jsonschema: Add caching, documentation, and version pinning support

internal/config/validation_schema.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"regexp"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/githubnext/gh-aw-mcpg/internal/config/rules"
@@ -26,6 +27,26 @@ var (
 
 	// logSchema is the debug logger for schema validation
 	logSchema = logger.New("config:validation_schema")
+
+	// Schema URL configuration
+	// This URL points to the source of truth for the MCP Gateway configuration schema.
+	//
+	// Build Reproducibility:
+	// For production builds, consider pinning to a specific commit SHA or version tag:
+	//   - Commit SHA: "https://raw.githubusercontent.com/githubnext/gh-aw/<commit-sha>/docs/public/schemas/mcp-gateway-config.schema.json"
+	//   - Version tag: "https://raw.githubusercontent.com/githubnext/gh-aw/v1.0.0/docs/public/schemas/mcp-gateway-config.schema.json"
+	//
+	// Using 'main' branch ensures we always use the latest schema but may introduce
+	// changes that break builds. For stable releases, pin to a specific version.
+	//
+	// Alternative: Embed the schema using go:embed directive for zero network dependency.
+	schemaURL = "https://raw.githubusercontent.com/githubnext/gh-aw/main/docs/public/schemas/mcp-gateway-config.schema.json"
+
+	// Schema caching to avoid recompiling the JSON schema on every validation
+	// This improves performance by compiling the schema once and reusing it
+	schemaOnce   sync.Once
+	cachedSchema *jsonschema.Schema
+	schemaErr    error
 )
 
 // SetGatewayVersion sets the gateway version for error reporting
@@ -35,8 +56,34 @@ func SetGatewayVersion(version string) {
 	}
 }
 
