Fixed the validation result cache serving one document's result for another

[xperiandri]

Problem

• Wrong cached results. The validation result cache keyed its entries by two 32-bit structural hash codes: one of the document and one of the introspected schema. Different documents share these hash codes, for example { f(x: 0) } and { f(x: 4294967297) }. An invalid document could therefore pass validation with the cached result of a valid one.
• No single flight. Concurrent requests for a document that was not cached yet each ran the validation.
• Sliding expiration did not slide. A cache hit did not refresh the last use, so every entry expired 30 seconds after it was added, however often it was used.
• A timer that was never stopped. Every MemoryValidationResultCache started one, including the cache each Executor creates when given none. The timer kept the cache and all its entries alive until the process exited.
• Hashing the schema per request. Executor computed the structural hash code of the whole introspected schema on every request.

Changes

• Breaking: ValidationResultKey holds the Document, compared structurally, and the IntrospectionSchema instance, compared by reference. It replaces the DocumentId and SchemaId hash codes.
  • Its hash code only buckets keys. It is computed once per key from every value of the document and mixed with a secret seed chosen per process, so that clients cannot craft many documents sharing one.
  • ExecutionPlan.DocumentId is unchanged.
• Microsoft.Extensions.Caching.Memory instead of an own cache. MemoryValidationResultCache and the client provider's design-time cache of provided types hold their entries in a MemoryCache. The library's own MemoryCache helper is deleted, and FSharp.Data.GraphQL.Shared now depends on the package, so it also lands in the design-time folder of the client provider.
  • New constructors MemoryValidationResultCache (cache) and MemoryValidationResultCache (cache, slidingExpiration) take the IMemoryCache to use, so that an application can pass one it configures itself, such as a keyed service. It should hold validation results only and have a SizeLimit in bytes.
  • A cache hit refreshes the sliding expiration, and expired entries are removed while the cache is used, not by a timer.
• Single flight. A memory cache may run the factory of a key once per concurrent request, so MemoryValidationResultCache shares the validation in flight itself and puts only a finished result into the memory cache.
  • Requests share a validation whether or not its result ends up cached.
  • A validation in flight can neither expire nor be evicted, and the sliding expiration of its result counts from when it finished.
  • A validation that throws is run again by the next request.
• Size limit. The cache now holds the documents of its keys, so every entry declares ValidationResultKey.DocumentSize as its size: the estimated memory of the parsed document in bytes, a fixed amount per node and two bytes per character of names and strings.
  • A cache created without an IMemoryCache owns one limited to MemoryValidationResultCache.DefaultSizeLimit, 16 MiB. The new constructor MemoryValidationResultCache (slidingExpiration, sizeLimit) sets another limit.
  • An entry that does not fit is not cached, and the least recently used entries are evicted to make room for the next ones, a tenth of the limit at a time.
  • A document larger than the whole limit is validated on every request and is not offered to the memory cache at all, so it does not evict the others.
• Executor reads ISchema.Introspected once, when it is created.
• Client provider. Its design-time validation cache uses the new key.
• Docs. The docs of CreateExecutionPlan, of AsyncExecute and docs/execution-pipeline.md no longer call DocumentId unique or suggest caching execution plans by it. A cache keyed by it alone could execute a document that was never validated, with the plan of another.

Not in this PR

IDistributedCache is not supported:

• It needs a string key. That would have to be a collision-resistant digest of the document plus an identity of the schema that is the same in every process, and neither exists yet. Make documentId deterministic SHA-256 string and keep schemaId as in-memory int cache key #575 works on the former.
• Its values are bytes, so validation results would need a serialized form.
• Validating a document usually costs less than a network round trip.

IValidationResultCache stays the extension point for such a cache.

Estimate of the document size

On .NET 10, I measured the memory that parsed documents retain against the estimate:

Document	Retained / estimated
100 000 fields	1.13
nesting of 100	1.10
10 000 fragments	1.08
a 1 000 000-character string	1.00
20 000 aliases with directives	0.68
50 000 fields with 2 arguments	0.64

Tests

The tests are xUnit, in the new ValidationCacheTests.fs:

• documents with colliding hash codes are validated separately, whichever one is cached first; keys with equal hash codes are different;
• one document is validated separately against each schema that shares the cache;
• concurrent requests for one key run the validation once; a validation that throws is run again by the next request;
• concurrent requests share one validation whose result cannot be cached;
• a validation that outlasts the sliding expiration is still shared, and its result is cached from when it finished;
• a cache hit refreshes the sliding expiration, on a memory cache with a clock the test sets;
• entries declare their size to a memory cache with a size limit; a document larger than the limit of an own cache is not cached and does not evict the documents within the limit;
• an Executor caching in a keyed IMemoryCache of a service provider;
• the estimate of the document size, including a 100 000-character string;
• Executor does not read the introspected schema per request.

The three tests of sharing a validation fail when each request runs its own.

Verification:

• Unit tests: the whole project passes, 786 tests with 5 skipped.
• FAKE: the full pipeline passes, including the 106 integration tests, which build with the client provider and so load the new package in its design-time folder.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Cache-pressure and expiration races still violate single-flight and size-limit guarantees, while execution-plan cache guidance remains incomplete.

4 open findings

• Prevent expiration of in-flight entries · New
• Retry eviction until cache size meets target · New
• Preserve single-flight behavior during eviction · New
• Update remaining DocumentId cache key documentation · New

What changed in this PR

Fixes validation-cache collisions while improving concurrency, expiration, memory limits, and schema reuse.

Changes:

• Uses document-aware, schema-specific validation keys.
• Reworks caching for single-flight production, LRU eviction, and sliding expiration.
• Adds regression tests and safer execution-plan caching guidance.

File	Description
ValidationResultCache.fs	Introduces secure keys and bounded validation caching.
MemoryCache.fs	Implements lazy production, expiration, and eviction.
Executor.fs	Reuses introspection and updates cache keys/docs.
ProvidedTypesHelper.fs	Adopts the new validation key.
ValidationCacheTests.fs	Adds cache correctness and concurrency tests.
FSharp.Data.GraphQL.Tests.fsproj	Includes the new tests.
execution-pipeline.md	Warns against DocumentId-only caching.
RELEASE_NOTES.md	Documents behavior and API changes.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Test Results

    9 files      9 suites   14m 40s ⏱️
  894 tests   889 ✅  5 💤 0 ❌
2 682 runs  2 667 ✅ 15 💤 0 ❌

Results for commit 4ec660a.

♻️ This comment has been updated with latest results.