test(resolve): entity-caching benchmarks (copy budget, overhead ladder, analytics)

Add Go benchmarks (bench_test files only, no production changes) covering the caching engine: the StructuralCopy helper primitives (L1/L2 read/write, with vs without transform), the Copy-Budget pair (caching vs non-caching merge paths so per-request copy overhead is measurable 1:1), the overhead ladder (Disabled / ConfiguredButDisabled / L1Only / L1L2_Miss / L1L2_Hit), and the analytics micro-benches (disabled vs enabled, field hashing).

Validates the design: ConfiguredButDisabled has identical allocs to Disabled (no guard leak), L1L2_Hit is cheaper than L1L2_Miss, and analytics adds zero allocations when off.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 2 people

v2/pkg/engine/resolve/cache_analytics_bench_test.go

@@ -0,0 +1,72 @@
+package resolve
+
+import (
+	"context"
+	"testing"
+
+	"github.com/cespare/xxhash/v2"
+)
+
+var cacheAnalyticsBenchSink uint64
+
+func BenchmarkCacheAnalytics_Disabled(b *testing.B) {
+	ctx := NewContext(context.Background())
+	ctx.ExecutionOptions.Caching.EnableCacheAnalytics = false
+	event := CacheKeyEvent{
+		Key:        `{"__typename":"User","key":{"id":"1"}}`,
+		EntityType: "User",
+		Hit:        true,
+		Bytes:      64,
+	}
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	for b.Loop() {
+		ctx.cacheAnalytics().recordL1Read(event)
+	}
+}
+
+func BenchmarkCacheAnalytics_Enabled(b *testing.B) {
+	ctx := NewContext(context.Background())
+	ctx.ExecutionOptions.Caching.EnableCacheAnalytics = true
+	collector := ctx.cacheAnalytics()
+	collector.l1Reads = make([]CacheKeyEvent, 0, 1024)
+	event := CacheKeyEvent{
+		Key:        `{"__typename":"User","key":{"id":"1"}}`,
+		EntityType: "User",
+		Hit:        true,
+		Bytes:      64,
+	}
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	for b.Loop() {
+		if len(collector.l1Reads) == cap(collector.l1Reads) {
+			collector.l1Reads = collector.l1Reads[:0]
+		}
+		collector.recordL1Read(event)
+	}
+}
+
+func BenchmarkCacheAnalytics_FieldHashing(b *testing.B) {
+	ctx := NewContext(context.Background())
+	ctx.ExecutionOptions.Caching.EnableCacheAnalytics = true
+	collector := ctx.cacheAnalytics()
+	collector.fieldHashes = make([]FieldHashEvent, 0, 1024)
+	fieldPath := []byte("User.profile.displayName")
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	for b.Loop() {
+		if len(collector.fieldHashes) == cap(collector.fieldHashes) {
+			collector.fieldHashes = collector.fieldHashes[:0]
+		}
+		hash := xxhash.Sum64(fieldPath)
+		collector.recordFieldHash(FieldHashEvent{
+			EntityType: "User",
+			FieldPath:  "profile.displayName",
+			Hash:       hash,
+		})
+		cacheAnalyticsBenchSink = hash
+	}
+}

v2/pkg/engine/resolve/caching_overhead_bench_test.go

