Unique args: Guard against recursive types (#1090)

Also reported over in #1087, the unique module will overflow if
encountering a recursive type as it looks for unique keys to consider.

Here, try to be a little smarter about this, but not overly so by only
processing each type once. This means that inner recursive types always
just get treatment as a fully encoded JSON blob, but that's about as
good of a way to handle them as I can think of anyway.

Take this example:

    type RecursiveType struct {
            NotUnique string         `river:"-"`
            Recursive *RecursiveType `river:"unique"` // inner recursive type ignored by River
            String    string         `river:"unique"`
    }
    type TaskJobArgs struct {
            JobArgsStaticKind

            Recursive RecursiveType `river:"unique"`
    }
    return TaskJobArgs{
            JobArgsStaticKind: JobArgsStaticKind{kind: "worker_7"},
            Recursive: RecursiveType{
                    Recursive: &RecursiveType{
                            String: "level2",
                    },
                    String: "level1",
            },
    }

Generated output is:

    &kind=worker_7&args={"Recursive":{"Recursive":{"NotUnique":"","Recursive":null,"String":"level2"},"String":"level1"}}

Notably, we see "NotUnique" show up in the inner recursive type because
River has given up processing that and just treated the entire inner
"Recursive" as a JSON value. The outer type does not have "NotUnique"
because River saw the `river:"-"` annotation and knew not to treat it as
unique.

Author: brandur

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Unique args: Handle embedded fields that are not structs. [PR #1088](https://github.com/riverqueue/river/pull/1088).
+- Fix stack overflow when handling `river:"unique"` annotations on recursive types. [PR #1090](https://github.com/riverqueue/river/pull/1090).
 
 ## [0.27.0] - 2025-11-14
 

internal/dbunique/db_unique_test.go

@@ -360,6 +360,39 @@ func TestUniqueKey(t *testing.T) {
 			// args JSON should be sorted alphabetically:
 			expectedJSON: `&kind=worker_1&args={}`,
 		},
+		{
+			name: "ByArgsRecursiveType",
+			argsFunc: func() rivertype.JobArgs {
+				type RecursiveType struct {
+					NotUnique string         `river:"-"`
+					Recursive *RecursiveType `river:"unique"` // inner recursive type ignored by River
+					String    string         `river:"unique"`
+				}
+				type TaskJobArgs struct {
+					JobArgsStaticKind
+
+					Recursive RecursiveType `river:"unique"`
+				}
+				return TaskJobArgs{
+					JobArgsStaticKind: JobArgsStaticKind{kind: "worker_7"},
+					Recursive: RecursiveType{
+						Recursive: &RecursiveType{
+							String: "level2",
+						},
+						String: "level1",
+					},
+				}
+			},
+			uniqueOpts: UniqueOpts{ByArgs: true},
+
+			// Notably, "NotUnique" shows up here inside the inner recursive
+			// type because when River saw the recursive typed markd with
+			// `unique` again, it just gave up and returned the entire the
+			// entire key which is then extracted by gjson. The top-level type
+			// also has a "NotUnique", but that's not returned because River was
+			// processing this type for the first time.
+			expectedJSON: `&kind=worker_7&args={"Recursive":{"Recursive":{"NotUnique":"","Recursive":null,"String":"level2"},"String":"level1"}}`,
+		},
 		{
 			name: "CustomByStateWithPeriod",
 			argsFunc: func() rivertype.JobArgs {

internal/dbunique/unique_fields.go

@@ -42,7 +42,10 @@ func extractUniqueValues(encodedArgs []byte, uniqueKeys []string) []string {
 // getSortedUniqueFields uses reflection to retrieve the JSON keys of fields
 // marked with `river:"unique"` among potentially other comma-separated values.
 // The return values are the JSON keys using the same logic as the `json` struct tag.
-func getSortedUniqueFields(typ reflect.Type, path []string) ([]string, error) {
+//
+// typesSeen should be a map passed through to make sure that recursive types
+// don't cause a stack overflow.
+func getSortedUniqueFields(typ reflect.Type, path []string, typesSeen map[reflect.Type]struct{}) ([]string, error) {
 	// Handle pointer to struct
 	if typ.Kind() == reflect.Ptr {
 		typ = typ.Elem()
@@ -53,6 +56,14 @@ func getSortedUniqueFields(typ reflect.Type, path []string) ([]string, error) {
 		return nil, fmt.Errorf("expected struct, got %T", typ.Name())
 	}
 
+	// Stop when encountering a recursive type. This has the effect of the
+	// entire subfield's value being extracted by gjson, but this is about as
+	// right of a way to handle it as any other I can think of.
+	if _, ok := typesSeen[typ]; ok {
+		return nil, nil
+	}
+	typesSeen[typ] = struct{}{}
+
 	var uniqueFields []string
 
 	// Iterate over all fields
@@ -97,7 +108,7 @@ func getSortedUniqueFields(typ reflect.Type, path []string) ([]string, error) {
 				fullPath = append(path, uniqueName) //nolint:gocritic
 			}
 
-			uniqueSubFields, err := getSortedUniqueFields(field.Type, fullPath)
+			uniqueSubFields, err := getSortedUniqueFields(field.Type, fullPath, typesSeen)
 			if err != nil {
 				return nil, err
 			}
@@ -140,7 +151,7 @@ func getSortedUniqueFieldsCached(args rivertype.JobArgs) ([]string, error) {
 	cacheMutex.RUnlock()
 
 	// Not in cache; retrieve using reflection
-	fields, err := getSortedUniqueFields(reflect.TypeOf(args), nil)
+	fields, err := getSortedUniqueFields(reflect.TypeOf(args), nil, make(map[reflect.Type]struct{}))
 	if err != nil {
 		return nil, err
 	}