v1/topdown/graphql: Cache GraphQL schema parse results (open-policy-agent#5377)

This commit stores parsed GraphQL schemas to the cache, which improves
the performance of GraphQL operations that parse the schema more than once.

Rough Draft Complete:
  - graphql.schema_is_valid

TODO:
  - graphql.is_valid
  - graphql.parse
  - graphql.parse_and_verify
  - graphql.parse_query
  - graphql.parse_schema

goarch: amd64
pkg: github.com/open-policy-agent/opa/v1/topdown
cpu: Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
BenchmarkGraphQLSchemaIsValid/Trivial_Schema_-_string-16                     	   16966	     68579 ns/op
BenchmarkGraphQLSchemaIsValid/Trivial_Schema_with_cache_-_string-16         	 1000000	      1062 ns/op
BenchmarkGraphQLSchemaIsValid/Trivial_Schema_-_object-16                    	   12900	     92484 ns/op
BenchmarkGraphQLSchemaIsValid/Trivial_Schema_with_cache_-_object-16         	   92516	     12064 ns/op
BenchmarkGraphQLSchemaIsValid/Complex_Schema_-_string-16                    	      60	  19294987 ns/op
BenchmarkGraphQLSchemaIsValid/Complex_Schema_with_cache_-_string-16         	     342	   3443940 ns/op
PASS
ok  	github.com/open-policy-agent/opa/v1/topdown	12.613s

Fixes: open-policy-agent#5377

Author: robmyersrobmyers

Diff for: docs/content/configuration.md

@@ -861,14 +861,15 @@ Caching represents the configuration of the inter-query cache that built-in func
 functions provided by OPA, `http.send` is currently the only one to utilize the inter-query cache. See the documentation
 on the [http.send built-in function](../policy-reference/#http) for information about the available caching options.
 
-It also represents the configuration of the inter-query _value_ cache that built-in functions can utilize. Currently, 
+It also represents the configuration of the inter-query _value_ cache that built-in functions can utilize. Currently,
 this cache is utilized by the `regex` and `glob` built-in functions for compiled regex and glob match patterns
-respectively, and the `json.schema_match` built-in function for compiled JSON schemas.
+respectively, the `json.schema_match` built-in function for compiled JSON schemas, and the `graphql.schema_is_valid`
+function for parsed GraphQL schemas.
 
 | Field                                                                    | Type    | Required | Description                                                                                                                                                                                                                                          |
 |--------------------------------------------------------------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `caching.inter_query_builtin_cache.max_size_bytes`                       | `int64` | No       | Inter-query cache size limit in bytes. OPA will drop old items from the cache if this limit is exceeded. By default, no limit is set.                                                                                                                |
-| `caching.inter_query_builtin_cache.forced_eviction_threshold_percentage` | `int64` | No       | Threshold limit configured as percentage of `caching.inter_query_builtin_cache.max_size_bytes`, when exceeded OPA will start dropping old items permaturely. By default, set to `100`.                                                               |
+| `caching.inter_query_builtin_cache.forced_eviction_threshold_percentage` | `int64` | No       | Threshold limit configured as percentage of `caching.inter_query_builtin_cache.max_size_bytes`, when exceeded OPA will start dropping old items prematurely. By default, set to `100`.                                                               |
 | `caching.inter_query_builtin_cache.stale_entry_eviction_period_seconds`  | `int64` | No       | Stale entry eviction period in seconds. OPA will drop expired items from the cache every `stale_entry_eviction_period_seconds`. By default, set to `0` indicating stale entry eviction is disabled.                                                  |
 | `caching.inter_query_builtin_value_cache.max_num_entries`                | `int`   | No       | Maximum number of entries in the Inter-query value cache. OPA will drop random items from the cache if this limit is exceeded. By default, set to `0` indicating unlimited size.                                                                     |
 | `caching.inter_query_builtin_value_cache.named.io_jwt.max_num_entries`   | `int`   | No       | Maximum number of entries in the `io_jwt` cache, used by the [`io.jwt` token verification](../policy-reference/#tokens) built-in functions. OPA will drop random items from the cache if this limit is exceeded. By default, this cache is disabled. |

Diff for: v1/topdown/.gitignore

@@ -0,0 +1 @@
+complex-schema.gql

Diff for: v1/topdown/graphql.go

@@ -453,28 +453,91 @@ func builtinGraphQLIsValid(_ BuiltinContext, operands []*ast.Term, iter func(*as
 	return iter(ast.InternedBooleanTerm(true))
 }
 
-func builtinGraphQLSchemaIsValid(_ BuiltinContext, operands []*ast.Term, iter func(*ast.Term) error) error {
-	var schemaDoc *gqlast.SchemaDocument
+func builtinGraphQLSchemaIsValid(bctx BuiltinContext, operands []*ast.Term, iter func(*ast.Term) error) error {
 	var err error
 
-	switch x := operands[0].Value.(type) {
-	case ast.String:
-		schemaDoc, err = parseSchema(string(x))
-	case ast.Object:
-		schemaDoc, err = objectToSchemaDocument(x)
-	default:
-		// Error if wrong type.
-		return iter(ast.InternedBooleanTerm(false))
-	}
-	if err != nil {
-		return iter(ast.InternedBooleanTerm(false))
+	// Schemas are only cached if they are valid
+	schemaCacheKey, schema := cacheGetSchema(bctx, operands)
+	if schema == nil {
+		var schemaDoc *gqlast.SchemaDocument
+		var validatedSchema *gqlast.Schema
+
+		switch x := operands[0].Value.(type) {
+		case ast.String:
+			schemaDoc, err = parseSchema(string(x))
+		case ast.Object:
+			schemaDoc, err = objectToSchemaDocument(x)
+		default:
+			// Error if wrong type.
+			return iter(ast.InternedBooleanTerm(false))
+		}
+		if err != nil {
+			return iter(ast.InternedBooleanTerm(false))
+		}
+		// Validate the schema, this determines the result
+		// and whether there is a schema to cache
+		validatedSchema, err = convertSchema(schemaDoc)
+		if bctx.InterQueryBuiltinValueCache != nil && err == nil {
+			cacheInsertSchema(bctx, schemaCacheKey, validatedSchema)
+		}
 	}
 
-	// Validate the schema, this determines the result
-	_, err = convertSchema(schemaDoc)
 	return iter(ast.InternedBooleanTerm(err == nil))
 }
 
+// Insert Schema into cache
+func cacheInsertSchema(bctx BuiltinContext, key string, schema *gqlast.Schema) int {
+	cacheKeyAST := ast.StringTerm(key).Value
+	numDroppedEntries := bctx.InterQueryBuiltinValueCache.Insert(cacheKeyAST, schema)
+	return numDroppedEntries
+}
+
+// Returns the cache key and a Schema if this key already exists in the cache
+func cacheGetSchema(bctx BuiltinContext, operands []*ast.Term) (string, *gqlast.Schema) {
+	var key string
+	var schema *gqlast.Schema
+
+	if k, keyOk := cacheKeyWithPrefix(bctx, operands, "gql_schema"); keyOk {
+		key = k
+		if val, ok := bctx.InterQueryBuiltinValueCache.Get(ast.StringTerm(key).Value); ok {
+			var isSchema bool
+			schema, isSchema = val.(*gqlast.Schema)
+			if !isSchema {
+				return key, nil
+			}
+		}
+	}
+	return key, schema
+}
+
+// Compute a constant size key for use with the cache
+func cacheKeyWithPrefix(bctx BuiltinContext, operands []*ast.Term, prefix string) (string, bool) {
+	var cacheKey ast.String
+	var ok bool = false
+
+	if bctx.InterQueryBuiltinValueCache != nil {
+		switch operands[0].Value.(type) {
+		case ast.String:
+			err := builtinCryptoSha256(bctx, operands, func(term *ast.Term) error {
+				cacheKey = term.Value.(ast.String)
+				return nil
+			})
+			ok = (len(cacheKey) > 0) && (err == nil)
+		case ast.Object:
+			objTerm := ast.NewTerm(ast.String(operands[0].String()))
+			err := builtinCryptoSha256(bctx, []*ast.Term{objTerm}, func(term *ast.Term) error {
+				cacheKey = term.Value.(ast.String)
+				return nil
+			})
+			ok = (len(cacheKey) > 0) && (err == nil)
+		default:
+			ok = false
+		}
+	}
+
+	return prefix + "-" + string(cacheKey), ok
+}
+
 func init() {
 	RegisterBuiltinFunc(ast.GraphQLParse.Name, builtinGraphQLParse)
 	RegisterBuiltinFunc(ast.GraphQLParseAndVerify.Name, builtinGraphQLParseAndVerify)

Diff for: v1/topdown/graphql_bench_test.go

@@ -0,0 +1,76 @@
+// Copyright 2025 The OPA Authors.  All rights reserved.
+// Use of this source code is governed by an Apache2
+// license that can be found in the LICENSE file.
+
+package topdown
+
+import (
+	"context"
+	_ "embed"
+	"testing"
+
+	"github.com/open-policy-agent/opa/v1/ast"
+	"github.com/open-policy-agent/opa/v1/topdown/cache"
+)
+
+// employeeGQLSchema is a simple schema defined in graphql_test.go
+//
+// If you don't have your own complex GQL schema you can use the
+// [GitHub GraphQL Schema](https://docs.github.com/en/graphql) for more realistic performance testing
+//
+// Download the schema with curl -o complex-schema.gql -L https://docs.github.com/public/fpt/schema.docs.graphql
+// and use embed so we don't include an extra 2+M in source tree.
+//
+//go:embed complex-schema.gql
+var complexGQLSchema string
+
+// graphqurl --introspect https://api.github.com/graphql -H "Authorization: bearer $GITHUB_TOKEN" --format=json > complex-schema.json
+//
+//go:embed complex-schema.json
+var complexGQLSchemaJSON string
+
+func BenchmarkGraphQLSchemaIsValid(b *testing.B) {
+
+	// Share an InterQueryValueCache across multiple runs
+	// Tune number of entries to exceed number of distinct GQL schemas
+	in := `{"inter_query_builtin_value_cache": {"max_num_entries": 10},}`
+	config, _ := cache.ParseCachingConfig([]byte(in))
+	valueCache := cache.NewInterQueryValueCache(context.Background(), config)
+
+	benches := []struct {
+		desc   string
+		schema *ast.Term
+		cache  cache.InterQueryValueCache
+	}{
+		{"Trivial Schema - string", ast.NewTerm(ast.String(employeeGQLSchema)), nil},
+		{"Trivial Schema with cache - string", ast.NewTerm(ast.String(employeeGQLSchema)), valueCache},
+		{"Trivial Schema - object", ast.NewTerm(ast.MustParseTerm(employeeGQLSchemaAST).Value.(ast.Object)), nil},
+		{"Trivial Schema with cache - object", ast.NewTerm(ast.MustParseTerm(employeeGQLSchemaAST).Value.(ast.Object)), valueCache},
+		{"Trivial Schema - AST JSON string", ast.NewTerm(ast.String(employeeGQLSchemaAST)), nil},
+		{"Trivial Schema with cache - AST JSON string", ast.NewTerm(ast.String(employeeGQLSchemaAST)), valueCache},
+		{"Complex Schema - string", ast.NewTerm(ast.String(complexGQLSchema)), nil},
+		{"Complex Schema with cache - string", ast.NewTerm(ast.String(complexGQLSchema)), valueCache},
+		{"Complex Schema - JSON string", ast.NewTerm(ast.String(complexGQLSchemaJSON)), nil},
+		{"Complex Schema with cache - JSON string", ast.NewTerm(ast.String(complexGQLSchemaJSON)), valueCache},
+	}
+
+	for _, bench := range benches {
+		b.Run(bench.desc, func(b *testing.B) {
+			for range b.N {
+				err := builtinGraphQLSchemaIsValid(
+					BuiltinContext{
+						InterQueryBuiltinValueCache: bench.cache,
+					},
+					[]*ast.Term{bench.schema},
+					func(term *ast.Term) error {
+						return nil
+					},
+				)
+
+				if err != nil {
+					b.Fatalf("unexpected error: %s", err)
+				}
+			}
+		})
+	}
+}