@@ -0,0 +1,223 @@
+package resolve
+
+import (
+	"bytes"
+	"context"
+	"testing"
+)
+
+var cachingOverheadBenchSink string
+
+func BenchmarkCachingOverhead_Sequential(b *testing.B) {
+	b.Run("Disabled", func(b *testing.B) {
+		benchCachingOverheadSequential(b, &FetchCacheConfiguration{}, ResolverOptions{}, func(ctx *Context) {
+			ctx.ExecutionOptions.Caching = CachingOptions{
+				EnableL1Cache: false,
+				EnableL2Cache: false,
+			}
+		})
+	})
+	b.Run("ConfiguredButDisabled", func(b *testing.B) {
+		cache := batchUserNameCacheConfig(false)
+		cache.UseL1Cache = true
+		benchCachingOverheadSequential(b, cache, ResolverOptions{}, func(ctx *Context) {
+			ctx.ExecutionOptions.Caching = CachingOptions{
+				EnableL1Cache: false,
+				EnableL2Cache: false,
+			}
+		})
+	})
+	b.Run("L1Only", func(b *testing.B) {
+		cache := batchUserNameCacheConfig(false)
+		cache.EnableL2Cache = false
+		cache.UseL1Cache = true
+		benchCachingOverheadSequential(b, cache, ResolverOptions{}, func(ctx *Context) {
+			ctx.ExecutionOptions.Caching = CachingOptions{
+				EnableL1Cache: true,
+				EnableL2Cache: false,
+			}
+		})
+	})
+	b.Run("L1L2_Miss", func(b *testing.B) {
+		cacheBackend := newBenchLoaderCache()
+		cache := batchUserNameCacheConfig(false)
+		cache.UseL1Cache = true
+		benchCachingOverheadSequential(b, cache, ResolverOptions{
+			Caches: map[string]LoaderCache{"default": cacheBackend},
+		}, func(ctx *Context) {
+			cacheBackend.Clear()
+			ctx.ExecutionOptions.Caching = CachingOptions{
+				EnableL1Cache: true,
+				EnableL2Cache: true,
+			}
+		})
+	})
+	b.Run("L1L2_Hit", func(b *testing.B) {
+		cacheBackend := newBenchLoaderCache()
+		options := ResolverOptions{Caches: map[string]LoaderCache{"default": cacheBackend}}
+		cache := batchUserNameCacheConfig(false)
+		cache.UseL1Cache = true
+		response, cancel := newCachingOverheadBenchResponse(cache)
+		defer cancel()
+		resolver, shutdown := newCachingOverheadBenchResolver(options)
+		defer shutdown()
+		benchResolveGraphQLResponse(b, resolver, response, func(ctx *Context) {
+			ctx.ExecutionOptions.Caching = CachingOptions{
+				EnableL1Cache: true,
+				EnableL2Cache: true,
+			}
+		})
+		b.ReportAllocs()
+		b.ResetTimer()
+		for b.Loop() {
+			cachingOverheadBenchSink = benchResolveGraphQLResponse(b, resolver, response, func(ctx *Context) {
+				ctx.ExecutionOptions.Caching = CachingOptions{
+					EnableL1Cache: true,
+					EnableL2Cache: true,
+				}
+			})
+		}
+	})
+}
+
+func BenchmarkCachingOverhead_Analytics(b *testing.B) {
+	cacheBackend := newBenchLoaderCache()
+	options := ResolverOptions{Caches: map[string]LoaderCache{"default": cacheBackend}}
+	cache := batchUserNameCacheConfig(false)
+	cache.UseL1Cache = true
+	response, cancel := newCachingOverheadBenchResponse(cache)
+	defer cancel()
+	resolver, shutdown := newCachingOverheadBenchResolver(options)
+	defer shutdown()
+	benchResolveGraphQLResponse(b, resolver, response, func(ctx *Context) {
+		ctx.ExecutionOptions.Caching = CachingOptions{
+			EnableL1Cache: true,
+			EnableL2Cache: true,
+		}
+	})
+
+	b.Run("AnalyticsOff", func(b *testing.B) {
+		b.ReportAllocs()
+		b.ResetTimer()
+		for b.Loop() {
+			cachingOverheadBenchSink = benchResolveGraphQLResponse(b, resolver, response, func(ctx *Context) {
+				ctx.ExecutionOptions.Caching = CachingOptions{
+					EnableL1Cache: true,
+					EnableL2Cache: true,
+				}
+			})
+		}
+	})
+	b.Run("AnalyticsOn", func(b *testing.B) {
+		b.ReportAllocs()
+		b.ResetTimer()
+		for b.Loop() {
+			cachingOverheadBenchSink = benchResolveGraphQLResponse(b, resolver, response, func(ctx *Context) {
+				ctx.ExecutionOptions.Caching = CachingOptions{
+					EnableL1Cache:        true,
+					EnableL2Cache:        true,
+					EnableCacheAnalytics: true,
+				}
+			})
+		}
+	})
+}
+
+func benchCachingOverheadSequential(b *testing.B, cache *FetchCacheConfiguration, options ResolverOptions, configure func(*Context)) {
+	b.Helper()
+
+	response, cancel := newCachingOverheadBenchResponse(cache)
+	defer cancel()
+	resolver, shutdown := newCachingOverheadBenchResolver(options)
+	defer shutdown()
+
+	benchResolveGraphQLResponse(b, resolver, response, configure)
+	b.ReportAllocs()
+	b.ResetTimer()
+	for b.Loop() {
+		cachingOverheadBenchSink = benchResolveGraphQLResponse(b, resolver, response, configure)
+	}
+}
+
+func newCachingOverheadBenchResponse(cache *FetchCacheConfiguration) (*GraphQLResponse, context.CancelFunc) {
+	root := &countingCacheTestDataSource{
+		responses: [][]byte{
+			[]byte(`{"data":{"users":[{"__typename":"User","id":"1"},{"__typename":"User","id":"2"}]}}`),
+		},
+	}
+	entities := &countingCacheTestDataSource{
+		responses: [][]byte{
+			[]byte(`{"data":{"_entities":[{"__typename":"User","id":"1","name":"Ada"},{"__typename":"User","id":"2","name":"Grace"}]}}`),
+		},
+	}
+	return cacheTestBatchEntityResponse(root, entities, cache), func() {}
+}
+
+func newCachingOverheadBenchResolver(options ResolverOptions) (*Resolver, context.CancelFunc) {
+	resolverCtx, cancel := context.WithCancel(context.Background())
+	resolver := New(resolverCtx, options)
+	return resolver, cancel
+}
+
+func benchResolveGraphQLResponse(b *testing.B, resolver *Resolver, response *GraphQLResponse, configure func(*Context)) string {
+	b.Helper()
+
+	ctx := NewContext(context.Background())
+	ctx.ExecutionOptions.DisableSubgraphRequestDeduplication = true
+	if configure != nil {
+		configure(ctx)
+	}
+
+	var out bytes.Buffer
+	_, err := resolver.ResolveGraphQLResponse(ctx, response, nil, &out)
+	if err != nil {
+		b.Fatal(err)
+	}
+	return out.String()
+}
+
+type benchLoaderCache struct {
+	entries map[string][]byte
+}
+
+func newBenchLoaderCache() *benchLoaderCache {
+	return &benchLoaderCache{entries: map[string][]byte{}}
+}
+
+func (c *benchLoaderCache) Get(_ context.Context, keys []string) ([]*CacheEntry, error) {
+	entries := make([]*CacheEntry, len(keys))
+	for i, key := range keys {
+		value, ok := c.entries[key]
+		if !ok {
+			continue
+		}
+		entries[i] = &CacheEntry{
+			Key:   key,
+			Value: append([]byte(nil), value...),
+		}
+	}
+	return entries, nil
+}
+
+func (c *benchLoaderCache) Set(_ context.Context, entries []*CacheEntry) error {
+	for _, entry := range entries {
+		if entry == nil {
+			continue
+		}
+		c.entries[entry.Key] = append([]byte(nil), entry.Value...)
+	}
+	return nil
+}
+
+func (c *benchLoaderCache) Delete(_ context.Context, keys []string) error {
+	for _, key := range keys {
+		delete(c.entries, key)
+	}
+	return nil
+}
+
+func (c *benchLoaderCache) Clear() {
+	for key := range c.entries {
+		delete(c.entries, key)
+	}
+}