-// fetchAndFixSchema fetches the JSON schema from the remote URL and fixes
-// regex patterns that use negative lookahead (not supported in JSON Schema Draft 7)
+// fetchAndFixSchema fetches the JSON schema from the remote URL and applies
+// workarounds for JSON Schema Draft 7 limitations.
+//
+// Background:
+// The MCP Gateway configuration schema uses regex patterns with negative lookahead
+// assertions (e.g., "(?!stdio|http)") to exclude specific values. However, JSON Schema
+// Draft 7's pattern validation uses ECMA-262 regex syntax, which does not support
+// negative lookahead in all implementations.
+//
+// Workaround Strategy:
+// Instead of using pattern-based exclusions, we replace them with semantic equivalents:
+//
+//  1. For customServerConfig.type:
+//     - Original: pattern: "^(?!stdio$|http$).*"
+//     - Fixed: not: { enum: ["stdio", "http"] }
+//     - This achieves the same validation goal using JSON Schema's "not" keyword
+//
+//  2. For customSchemas patternProperties:
+//     - Original: "^(?!stdio$|http$)[a-z][a-z0-9-]*$"
+//     - Fixed: "^[a-z][a-z0-9-]*$" (combined with oneOf constraint)
+//     - The oneOf logic in the schema ensures stdio/http are validated separately
+//
+// These replacements maintain semantic equivalence while using only Draft 7 features.
+//
+// Future Consideration:
+// TODO: Investigate if JSON Schema v6 (library upgrade) or Draft 2019-09+/2020-12
+// (newer spec) eliminate this workaround. The jsonschema/v6 Go library may handle
+// these patterns natively, potentially allowing removal of this function entirely.
 func fetchAndFixSchema(url string) ([]byte, error) {
 	logSchema.Printf("Fetching schema from URL: %s", url)
 
@@ -118,53 +165,79 @@ func fetchAndFixSchema(url string) ([]byte, error) {
 	return fixedBytes, nil
 }
 
-// validateJSONSchema validates the raw JSON configuration against the JSON schema
-func validateJSONSchema(data []byte) error {
-	logSchema.Printf("Starting JSON schema validation: data_size=%d bytes", len(data))
-
-	// Fetch the schema from the remote URL (source of truth)
-	schemaURL := "https://raw.githubusercontent.com/githubnext/gh-aw/main/docs/public/schemas/mcp-gateway-config.schema.json"
-	schemaJSON, err := fetchAndFixSchema(schemaURL)
-	if err != nil {
-		return fmt.Errorf("failed to fetch schema: %w", err)
-	}
+// getOrCompileSchema retrieves the cached compiled schema or compiles it on first use.
+// This function uses sync.Once to ensure thread-safe, one-time schema compilation,
+// which significantly improves performance by avoiding repeated schema fetching and
+// compilation on every validation call.
+//
+// The schema is fetched from the remote URL on first call and cached for subsequent uses.
+// If schema compilation fails, the error is also cached to avoid repeated fetch attempts.
+//
+// Returns:
+//   - Compiled JSON schema on success
+//   - Error if schema fetch or compilation fails
+func getOrCompileSchema() (*jsonschema.Schema, error) {
+	schemaOnce.Do(func() {
+		logSchema.Print("Compiling JSON schema for the first time")
+
+		// Fetch the schema from the configured URL
+		schemaJSON, fetchErr := fetchAndFixSchema(schemaURL)
+		if fetchErr != nil {
+			schemaErr = fmt.Errorf("failed to fetch schema: %w", fetchErr)
+			logSchema.Printf("Schema compilation failed: %v", schemaErr)
+			return
+		}
 
-	// Parse the schema
-	var schemaData interface{}
-	if err := json.Unmarshal(schemaJSON, &schemaData); err != nil {
-		return fmt.Errorf("failed to parse schema: %w", err)
-	}
+		// Parse the schema to extract its $id
+		var schemaObj map[string]interface{}
+		if parseErr := json.Unmarshal(schemaJSON, &schemaObj); parseErr != nil {
+			schemaErr = fmt.Errorf("failed to parse schema JSON: %w", parseErr)
+			return
+		}
 
-	// Compile the schema
-	compiler := jsonschema.NewCompiler()
-	compiler.Draft = jsonschema.Draft7
+		schemaID, ok := schemaObj["$id"].(string)
+		if !ok || schemaID == "" {
+			schemaID = schemaURL
+		}
 
-	// Add the schema with its $id from the remote schema
-	// Note: The remote schema uses https://docs.github.com/gh-aw/schemas/mcp-gateway-config.schema.json
-	// as its $id, so we need to register it there as well
-	var schemaObj map[string]interface{}
-	if err := json.Unmarshal(schemaJSON, &schemaObj); err != nil {
-		return fmt.Errorf("failed to parse schema JSON: %w", err)
-	}
+		// Compile the schema
+		compiler := jsonschema.NewCompiler()
+		compiler.Draft = jsonschema.Draft7
 
-	schemaID, ok := schemaObj["$id"].(string)
-	if !ok || schemaID == "" {
-		schemaID = schemaURL
-	}
+		// Add the schema with both URLs (the fetch URL and the $id URL)
+		// This ensures references work correctly regardless of which URL is used
+		if addErr := compiler.AddResource(schemaURL, strings.NewReader(string(schemaJSON))); addErr != nil {
+			schemaErr = fmt.Errorf("failed to add schema resource: %w", addErr)
+			return
+		}
+		if schemaID != schemaURL {
+			if addErr := compiler.AddResource(schemaID, strings.NewReader(string(schemaJSON))); addErr != nil {
+				schemaErr = fmt.Errorf("failed to add schema resource with $id: %w", addErr)
+				return
+			}
+		}
 
-	// Add the schema with both URLs
-	if err := compiler.AddResource(schemaURL, strings.NewReader(string(schemaJSON))); err != nil {
-		return fmt.Errorf("failed to add schema resource: %w", err)
-	}
-	if schemaID != schemaURL {
-		if err := compiler.AddResource(schemaID, strings.NewReader(string(schemaJSON))); err != nil {
-			return fmt.Errorf("failed to add schema resource with $id: %w", err)
+		cachedSchema, schemaErr = compiler.Compile(schemaID)
+		if schemaErr != nil {
+			schemaErr = fmt.Errorf("failed to compile schema: %w", schemaErr)
+			logSchema.Printf("Schema compilation failed: %v", schemaErr)
+			return
 		}
-	}
 
-	schema, err := compiler.Compile(schemaID)
+		logSchema.Print("Schema compiled and cached successfully")
+	})
+
+	return cachedSchema, schemaErr
+}
+
+// validateJSONSchema validates the raw JSON configuration against the JSON schema
+func validateJSONSchema(data []byte) error {
+	logSchema.Printf("Starting JSON schema validation: data_size=%d bytes", len(data))
+
+	// Get the cached compiled schema (or compile it on first use)
+	schema, err := getOrCompileSchema()
 	if err != nil {
-		return fmt.Errorf("failed to compile schema: %w", err)
+		return err
 	}
 
 	// Parse the configuration

internal/config/validation_schema_test.go

@@ -618,3 +618,78 @@ func TestEnhancedErrorMessages(t *testing.T) {
 		})
 	}
 }
+
+// TestSchemaCaching verifies that the schema is compiled once and cached for reuse
+func TestSchemaCaching(t *testing.T) {
+	// Note: We can't fully reset the package-level sync.Once, but we can verify
+	// that multiple calls to getOrCompileSchema return the same schema instance
+
+	schema1, err1 := getOrCompileSchema()
+	assert.NoError(t, err1, "First schema compilation should succeed")
+	assert.NotNil(t, schema1, "First schema should not be nil")
+
+	schema2, err2 := getOrCompileSchema()
+	assert.NoError(t, err2, "Second schema retrieval should succeed")
+	assert.NotNil(t, schema2, "Second schema should not be nil")
+
+	// Verify that both calls return the exact same schema instance (pointer equality)
+	// This confirms caching is working correctly
+	if schema1 != schema2 {
+		t.Error("Expected both calls to return the same cached schema instance")
+	}
+
+	// Verify the cached schema can actually validate configurations
+	validConfig := `{
+"mcpServers": {
+"test": {
+"container": "ghcr.io/test/server:latest"
+}
+},
+"gateway": {
+"port": 8080,
+"domain": "localhost",
+"apiKey": "test-key"
+}
+}`
+
+	err := validateJSONSchema([]byte(validConfig))
+	assert.NoError(t, err, "Validation with cached schema should succeed")
+}
+
+// TestSchemaURLConfiguration verifies that the schema URL is configurable
+func TestSchemaURLConfiguration(t *testing.T) {
+	// Verify the schema URL is properly set
+	// This test documents the schema URL configuration for version pinning
+
+	// The current implementation uses 'main' branch
+	// For production, consider pinning to a specific commit SHA or version tag
+	expectedPattern := "https://raw.githubusercontent.com/githubnext/gh-aw/"
+
+	// We can't directly test the package-level schemaURL variable,
+	// but we can verify that the schema compiles and validates correctly
+	schema, err := getOrCompileSchema()
+	assert.NoError(t, err, "Schema compilation should succeed")
+	assert.NotNil(t, schema, "Schema should not be nil")
+
+	// Verify that the schema works for validation
+	validConfig := `{
+"mcpServers": {
+"test": {
+"container": "ghcr.io/test/server:latest"
+}
+},
+"gateway": {
+"port": 8080,
+"domain": "localhost",
+"apiKey": "test-key"
+}
+}`
+
+	err = validateJSONSchema([]byte(validConfig))
+	assert.NoError(t, err, "Validation should succeed with configured schema URL")
+
+	// Document the version pinning approach in test output
+	t.Logf("Schema URL pattern: %s", expectedPattern)
+	t.Logf("For production builds, consider pinning to: %s<commit-sha>/...", expectedPattern)
+	t.Logf("Or use a version tag: %sv1.0.0/...", expectedPattern)
+}