Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
371 changes: 371 additions & 0 deletions docs/caching/1-readme.md

Large diffs are not rendered by default.

472 changes: 472 additions & 0 deletions docs/caching/2-behavior.md

Large diffs are not rendered by default.

573 changes: 573 additions & 0 deletions docs/caching/3-onboarding.md

Large diffs are not rendered by default.

317 changes: 317 additions & 0 deletions docs/caching/4-redis-adapter-report.md

Large diffs are not rendered by default.

137 changes: 137 additions & 0 deletions docs/caching/5-testing-on-js-subgraphs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
# Live-subgraph testing report

Findings from running the execution engine's response caching against real Apollo-federation JS subgraphs,
2026-08-11.
Suite written by an agent from a detailed guide; all headline findings re-verified by hand,
including an independent rerun reproducing the correctness bug.

## Environment

- Suite: `apollo-response-caching/gqlt-live/` (standalone Go module,
`replace`-linked to the local graphql-go-tools checkout).
Its own `README.md` has the full setup for reproducing the environment on another machine
(subgraphs, Redis, composition, the directory-layout assumption of the `replace` directives).
Run from that directory: `gotestsum --format=short -- ./... -count=1`.
- Live origins: the two Apollo-federation subgraphs from the apollo-response-caching workspace,
`products` on :4301 (`Cache-Control: max-age=60, public`) and `reviews` on :4302 (`max-age=30, public`),
each with a request counter and body log.
Both must be running (`node index.js`); the suite does not start them.
- Redis 7.2 container `apollo-cache-redis` on :6380 for the Redis-store subtests.
- Composition: wgc over SDL copies fetched from the live subgraphs.
wgc rejects Apollo's `@cacheTag` directive;
the copies drop it from the `@link` import and declare it locally,
preserving all applications.
Inert for what is tested: this engine's directive is `@cache`, so `@cacheTag` affects no key, TTL, or tag.
- Every datasource is reached through a transparent recording reverse proxy so tests pin exact wire bodies;
the subgraphs' own counters are the independent cross-check.
A control subtest runs one operation both proxied and direct
and asserts identical responses, store ops, and counter deltas.

Result: 14 subtests, 13 pass, 1 deliberate known-failure pinning a real engine bug (finding 1).
Stable across `-race` reruns.

## Finding 1 — BUG: two calls of one cached root field in one operation share a key

```graphql
query($x: Int, $y: Int) { one: topProducts(first: $x) { upc } two: topProducts(first: $y) { upc } }
# variables {"x":1,"y":3}
```

The cold response is correct, and the two isolated fetches are genuinely different at the origin
(wire bodies carry `{"a":1}` and `{"b":3}` after variable remapping).
But both fetches render the SAME cache key, both read it, and both write it —
one silently overwrites the other.
The warm request serves the surviving entry to BOTH aliases:
observed `{"one":[1],"two":[1]}` and `{"one":[1,2,3],"two":[1,2,3]}` across runs,
i.e. which alias gets corrupted is nondeterministic (whichever isolated fetch finishes last wins).

Root cause: `rootFieldCacheKey` (`v2/pkg/engine/cache/cache_key_template.go`)
builds the preimage from the coordinate plus `canonicalVariables(ctx)`,
which serializes the ENTIRE request variable set rather than the arguments this fetch sends.
Two calls of one coordinate in one operation therefore have byte-identical preimages.

This breaks two stated invariants:
"read key == write key == fetch identity" and "caching never changes a response".
Entity keys are unaffected (they render from representation values).
Fix direction: derive the root-field key from the argument values the fetch itself sends
(its rendered input), mirroring how entity keys already work.
Pinned by the deliberately-failing subtest [11].

## Finding 2 — root-field entries fragment by client variable name

`topProducts(first: 1)` inline, `query($first: Int)` + `{"first":1}`, and `query($n: Int)` + `{"n":1}`
produce three different keys, three misses, and three copies of one value —
while the recorded wire bodies to the origin are byte-identical.
Same root cause as finding 1: the preimage serializes client-named request variables.
Impact is hit rate and store size, not correctness.
Pinned as a passing characterization subtest [10] (documents current behavior, not a fix).

