Fix stack overflow on circular schema refs in clearSchemaRefs

Signed-off-by: Guan-Ming (Wesley) Chiu <105915352+guan404ming@users.noreply.github.com>

Author: guan404ming

utils/component/openapi_generator.go

@@ -196,9 +196,9 @@ func getResolvedManifest(manifest string) (string, error) {
 	if doc.Components == nil || len(doc.Components.Schemas) == 0 {
 		return "", ErrNoSchemasFound
 	}
-	visited := make(map[*openapi3.SchemaRef]bool)
+	stack := make(map[*openapi3.Schema]bool)
 	for _, schemaRef := range doc.Components.Schemas {
-		clearSchemaRefs(schemaRef, visited)
+		clearSchemaRefs(schemaRef, stack)
 	}
 	resolved, err := json.Marshal(doc)
 	if err != nil {
@@ -208,35 +208,43 @@ func getResolvedManifest(manifest string) (string, error) {
 }
 
 // clearSchemaRefs recursively clears $ref strings on all nested SchemaRefs
-// so that json.Marshal outputs fully inlined schemas. The visited set
-// prevents infinite recursion on circular references.
-func clearSchemaRefs(sr *openapi3.SchemaRef, visited map[*openapi3.SchemaRef]bool) {
-	if sr == nil || visited[sr] {
+// so that json.Marshal outputs fully inlined schemas. The stack set tracks
+// Schema values (not SchemaRef pointers) on the current recursion path to
+// detect circular references. kin-openapi resolves $refs by creating
+// different SchemaRef objects that share the same underlying Schema pointer,
+// so tracking by *Schema is necessary to catch all cycles.
+func clearSchemaRefs(sr *openapi3.SchemaRef, stack map[*openapi3.Schema]bool) {
+	if sr == nil {
 		return
 	}
-	visited[sr] = true
 	sr.Ref = ""
 	s := sr.Value
 	if s == nil {
 		return
 	}
+	if stack[s] {
+		sr.Value = &openapi3.Schema{}
+		return
+	}
+	stack[s] = true
 	for _, child := range s.AllOf {
-		clearSchemaRefs(child, visited)
+		clearSchemaRefs(child, stack)
 	}
 	for _, child := range s.AnyOf {
-		clearSchemaRefs(child, visited)
+		clearSchemaRefs(child, stack)
 	}
 	for _, child := range s.OneOf {
-		clearSchemaRefs(child, visited)
+		clearSchemaRefs(child, stack)
 	}
-	clearSchemaRefs(s.Not, visited)
+	clearSchemaRefs(s.Not, stack)
 	if s.Items != nil {
-		clearSchemaRefs(s.Items, visited)
+		clearSchemaRefs(s.Items, stack)
 	}
 	for _, prop := range s.Properties {
-		clearSchemaRefs(prop, visited)
+		clearSchemaRefs(prop, stack)
 	}
 	if s.AdditionalProperties.Schema != nil {
-		clearSchemaRefs(s.AdditionalProperties.Schema, visited)
+		clearSchemaRefs(s.AdditionalProperties.Schema, stack)
 	}
+	delete(stack, s)
 }

utils/component/openapi_generator_integration_test.go

@@ -0,0 +1,40 @@
+package component
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+)
+
+// TestGetResolvedManifest_RealKubernetesSpec downloads the actual Kubernetes
+// OpenAPI spec and runs it through getResolvedManifest to verify that circular
+// references (e.g. JSONSchemaProps) do not cause a stack overflow.
+func TestGetResolvedManifest_RealKubernetesSpec(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	// apiextensions spec contains JSONSchemaProps which references itself circularly.
+	const specURL = "https://raw.githubusercontent.com/kubernetes/kubernetes/release-1.32/api/openapi-spec/v3/apis__apiextensions.k8s.io__v1_openapi.json"
+	resp, err := http.Get(specURL)
+	if err != nil {
+		t.Fatalf("failed to fetch kubernetes spec: %v", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("failed to read response body: %v", err)
+	}
+
+	out, err := getResolvedManifest(string(body))
+	if err != nil {
+		t.Fatalf("getResolvedManifest failed: %v", err)
+	}
+
+	if len(out) == 0 {
+		t.Fatal("expected non-empty output")
+	}
+	fmt.Printf("resolved manifest length: %d bytes\n", len(out))
+}

utils/component/openapi_generator_test.go

@@ -169,6 +169,50 @@ components:
 			wantErr:   true,
 			errSubstr: "",
 		},
+		{
+			name: "Self-referencing schema like JSONSchemaProps does not stack overflow",
+			input: `{
+				"openapi": "3.0.0",
+				"info": {"title": "k8s-like", "version": "1.0"},
+				"paths": {},
+				"components": {
+					"schemas": {
+						"JSONSchemaProps": {
+							"type": "object",
+							"properties": {
+								"description": {"type": "string"},
+								"properties": {
+									"type": "object",
+									"additionalProperties": {"$ref": "#/components/schemas/JSONSchemaProps"}
+								},
+								"items": {
+									"$ref": "#/components/schemas/JSONSchemaPropsOrArray"
+								},
+								"not": {
+									"$ref": "#/components/schemas/JSONSchemaProps"
+								},
+								"allOf": {
+									"type": "array",
+									"items": {"$ref": "#/components/schemas/JSONSchemaProps"}
+								}
+							}
+						},
+						"JSONSchemaPropsOrArray": {
+							"type": "object",
+							"properties": {
+								"schema": {"$ref": "#/components/schemas/JSONSchemaProps"},
+								"jsonSchemas": {
+									"type": "array",
+									"items": {"$ref": "#/components/schemas/JSONSchemaProps"}
+								}
+							}
+						}
+					}
+				}
+			}`,
+			checkPath: "components.schemas.JSONSchemaProps.properties.description",
+			wantType:  "string",
+		},
 	}
 
 	for _, tt := range tests {
@@ -278,7 +322,7 @@ func TestClearSchemaRefs(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			visited := make(map[*openapi3.SchemaRef]bool)
+			visited := make(map[*openapi3.Schema]bool)
 			clearSchemaRefs(tt.sr, visited)
 			if tt.sr != nil && tt.sr.Ref != "" {
 				t.Errorf("Ref = %q, want empty", tt.sr.Ref)
@@ -294,15 +338,36 @@ func TestClearSchemaRefs_Circular(t *testing.T) {
 	a.Value.Properties = openapi3.Schemas{"b": b}
 	b.Value.Properties = openapi3.Schemas{"a": a}
 
-	visited := make(map[*openapi3.SchemaRef]bool)
-	clearSchemaRefs(a, visited) // must not hang or panic
+	stack := make(map[*openapi3.Schema]bool)
+	clearSchemaRefs(a, stack) // must not hang or panic
 
 	if a.Ref != "" {
 		t.Errorf("a.Ref = %q, want empty", a.Ref)
 	}
 	if b.Ref != "" {
 		t.Errorf("b.Ref = %q, want empty", b.Ref)
 	}
+
+	// json.Marshal must not stack overflow on the cleared structure.
+	if _, err := json.Marshal(a); err != nil {
+		t.Fatalf("json.Marshal failed after clearing circular refs: %v", err)
+	}
+}
+
+func TestClearSchemaRefs_SelfReference(t *testing.T) {
+	// Schema that references itself (like JSONSchemaProps).
+	self := &openapi3.SchemaRef{Value: &openapi3.Schema{
+		Type: &openapi3.Types{"object"},
+	}}
+	self.Value.Properties = openapi3.Schemas{"nested": self}
+
+	stack := make(map[*openapi3.Schema]bool)
+	clearSchemaRefs(self, stack)
+
+	// The self-referencing property should be replaced, breaking the cycle.
+	if _, err := json.Marshal(self); err != nil {
+		t.Fatalf("json.Marshal failed on self-referencing schema: %v", err)
+	}
 }
 
 // navigatePath walks a dot-separated path through nested maps.