test(jsonrpc): add tests for positional decoding of parameters

Tests covers all structs declared in `params.go`, comparing positional
decoding against equivalent named decoding.

Author: renatomaia

internal/jsonrpc/api/params.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"encoding/json"
 	"fmt"
+	"reflect"
 )
 
 type StringOrList []string
@@ -221,3 +222,49 @@ type GetWithdrawalParams struct {
 	Application  string `json:"application"`
 	AccountIndex string `json:"account_index"`
 }
+
+// UnmarshalParams supports both by-name (object) and by-position (array) parameter structures.
+// If params is an object, it simply does json.Unmarshal; if it's an array, it will attempt
+// to unmarshal each positional parameter into the target struct field in declaration order.
+func UnmarshalParams(data json.RawMessage, target any) error {
+	data = bytes.TrimSpace(data)
+	if len(data) > 0 && data[0] == '[' {
+		// Unmarshal positional parameters into a slice of json.RawMessage.
+		var rawParams []json.RawMessage
+		if err := json.Unmarshal(data, &rawParams); err != nil {
+			return err
+		}
+		// Use reflection to set values in the target struct in the order they appear.
+		val := reflect.ValueOf(target)
+		if val.Kind() != reflect.Pointer || val.IsNil() {
+			return fmt.Errorf("error unmarshalling positional parameters target must be a non-nil pointer to a struct")
+		}
+		val = val.Elem()
+		if val.Kind() != reflect.Struct {
+			return fmt.Errorf("error unmarshalling positional parameters target must point to a struct")
+		}
+		typ := val.Type()
+		if len(rawParams) > typ.NumField() {
+			return fmt.Errorf("error unmarshalling positional parameters, expected %d params, got %d",
+				typ.NumField(), len(rawParams))
+		}
+		// For each field in the struct, if a positional parameter exists, unmarshal that parameter.
+		for i := 0; i < typ.NumField() && i < len(rawParams); i++ {
+			sf := typ.Field(i)
+			if sf.Tag.Get("json") == "-" {
+				continue
+			}
+			field := val.Field(i)
+			if !field.CanSet() {
+				return fmt.Errorf("error unmarshalling positional parameter field %q is not settable", typ.Field(i).Name)
+			}
+			// Unmarshal the corresponding raw parameter into the field.
+			if err := json.Unmarshal(rawParams[i], field.Addr().Interface()); err != nil {
+				return fmt.Errorf("error unmarshalling positional parameter %d for field %s: %w", i, typ.Field(i).Name, err)
+			}
+		}
+		return nil
+	}
+	// Otherwise, assume by-name structure.
+	return json.Unmarshal(data, target)
+}

internal/jsonrpc/api/params_test.go

@@ -83,3 +83,139 @@ func TestListOutputsParamsExecutedIsOptional(t *testing.T) {
 	require.NotNil(t, pending.Executed)
 	require.False(t, *pending.Executed)
 }