Doc impact: 2-behavior.md §3.7 ("variable names never affect keys") was contradicted by §3.5
(root-field preimages include the name-sorted variable set);
the docs now carry the known-deviation note pointing here.

## Finding 3 — coverage genuinely prevents ping-pong (works as designed)

The selection set is not part of a root-field key, so narrow and wide queries share one entry.
Sequence narrow → wide → narrow → wide:
the narrow query misses and writes;
the wide query gets a store HIT but coverage rejects the narrow entry and overwrites it wider;
both later queries serve from the wide entry.
Two origin requests total, then stable —
entries converge on the widest selection, narrower selections are projected down on serve.

## Verified working (each with wire-body, op-log, and counter evidence)

- **Entity L2 lifecycle**: counter deltas `{products:1, reviews:1}` cold, `{1, 0}` warm;
read key == write key.
- **Header beats static config**: with `DefaultTTL: 5m` at the global, subgraph AND root-field tiers,
entries are written with `TTL: 60s` (products) / `30s` (reviews) and `cc.ttl` agrees —
the origin's `max-age` is the runtime truth.
- **Root-field caching**: an alias-variant operation is served from the same entry with zero deltas;
a different `first` argument misses into its own entry;
root-field entries carry the two coarse tags only.
- **Batch entity fetch**: one `GetMany` with 3 keys, one `SetMany` with 3 entries,
one wire request carrying all 3 representations; the warm run is a full hit.
- **Partial cache load**: with one product primed, the reviews origin received exactly
`{"representations":[{"__typename":"Product","upc":"2"}]}`
and only the missing entry was written back.
- **Client cache answer**: cold `MaxAge` is exactly `30s` (the minimum of 60/30, proving min-fold);
the warm countdown lands in `(25s, 30s]`;
one uncached fetch forces `NoStore` while the cacheable part is still stored.
- **Response invariance**: no-controller, cold-cached, and fully-warm runs are byte-identical.
- **Redis store (prototype)**: the envelope crosses into a real Redis verbatim with the header TTL;
a fresh controller serves from it;
delete-by-tag on the entity tag removes exactly one entry and forces a refetch.

## Not tested, and why

Both origins serve one hardcoded `Cache-Control` and never vary it,
so `no-store` / `no-cache` / `private` / malformed directives / the `MaxTTL` clamp are unreachable live.
Making the two `index.js` files vary the header per operation
is the highest-value extension to this suite.
Also uncovered: the negative sentinel (no empty-entity path in the fixtures),
privacy partitions (no identity source), shadow mode, `@defer` L1 reuse, store-error fallback —
all of these are covered by the in-repo `execution/cachingtesting` suites against doubles.
The reviews subgraph's `extensions.invalidation` hint on `addReview` is ignored by this engine;
mutation-driven invalidation is documented out of scope.

## Suite caveats

- `Mutation.addReview` permanently mutates the subgraph's in-memory data;
running it once invalidates pinned bodies until the node process restarts.
- Pinned keys embed the composition-assigned datasource ordinal (`v1:0` / `v1:1`);
adding a subgraph to `graph.yaml` re-pins them all.
- Subtests read shared origin counters and must stay sequential (no `t.Parallel`).

## Notes for the router's Redis adapter (defects found in the suite's own prototype)

All three were caught and fixed during the suite's self-review;
they are exactly the traps the production adapter must avoid
(consistent with `4-redis-adapter-report.md` §3–§5):

- An unconditional tag-set `PEXPIRE` lets a short-lived entry SHORTEN a tag index's lifetime,
stranding longer-lived entries as permanently unpurgeable — use the `EXPIRE ... GT` form.
- Returning the tag set's cardinality from delete-by-tag over-reports;
return the deletion command's own count.
- A read helper that maps every error to "absent" makes
"the purge worked" satisfiable by "Redis is unreachable" — errors and misses must stay distinct.
112 changes: 112 additions & 0 deletions docs/caching/6-open-issues.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Open issues

## BUG: root-field cache keys derive from the request variable set, not the fetch's arguments

Found by live-subgraph testing 2026-08-11 (`5-testing-on-js-subgraphs.md`, findings 1 and 2).
`rootFieldCacheKey` hashes `{TypeName}.{FieldName}:{canonicalVariables(ctx)}` — the WHOLE request variable set.

Two consequences:

1. CORRECTNESS: two aliased calls of one cached root field in one operation
(`one: topProducts(first:$x) two: topProducts(first:$y)`) render identical keys;
one write overwrites the other and the warm response serves the survivor to both aliases,
nondeterministically.
Pinned by the deliberately-failing subtest [11] in the gqlt-live suite.
2. HIT RATE: client variable names are in the preimage,
so `($first:Int){"first":1}` and `($n:Int){"n":1}` fragment into separate entries
for byte-identical origin requests.

Fix direction: derive the key from the argument values the fetch itself sends
(its rendered input), mirroring entity keys.
Until fixed: do not configure root-field caching for fields a single operation may call twice.
Comment on lines +19 to +21

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Block root-field caching until the key uses fetch arguments.

The documented failure serves one root-field result to another alias when both calls use different arguments. This changes a valid GraphQL response.

Derive the key from the rendered arguments of this fetch. If that fix cannot ship now, reject or disable root-field cache configuration. Documentation alone cannot prevent this corruption.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/caching/6-open-issues.md` around lines 19 - 21, Implement the root-field
cache fix so its key is derived from the fetch’s rendered argument values,
matching entity-key behavior and distinguishing aliased calls with different
arguments. If that implementation is not available, reject or disable root-field
cache configuration rather than relying solely on the documented warning.


## Entry thrash: disjoint selections over one entity share a key and replace each other

Selection sets are not part of entity keys,
so two operations selecting DISJOINT field sets of the same entity from the same subgraph
(`User {a b}` vs `User {address}`) compete for ONE entry slot.
Each read is a store HIT that the coverage walk rejects (the entry lacks the other shape's fields),
and each refetch REPLACES the entry wholesale (storage is replace-only, no entry merging).

Verified with a scratch engine test 2026-08-11:
alternating `{upc stock}` / `{upc warehouse{...}}` four times produced four origin requests,
four hit-but-rejected reads, and an entry ping-ponging between the two shapes —
hit rate zero for both operations.
Traffic converges only when some operation fetches a superset in a single fetch
(the wider-serves-narrower behavior verified live, `5-testing-on-js-subgraphs.md` finding 3).

Agreed direction: follow Apollo and add a selection-shape digest to the L2 key —
`,"fields":"<16-hex>"` over the sorted NORMALIZED field paths of the fetch's ProvidesData tree,
computable at plan time and frozen in the key spec.
Because the digest is over normalized schema names,
alias/order/fragment variants and argument-value variants still share entries
(better than Apollo's raw query-shape hash),
and the entity tag still covers all shape variants, so one purge clears them all.
Comment on lines +41 to +44

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Keep rendered argument values in the full cache key.

Line 42 says that argument-value variants share entries. That is unsafe. v2/pkg/engine/cache/cache_key_args_test.go includes an args hash in the key preimage, and v2/pkg/engine/cache/controller_rootfield_test.go requires different variable values to produce different keys.

State that aliases, field order, and fragment variants share the selection digest. Different rendered argument values must use different entries.

Proposed wording
-Because the digest is over normalized schema names,
-alias/order/fragment variants and argument-value variants still share entries
-(better than Apollo's raw query-shape hash),
+Because the digest is over normalized schema names,
+alias/order/fragment variants share the same selection digest, while rendered
+argument values remain in the full cache key and use different entries
+(better than Apollo's raw query-shape hash),
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/caching/6-open-issues.md` around lines 41 - 44, Update the caching
documentation sentence to distinguish shared selection-digest variants from
argument values: aliases, field order, and fragment variants may share the
selection digest, but rendered argument values must remain in the full cache key
and produce separate entries.

Coverage stays on the read path as a corruption guard only.