+
+func TestPositionalParamsDeclarationOrder(t *testing.T) {
+	tests := map[string]struct {
+		newTarget  func() any
+		positional string
+		named      string
+	}{
+		"ListApplicationsParams": {
+			func() any { return &ListApplicationsParams{} },
+			`[25,3,true]`,
+			`{"limit":25,"offset":3,"descending":true}`,
+		},
+		"GetApplicationParams": {
+			func() any { return &GetApplicationParams{} },
+			`["app"]`,
+			`{"application":"app"}`,
+		},
+		"ListEpochsParams": {
+			func() any { return &ListEpochsParams{} },
+			`["app",["OPEN","CLOSED"],25,3,true,"0x2","0x9"]`,
+			`{"application":"app","status":["OPEN","CLOSED"],"limit":25,"offset":3,"descending":true,"from":"0x2","to":"0x9"}`,
+		},
+		"GetEpochParams": {
+			func() any { return &GetEpochParams{} },
+			`["app","0x4"]`,
+			`{"application":"app","epoch_index":"0x4"}`,
+		},
+		"GetEpochByVirtualIndexParams": {
+			func() any { return &GetEpochByVirtualIndexParams{} },
+			`["app","0x7"]`,
+			`{"application":"app","virtual_index":"0x7"}`,
+		},
+		"GetLastAcceptedEpochIndexParams": {
+			func() any { return &GetLastAcceptedEpochIndexParams{} },
+			`["app"]`,
+			`{"application":"app"}`,
+		},
+		"ListInputsParams": {
+			func() any { return &ListInputsParams{} },
+			`["app","0x4","sender","transaction-hash",25,3,true,"0x2","0x9"]`,
+			`{"application":"app","epoch_index":"0x4","sender":"sender","transaction_hash":"transaction-hash","limit":25,"offset":3,"descending":true,"from":"0x2","to":"0x9"}`,
+		},
+		"GetInputParams": {
+			func() any { return &GetInputParams{} },
+			`["app","0x5"]`,
+			`{"application":"app","input_index":"0x5"}`,
+		},
+		"GetProcessedInputCountParams": {
+			func() any { return &GetProcessedInputCountParams{} },
+			`["app"]`,
+			`{"application":"app"}`,
+		},
+		"ListOutputsParams": {
+			func() any { return &ListOutputsParams{} },
+			`["app","0x4","0x5",["0x237a816f","0x10321e8b"],"voucher",25,3,true,"0x2","0x9",true]`,
+			`{"application":"app","epoch_index":"0x4","input_index":"0x5","output_type":["0x237a816f","0x10321e8b"],"voucher_address":"voucher","limit":25,"offset":3,"descending":true,"from":"0x2","to":"0x9","executed":true}`,
+		},
+		"GetOutputParams": {
+			func() any { return &GetOutputParams{} },
+			`["app","0x6"]`,
+			`{"application":"app","output_index":"0x6"}`,
+		},
+		"ListReportsParams": {
+			func() any { return &ListReportsParams{} },
+			`["app","0x4","0x5",25,3,true,"0x2","0x9"]`,
+			`{"application":"app","epoch_index":"0x4","input_index":"0x5","limit":25,"offset":3,"descending":true,"from":"0x2","to":"0x9"}`,
+		},
+		"GetReportParams": {
+			func() any { return &GetReportParams{} },
+			`["app","0x7"]`,
+			`{"application":"app","report_index":"0x7"}`,
+		},
+		"ListTournamentsParams": {
+			func() any { return &ListTournamentsParams{} },
+			`["app","0x4","0x2","parent-tournament","parent-match",25,3,true]`,
+			`{"application":"app","epoch_index":"0x4","level":"0x2","parent_tournament_address":"parent-tournament","parent_match_id_hash":"parent-match","limit":25,"offset":3,"descending":true}`,
+		},
+		"GetTournamentParams": {
+			func() any { return &GetTournamentParams{} },
+			`["app","tournament"]`,
+			`{"application":"app","address":"tournament"}`,
+		},
+		"ListCommitmentsParams": {
+			func() any { return &ListCommitmentsParams{} },
+			`["app","0x4","tournament",25,3,true]`,
+			`{"application":"app","epoch_index":"0x4","tournament_address":"tournament","limit":25,"offset":3,"descending":true}`,
+		},
+		"GetCommitmentParams": {
+			func() any { return &GetCommitmentParams{} },
+			`["app","0x4","tournament","commitment"]`,
+			`{"application":"app","epoch_index":"0x4","tournament_address":"tournament","commitment":"commitment"}`,
+		},
+		"ListMatchesParams": {
+			func() any { return &ListMatchesParams{} },
+			`["app","0x4","tournament",25,3,true]`,
+			`{"application":"app","epoch_index":"0x4","tournament_address":"tournament","limit":25,"offset":3,"descending":true}`,
+		},
+		"GetMatchParams": {
+			func() any { return &GetMatchParams{} },
+			`["app","0x4","tournament","id-hash"]`,
+			`{"application":"app","epoch_index":"0x4","tournament_address":"tournament","id_hash":"id-hash"}`,
+		},
+		"ListMatchAdvancesParams": {
+			func() any { return &ListMatchAdvancesParams{} },
+			`["app","0x4","tournament","id-hash",25,3,true]`,
+			`{"application":"app","epoch_index":"0x4","tournament_address":"tournament","id_hash":"id-hash","limit":25,"offset":3,"descending":true}`,
+		},
+		"GetMatchAdvanceParams": {
+			func() any { return &GetMatchAdvanceParams{} },
+			`["app","0x4","tournament","id-hash","parent"]`,
+			`{"application":"app","epoch_index":"0x4","tournament_address":"tournament","id_hash":"id-hash","parent":"parent"}`,
+		},
+		"ListWithdrawalsParams": {
+			func() any { return &ListWithdrawalsParams{} },
+			`["app","0x8",25,3,true]`,
+			`{"application":"app","account_index":"0x8","limit":25,"offset":3,"descending":true}`,
+		},
+		"GetWithdrawalParams": {
+			func() any { return &GetWithdrawalParams{} },
+			`["app","0x8"]`,
+			`{"application":"app","account_index":"0x8"}`,
+		},
+	}
+
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			expected := test.newTarget()
+			require.NoError(t, json.Unmarshal([]byte(test.named), expected))
+
+			actual := test.newTarget()
+			require.NoError(t, UnmarshalParams(json.RawMessage(test.positional), actual))
+
+			require.Equal(t, expected, actual)
+		})
+	}
+}