Decided trade-offs to carry into the spec:

- L1 keeps the coverage-based model WITHOUT the digest:
cross-defer-group superset reuse (initial `{stock, warehouse}` serving a deferred `{stock}`)
and the `optimizeL1Cache` provider/consumer proof depend on it.
- Costs accepted: a narrow query after a wide one misses (per-shape warmup),
negative sentinels fragment per shape,
and the store holds one entry per (entity × shape × args × partition) — all Apollo-equivalent.

## TTL churn: the last writer's TTL caps the shared entry

Same root cause as the thrash issue, visible even for OVERLAPPING selections
when the origin's `Cache-Control: max-age` differs per operation
(the header is per HTTP response and beats static config).
With `{a b c}` answered `max-age=86400` and `{a b c d}` answered `max-age=600`:
whichever fetch wrote LAST owns the single entry and its TTL,
so the 10-minute superset write discards the remaining day of the narrow entry,
and after it expires the shapes alternate ownership indefinitely.
This is a consequence of the one-write-moment/one-honest-TTL invariant
(no field-level ages, no entry merging) — correct, but it makes a short-TTL operation
cap the effective cache lifetime of every operation sharing the entry.
The selection-shape digest above resolves this too:
per-shape entries each keep their own honest TTL.

## Open design: detecting the NEED for invalidation on schema deploys

The engine has NO schema-drift guard (the envelope `types` map was dropped 2026-08-10):
an entry written before a schema change is served as long as it decodes and covers the selection.
Undecided: whether/how a schema publish should purge affected entries — e.g. diff the composed schema at publish
time and fire `type:{subgraph}:{Type}` tag invalidations for types whose field shapes changed.
Belongs to the router/composition layer; the tag vocabulary already supports it.

## Follow-up: honor `s-maxage` in the header-driven caching model

The router cache is a SHARED cache, so the semantically correct reading of `Cache-Control: max-age=30, s-maxage=600`
is: router entry TTL = 600s (`s-maxage` wins for shared caches), client-facing aggregated header = 30s (`max-age`).
Useful pattern once tag invalidation exists: long router TTL + active purge, short client TTL.
Deliberately out of the initial model: it needs a second freshness number through the pipeline —
entry TTL from `s-maxage`, plus a separate client TTL in the value envelope's `cc`
metadata for the client-header aggregation.
Additive change; implement when the long-edge/short-client pattern is requested.

## Check: entity interface caching support

We need to verify whether caching works (and should be supported) for entity interfaces under the representation-derived single-key model
(implemented 2026-08-04; described in `1-readme.md`, spec text in git history of the 98dff2032..9f15c5c6c commit series).

Established (verified in `plan/representationvariable/representation_variable.go`):

- `BuildRepresentationVariableNode` bakes the interfaceObject/entity-interface `__typename` remap into the node:
for an `@interfaceObject` target the node's `__typename` field is a `resolve.StaticString{Value: <InterfaceTypeName>}`, not an item read.
- Consequence for representation-derived keys: the key renderer must take `__typename` from the NODE
(static value when present, item value otherwise), not unconditionally from the item —
then interfaceObject fetches key under the interface name automatically, inheriting the planner's remap for free.

Still to answer:

- Cross-subgraph identity split: a concrete-type subgraph keys the entity as `Article` while the `@interfaceObject` subgraph keys it as `Personalized` —
disjoint entries for the same logical entity.
Likely CORRECT (different subgraphs provide different data and the subgraph segment separates their keyspaces anyway), but decide and document.
- The `OnTypeNames`-aware key renderer (merged representation nodes for abstract-type batch fetches) must be tested against interface entity fixtures,
not only union/concrete ones.
- Coverage walk (`covers` / `skipFieldForTypeName`): verify type-conditioned fields behave for interface fetches where the cached value's `__typename`
is a concrete implementer but ProvidesData fields are conditioned on the interface.
- Fixtures: current caching subgraphs have no interface entities; add one (e.g. `Personalized`-style interface with two implementers, one `@interfaceObject` subgraph)
before claiming support either way.
Loading