From 279c752b7991eb94e102e6c26ded37b8d224e9c6 Mon Sep 17 00:00:00 2001 From: spetrunin Date: Tue, 11 Aug 2026 11:35:16 +0300 Subject: [PATCH 1/3] feat: add response caching support (squash of tmp-caching) Squash of the full tmp-caching series plus follow-ups: envelope types map removed, key format v1, comment hygiene, and the docs/caching documentation set. Co-Authored-By: Claude Fable 5 --- docs/caching/1-readme.md | 371 ++++ docs/caching/2-behavior.md | 472 +++++ docs/caching/3-onboarding.md | 573 ++++++ docs/caching/4-redis-adapter-report.md | 317 ++++ docs/caching/5-testing-on-js-subgraphs.md | 135 ++ docs/caching/6-open-issues.md | 64 + execution/cachingtesting/args_key_e2e_test.go | 302 ++++ execution/cachingtesting/art_e2e_test.go | 1556 +++++++++++++++++ execution/cachingtesting/batch_e2e_test.go | 132 ++ .../cachingtesting/cache_control_e2e_test.go | 329 ++++ execution/cachingtesting/cachingtesting.go | 286 +++ .../cachingtesting/cachingtesting_test.go | 139 ++ execution/cachingtesting/cascade_e2e_test.go | 228 +++ .../cachingtesting/client_headers_e2e_test.go | 424 +++++ execution/cachingtesting/compose.sh | 10 + execution/cachingtesting/config.json | 439 +++++ execution/cachingtesting/defer_l1_e2e_test.go | 381 ++++ execution/cachingtesting/enginetesting.go | 299 ++++ .../cachingtesting/entity_config_test.go | 240 +++ execution/cachingtesting/entity_l2_test.go | 248 +++ execution/cachingtesting/envelope_e2e_test.go | 160 ++ execution/cachingtesting/graph.yaml | 22 + .../cachingtesting/isolation_e2e_test.go | 371 ++++ execution/cachingtesting/l1_e2e_test.go | 191 ++ execution/cachingtesting/loader_bench_test.go | 279 +++ execution/cachingtesting/negative_e2e_test.go | 81 + .../cachingtesting/normalization_e2e_test.go | 96 + execution/cachingtesting/partial_e2e_test.go | 109 ++ execution/cachingtesting/privacy_e2e_test.go | 343 ++++ .../cachingtesting/provides_data_test.go | 160 ++ .../cachingtesting/rootfield_e2e_test.go | 92 + execution/cachingtesting/shadow_e2e_test.go | 90 + .../cachingtesting/store_batching_e2e_test.go | 293 ++++ .../cachingtesting/subgraphs/deals.graphql | 10 + .../subgraphs/inventory.graphql | 10 + .../cachingtesting/subgraphs/products.graphql | 16 + .../cachingtesting/subgraphs/reviews.graphql | 18 + .../cachingtesting/subgraphs/users.graphql | 8 + execution/cachingtesting/tags_e2e_test.go | 219 +++ .../type_declaration_e2e_test.go | 297 ++++ .../engine/engine_caching_config_test.go | 104 ++ execution/engine/engine_config.go | 24 + execution/engine/execution_engine.go | 88 +- .../complex_nesting_query_with_art.json | 186 +- .../gateway/httphandler/http.go | 14 +- v2/pkg/engine/cache/cache_control.go | 180 ++ v2/pkg/engine/cache/cache_control_test.go | 285 +++ v2/pkg/engine/cache/cache_key_args_test.go | 299 ++++ v2/pkg/engine/cache/cache_key_builder.go | 73 + v2/pkg/engine/cache/cache_key_builder_test.go | 306 ++++ .../engine/cache/cache_key_partition_test.go | 174 ++ v2/pkg/engine/cache/cache_key_template.go | 472 +++++ .../engine/cache/cache_key_template_test.go | 269 +++ v2/pkg/engine/cache/cache_response.go | 210 +++ v2/pkg/engine/cache/cache_response_test.go | 452 +++++ v2/pkg/engine/cache/cache_tags.go | 55 + v2/pkg/engine/cache/cache_tags_test.go | 202 +++ v2/pkg/engine/cache/cachetesting/fakes.go | 755 ++++++++ .../engine/cache/cachetesting/fakes_test.go | 304 ++++ v2/pkg/engine/cache/cachetesting/realish.go | 14 + v2/pkg/engine/cache/configure_caching.go | 53 + v2/pkg/engine/cache/configure_caching_test.go | 72 + v2/pkg/engine/cache/controller.go | 1058 +++++++++++ v2/pkg/engine/cache/controller_batch_test.go | 253 +++ .../cache/controller_cache_control_test.go | 541 ++++++ v2/pkg/engine/cache/controller_l1_test.go | 229 +++ .../engine/cache/controller_negative_test.go | 188 ++ .../engine/cache/controller_privacy_test.go | 481 +++++ .../engine/cache/controller_rootfield_test.go | 195 +++ v2/pkg/engine/cache/controller_shadow_test.go | 251 +++ v2/pkg/engine/cache/controller_store_test.go | 574 ++++++ v2/pkg/engine/cache/controller_test.go | 673 +++++++ v2/pkg/engine/cache/coverage.go | 102 ++ v2/pkg/engine/cache/coverage_test.go | 59 + v2/pkg/engine/cache/envelope.go | 105 ++ v2/pkg/engine/cache/envelope_test.go | 176 ++ .../engine/cache/fetch_cache_configurator.go | 168 ++ ...fetch_cache_configurator_rootfield_test.go | 190 ++ .../cache/fetch_cache_configurator_test.go | 285 +++ .../fetch_cache_configurator_types_test.go | 193 ++ v2/pkg/engine/cache/observer.go | 229 +++ v2/pkg/engine/cache/observer_test.go | 322 ++++ v2/pkg/engine/cache/optimize_l1_cache.go | 442 +++++ v2/pkg/engine/cache/optimize_l1_cache_test.go | 234 +++ v2/pkg/engine/cache/partial.go | 107 ++ v2/pkg/engine/cache/partial_test.go | 283 +++ v2/pkg/engine/cache/transform.go | 186 ++ v2/pkg/engine/cache/transform_test.go | 235 +++ .../graphql_datasource/graphql_datasource.go | 9 +- .../plan/cache_provides_data_visitor.go | 491 ++++++ .../cache_provides_data_visitor_port_test.go | 789 +++++++++ .../plan/cache_provides_data_visitor_test.go | 110 ++ .../plan/cacheconfig/cache_directive.go | 106 ++ .../plan/cacheconfig/cache_directive_test.go | 242 +++ v2/pkg/engine/plan/cacheconfig/cacheconfig.go | 287 +++ .../plan/cacheconfig/cacheconfig_test.go | 524 ++++++ .../plan/cacheconfig/type_cache_test.go | 285 +++ v2/pkg/engine/plan/configuration.go | 8 + v2/pkg/engine/plan/path_builder_visitor.go | 23 +- v2/pkg/engine/plan/planner.go | 21 + .../representation_variable.go | 44 +- .../representation_variable_test.go | 280 ++- v2/pkg/engine/plan/root_field_isolation.go | 24 + .../engine/plan/root_field_isolation_test.go | 120 ++ v2/pkg/engine/postprocess/postprocess.go | 84 + .../postprocess/postprocess_caching_test.go | 302 ++++ v2/pkg/engine/resolve/batch_input_assembly.go | 48 + .../resolve/batch_input_assembly_test.go | 92 + v2/pkg/engine/resolve/cache_config.go | 179 ++ v2/pkg/engine/resolve/cache_config_test.go | 171 ++ v2/pkg/engine/resolve/cache_controller.go | 303 ++++ .../engine/resolve/cache_controller_test.go | 51 + v2/pkg/engine/resolve/cache_fetch_test.go | 63 + v2/pkg/engine/resolve/cache_node_copy_test.go | 91 + v2/pkg/engine/resolve/cache_noop_test.go | 153 ++ v2/pkg/engine/resolve/cache_response.go | 45 + v2/pkg/engine/resolve/cache_transaction.go | 113 ++ v2/pkg/engine/resolve/context.go | 117 ++ v2/pkg/engine/resolve/fetch.go | 172 ++ v2/pkg/engine/resolve/fetchtree.go | 14 + v2/pkg/engine/resolve/loader.go | 274 ++- v2/pkg/engine/resolve/node_object.go | 86 +- v2/pkg/engine/resolve/resolve.go | 32 + v2/pkg/engine/resolve/response.go | 18 + .../subgraph_request_singleflight_test.go | 28 + v2/pkg/engine/resolve/tainted_objects_test.go | 14 + 126 files changed, 27711 insertions(+), 262 deletions(-) create mode 100644 docs/caching/1-readme.md create mode 100644 docs/caching/2-behavior.md create mode 100644 docs/caching/3-onboarding.md create mode 100644 docs/caching/4-redis-adapter-report.md create mode 100644 docs/caching/5-testing-on-js-subgraphs.md create mode 100644 docs/caching/6-open-issues.md create mode 100644 execution/cachingtesting/args_key_e2e_test.go create mode 100644 execution/cachingtesting/art_e2e_test.go create mode 100644 execution/cachingtesting/batch_e2e_test.go create mode 100644 execution/cachingtesting/cache_control_e2e_test.go create mode 100644 execution/cachingtesting/cachingtesting.go create mode 100644 execution/cachingtesting/cachingtesting_test.go create mode 100644 execution/cachingtesting/cascade_e2e_test.go create mode 100644 execution/cachingtesting/client_headers_e2e_test.go create mode 100755 execution/cachingtesting/compose.sh create mode 100644 execution/cachingtesting/config.json create mode 100644 execution/cachingtesting/defer_l1_e2e_test.go create mode 100644 execution/cachingtesting/enginetesting.go create mode 100644 execution/cachingtesting/entity_config_test.go create mode 100644 execution/cachingtesting/entity_l2_test.go create mode 100644 execution/cachingtesting/envelope_e2e_test.go create mode 100644 execution/cachingtesting/graph.yaml create mode 100644 execution/cachingtesting/isolation_e2e_test.go create mode 100644 execution/cachingtesting/l1_e2e_test.go create mode 100644 execution/cachingtesting/loader_bench_test.go create mode 100644 execution/cachingtesting/negative_e2e_test.go create mode 100644 execution/cachingtesting/normalization_e2e_test.go create mode 100644 execution/cachingtesting/partial_e2e_test.go create mode 100644 execution/cachingtesting/privacy_e2e_test.go create mode 100644 execution/cachingtesting/provides_data_test.go create mode 100644 execution/cachingtesting/rootfield_e2e_test.go create mode 100644 execution/cachingtesting/shadow_e2e_test.go create mode 100644 execution/cachingtesting/store_batching_e2e_test.go create mode 100644 execution/cachingtesting/subgraphs/deals.graphql create mode 100644 execution/cachingtesting/subgraphs/inventory.graphql create mode 100644 execution/cachingtesting/subgraphs/products.graphql create mode 100644 execution/cachingtesting/subgraphs/reviews.graphql create mode 100644 execution/cachingtesting/subgraphs/users.graphql create mode 100644 execution/cachingtesting/tags_e2e_test.go create mode 100644 execution/cachingtesting/type_declaration_e2e_test.go create mode 100644 execution/engine/engine_caching_config_test.go create mode 100644 v2/pkg/engine/cache/cache_control.go create mode 100644 v2/pkg/engine/cache/cache_control_test.go create mode 100644 v2/pkg/engine/cache/cache_key_args_test.go create mode 100644 v2/pkg/engine/cache/cache_key_builder.go create mode 100644 v2/pkg/engine/cache/cache_key_builder_test.go create mode 100644 v2/pkg/engine/cache/cache_key_partition_test.go create mode 100644 v2/pkg/engine/cache/cache_key_template.go create mode 100644 v2/pkg/engine/cache/cache_key_template_test.go create mode 100644 v2/pkg/engine/cache/cache_response.go create mode 100644 v2/pkg/engine/cache/cache_response_test.go create mode 100644 v2/pkg/engine/cache/cache_tags.go create mode 100644 v2/pkg/engine/cache/cache_tags_test.go create mode 100644 v2/pkg/engine/cache/cachetesting/fakes.go create mode 100644 v2/pkg/engine/cache/cachetesting/fakes_test.go create mode 100644 v2/pkg/engine/cache/cachetesting/realish.go create mode 100644 v2/pkg/engine/cache/configure_caching.go create mode 100644 v2/pkg/engine/cache/configure_caching_test.go create mode 100644 v2/pkg/engine/cache/controller.go create mode 100644 v2/pkg/engine/cache/controller_batch_test.go create mode 100644 v2/pkg/engine/cache/controller_cache_control_test.go create mode 100644 v2/pkg/engine/cache/controller_l1_test.go create mode 100644 v2/pkg/engine/cache/controller_negative_test.go create mode 100644 v2/pkg/engine/cache/controller_privacy_test.go create mode 100644 v2/pkg/engine/cache/controller_rootfield_test.go create mode 100644 v2/pkg/engine/cache/controller_shadow_test.go create mode 100644 v2/pkg/engine/cache/controller_store_test.go create mode 100644 v2/pkg/engine/cache/controller_test.go create mode 100644 v2/pkg/engine/cache/coverage.go create mode 100644 v2/pkg/engine/cache/coverage_test.go create mode 100644 v2/pkg/engine/cache/envelope.go create mode 100644 v2/pkg/engine/cache/envelope_test.go create mode 100644 v2/pkg/engine/cache/fetch_cache_configurator.go create mode 100644 v2/pkg/engine/cache/fetch_cache_configurator_rootfield_test.go create mode 100644 v2/pkg/engine/cache/fetch_cache_configurator_test.go create mode 100644 v2/pkg/engine/cache/fetch_cache_configurator_types_test.go create mode 100644 v2/pkg/engine/cache/observer.go create mode 100644 v2/pkg/engine/cache/observer_test.go create mode 100644 v2/pkg/engine/cache/optimize_l1_cache.go create mode 100644 v2/pkg/engine/cache/optimize_l1_cache_test.go create mode 100644 v2/pkg/engine/cache/partial.go create mode 100644 v2/pkg/engine/cache/partial_test.go create mode 100644 v2/pkg/engine/cache/transform.go create mode 100644 v2/pkg/engine/cache/transform_test.go create mode 100644 v2/pkg/engine/plan/cache_provides_data_visitor.go create mode 100644 v2/pkg/engine/plan/cache_provides_data_visitor_port_test.go create mode 100644 v2/pkg/engine/plan/cache_provides_data_visitor_test.go create mode 100644 v2/pkg/engine/plan/cacheconfig/cache_directive.go create mode 100644 v2/pkg/engine/plan/cacheconfig/cache_directive_test.go create mode 100644 v2/pkg/engine/plan/cacheconfig/cacheconfig.go create mode 100644 v2/pkg/engine/plan/cacheconfig/cacheconfig_test.go create mode 100644 v2/pkg/engine/plan/cacheconfig/type_cache_test.go rename v2/pkg/engine/{datasource/graphql_datasource => plan/representationvariable}/representation_variable.go (81%) rename v2/pkg/engine/{datasource/graphql_datasource => plan/representationvariable}/representation_variable_test.go (71%) create mode 100644 v2/pkg/engine/plan/root_field_isolation.go create mode 100644 v2/pkg/engine/plan/root_field_isolation_test.go create mode 100644 v2/pkg/engine/postprocess/postprocess_caching_test.go create mode 100644 v2/pkg/engine/resolve/batch_input_assembly.go create mode 100644 v2/pkg/engine/resolve/batch_input_assembly_test.go create mode 100644 v2/pkg/engine/resolve/cache_config.go create mode 100644 v2/pkg/engine/resolve/cache_config_test.go create mode 100644 v2/pkg/engine/resolve/cache_controller.go create mode 100644 v2/pkg/engine/resolve/cache_controller_test.go create mode 100644 v2/pkg/engine/resolve/cache_fetch_test.go create mode 100644 v2/pkg/engine/resolve/cache_node_copy_test.go create mode 100644 v2/pkg/engine/resolve/cache_noop_test.go create mode 100644 v2/pkg/engine/resolve/cache_response.go create mode 100644 v2/pkg/engine/resolve/cache_transaction.go diff --git a/docs/caching/1-readme.md b/docs/caching/1-readme.md new file mode 100644 index 0000000000..5a0ef8bac9 --- /dev/null +++ b/docs/caching/1-readme.md @@ -0,0 +1,371 @@ +# Entity and root-field caching + +This is the reference for what the caching feature consists of, +how to configure it, how it behaves as a black box, and how it is tested. +Design history lives in git. + +The full document set: + +| Document | What it is for | +|---|---| +| this README | index: black-box contract, configuration, file map, test map | +| [2-behavior.md](2-behavior.md) | the detailed behavior spec: wire traffic, worked key derivations, store/serve decision rules | +| [3-onboarding.md](3-onboarding.md) | the handover deep dive: mental model, code-path walkthrough, per-area internals, change recipes, gotchas | +| [6-open-issues.md](6-open-issues.md) | open design notes and known bugs: the root-field key bug, schema-deploy invalidation, `s-maxage`, entity-interface verification | +| [5-testing-on-js-subgraphs.md](5-testing-on-js-subgraphs.md) | findings from running the engine against live Apollo-federation JS subgraphs | +| [4-redis-adapter-report.md](4-redis-adapter-report.md) | researched design for the router-side Redis store adapter | + +## 1. What it does + +The engine caches **subgraph fetches** — never whole client responses — in two layers: + +- **L1** — request-lifetime, in-memory `*astjson.Value` store. + Shared across defer groups; zero marshaling. +- **L2** — an external store behind a batched two-method interface (Redis, memory, anything). + The only layer that marshals bytes. + +Freshness follows the HTTP model. +A subgraph's `Cache-Control` response header is the runtime truth: +`max-age` sets the entry TTL, `no-store` forbids caching, `private` triggers the privacy rules. +A static configuration cascade fills in when the header is silent. + +Entries carry stable tags for external invalidation. +Each request exposes an aggregated client cache policy the router can emit as a response header. + +With no cache controller attached, the runtime path is byte-identical to a non-caching build. +With no caching configuration, plans are byte-identical too. +These are the two **no-op gates**. + +## 2. Black-box behavior contract + +The one-paragraph version; every rule below is expanded with worked examples in 2-behavior.md. + +- A cached entity fetch is keyed by exactly what it sends: + subgraph, `@key` fields plus `@requires` values, argument values, requester partition. + Read key == write key == fetch identity ([BEHAVIOR §3](2-behavior.md#3-cache-keys)). +- A value is written only after a successful, storable, TTL-positive fetch; + it is served only when it decodes, matches the scope, and covers the selection + ([BEHAVIOR §4](2-behavior.md#4-when-a-value-is-cached--and-when-not), + [§6](2-behavior.md#6-when-a-cached-entry-is-served--and-when-it-is-a-miss)). +- Stored values are normalized (schema names, argument-suffixed fields), + so aliases and query shape never fragment or corrupt entries + ([BEHAVIOR §5](2-behavior.md#5-what-is-stored)). +- Batches render one key per unique representation; + with partial loading the subgraph receives only the missing representations + ([BEHAVIOR §7](2-behavior.md#7-batch-entity-fetches)). +- Empty entities cache as a negative sentinel under `NegativeCacheTTL`. +- Private data is partitioned per requester or not stored at all + ([BEHAVIOR §9](2-behavior.md#9-privacy-behavior)). +- Cache failures never fail a request; the origin is the fallback + ([BEHAVIOR §14](2-behavior.md#14-store-interaction-contract)). +- Caching never changes a response. + A cached and an uncached run of the same operation produce identical bodies. + +## 3. Components and file map + +The feature is split at a hard seam: +the `resolve` package holds only contract types and hook call sites, +and the `cache` package holds all cache logic. +Plan and postprocess hold thin shims. +The tables below are the index; +each area's internals, with the reasoning behind its design, +are explained in [ONBOARDING §3](3-onboarding.md#3-deep-dives), +and the code path connecting them in [ONBOARDING §2](3-onboarding.md#2-life-of-a-cached-request--the-code-path). + +### Plan time (per plan, cacheable work) + +| Area | Files | +|---|---| +| Configuration model: cascade, `Resolve`, `@cache` directive extraction | `v2/pkg/engine/plan/cacheconfig/cacheconfig.go`, `cache_directive.go` | +| ProvidesData walk: per-fetch field tree (aliases, args, type conditions) | `v2/pkg/engine/plan/cache_provides_data_visitor.go` | +| Per-root-field planner isolation gate | `v2/pkg/engine/plan/root_field_isolation.go` | +| `@key`-vs-`@requires` field marking on representation nodes | `v2/pkg/engine/plan/representationvariable/representation_variable.go` | +| Planner wiring (gated second walk) | `v2/pkg/engine/plan/planner.go` | +| Postprocess wiring into the caching passes | `v2/pkg/engine/postprocess/postprocess.go` | +| Pass entry: fetch config assembly + L1 narrowing | `v2/pkg/engine/cache/configure_caching.go`, `fetch_cache_configurator.go`, `optimize_l1_cache.go` | +| Key spec freezing from the fetch's representation node | `v2/pkg/engine/cache/cache_key_builder.go` | + +### Runtime (per request) + +| Area | Files | +|---|---| +| Loader-facing contract: `CacheController`, `RequestCache`, `Decision`, handle types | `v2/pkg/engine/resolve/cache_controller.go` | +| Per-fetch config carried on the plan | `v2/pkg/engine/resolve/cache_config.go` | +| Arena/lock transaction the hooks run under | `v2/pkg/engine/resolve/cache_transaction.go` | +| Client cache answer type | `v2/pkg/engine/resolve/cache_response.go` | +| Deferred batch input assembly (reduced representations) | `v2/pkg/engine/resolve/batch_input_assembly.go` | +| Hook call sites in the loader; ports on the Context | `v2/pkg/engine/resolve/loader.go`, `context.go`, `resolve.go` | +| The controller: lookup, decisions, merge hooks, deferred writes | `v2/pkg/engine/cache/controller.go` | +| Key rendering: entity/root-field keys, args digest, partitions | `v2/pkg/engine/cache/cache_key_template.go` | +| `Cache-Control` parsing + TTL/storability ladder | `v2/pkg/engine/cache/cache_control.go` | +| Value envelope encode/decode | `v2/pkg/engine/cache/envelope.go` | +| Coverage walk (can this entry serve this fetch) | `v2/pkg/engine/cache/coverage.go` | +| Normalize/denormalize between query shape and stored shape | `v2/pkg/engine/cache/transform.go` | +| Partial batch splice/realign | `v2/pkg/engine/cache/partial.go` | +| Default invalidation tags | `v2/pkg/engine/cache/cache_tags.go` | +| Client cache answer folding | `v2/pkg/engine/cache/cache_response.go` | +| ART trace / analytics observer | `v2/pkg/engine/cache/observer.go` | +| Test doubles (fake store with op log, recording observers/controllers) | `v2/pkg/engine/cache/cachetesting/` | + +### Integration surface + +| Area | Files | +|---|---| +| `Configuration.SetCaching` — the one config entry point | `execution/engine/engine_config.go` | +| `WithCacheController`, `WithPrivatePartitionProvider`, `CacheResponseInfo` | `execution/engine/execution_engine.go` | + +## 4. Configuring it + +### 4.1 Plan side — the configuration cascade + +`Configuration.SetCaching(cacheconfig.CachingConfiguration)`. +Three levels, most specific wins, every knob optional: + +```go +engineConfig.SetCaching(cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{ + DefaultTTL: 5 * time.Minute, // static fallback when no header and no narrower config + MaxTTL: time.Hour, // clamp on ANY resolved TTL, header-driven included; 0 = no clamp + NegativeCacheTTL: 30 * time.Second, // empty-entity sentinel lifetime; header-independent + EnablePartialCacheLoad: true, // mixed batch hits fetch only the missing entities + ShadowMode: false, // read-never-serve staleness measurement + HashAnalyticsKeys: false, // hash key material in traces + EmitCdnTags: false, // accumulate the CDN tag union (default off) + // EmitClientCacheControl *bool — client policy aggregation, default true + }, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { // keyed by datasource ID; absent subgraphs inherit pure global values + DefaultTTL: ptr(time.Minute), // pointer fields: nil = inherit from global + Enabled: ptr(false), // explicit veto for one subgraph + IncludeSubgraphHeaders: ptr(true), // vary-by-headers (public) or partition source (private) + Scope: ptr(cacheconfig.CacheScopePrivate), // every entry partitioned per requester + Types: map[string]cacheconfig.TypeCacheConfig{ // most specific static tier + "Product": {MaxAge: 30 * time.Second}, // beats the subgraph default + "Secret": {MaxAge: 0}, // declared uncacheable, sentinel included + "Profile": {MaxAge: time.Minute, Scope: cacheconfig.CacheScopePrivate}, + }, + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: time.Minute}, + // TTL 0 falls back to subgraph then global DefaultTTL; the entry itself is the opt-in + }, + }, + }, +}) +``` + +Enablement rules: + +- An entity fetch is cached when its type declaration says so (`MaxAge > 0`). + Without a declaration, it is cached when the effective subgraph config yields + `DefaultTTL > 0 || NegativeCacheTTL > 0`. + A declared `MaxAge: 0` vetoes the type entirely. +- A root field is cached only when a coordinate entry exists. +- There are no L1/L2 switches. + L2 follows the resolved TTLs; L1 eligibility is computed by the `optimizeL1Cache` postprocess pass. + +### 4.2 Per-type declarations from subgraph SDL + +Subgraph authors can declare per-type caching in their SDL; +the router extracts it into the `Types` map: + +```graphql +directive @cache(maxAge: Int!, scope: CacheControlScope = PUBLIC) on OBJECT + +type Product @key(fields: "upc") @cache(maxAge: 60) { + upc: String! +} +``` + +```go +types, warnings := cacheconfig.ExtractTypeCacheConfigs(subgraphSDL) +// merge into SubgraphCacheConfig.Types +// surface warnings — malformed declarations are skipped, never errors +``` + +`cacheconfig.CacheDirectiveDefinition` exports the directive SDL for composition tooling. + +### 4.3 Runtime side + +```go +controller := cache.NewController(store, observer, cache.WithGlobalConfig(caching.Global)) +engine.Execute(ctx, operation, writer, + engine.WithCacheController(controller), + engine.WithPrivatePartitionProvider(partitions), // only needed for PRIVATE scopes +) +``` + +The store the integrator supplies: + +```go +type Store interface { + GetMany(ctx context.Context, keys []string) ([]Entry, error) + SetMany(ctx context.Context, items []Item) error +} +// Item{Key, Value, TTL, Tags} +// Entry{Value, RemainingTTL, OK} — positional with keys +``` + +Tag index maintenance and delete-by-tag are the store implementation's job; +the engine only attaches tags. + +The partition provider names the requester for private scopes: + +```go +type PrivatePartitionProvider interface { + PrivatePartition(ctx *resolve.Context, subgraphName string) (value string, ok bool) +} +``` + +### 4.4 Reading the client cache policy + +After resolution, the router reads one value and decides what headers to emit: + +```go +info := resolveContext.CacheResponseInfo() +// CacheResponseInfo{HasPolicy, MaxAge, Private, NoStore, Tags} +``` + +Emission rules and the folding semantics: [BEHAVIOR §10](2-behavior.md#10-the-client-cache-answer). + +## 5. Architecture + +Plan time does all cacheable work; runtime only renders and decides: + +1. **Plan** — a gated second walk (`cacheProvidesDataVisitor`) records, + per fetch, the exact field tree that fetch returns. + The path builder isolates cached QUERY root fields into their own planners. +2. **Postprocess** — `cache.ConfigureCaching` resolves the config cascade per fetch, + freezes the key spec from the fetch's own representation node, + attaches a `resolve.FetchCacheConfig` to each cache-eligible fetch, + and narrows L1 to provider/consumer pairs across the response's fetch trees. +3. **Runtime** — the loader calls four hooks around each fetch + (`PrepareFetch`, `OnFetchSkipped`, `OnFetchResult`, `EndRequest`, + plus `OnUncachedFetch` for config-less fetches). + The controller renders keys, reads L1 then one batched `GetMany`, + decides (`Fetch` / `SkipFullHit` / `FetchPartial` / `FetchShadow`), + splices or write-gates on merge, and flushes one `SetMany` at request end. + The loader branches on nothing but the `Decision`. + +Concurrency: every hook opens exactly one `CacheTransaction`, +which holds the request's single data lock for the whole arena sequence; +all per-request cache state is guarded by that external lock. +`EndRequest` runs once, single-threaded, arena-free. + +Only static data is written at plan time; +digests, partitions, and header hashes derive per request, +so plans stay safely shareable across requests (plan-cache safety). + +## 6. Invariants (must survive any change) + +- Both no-op gates: no controller / no config ⇒ byte-identical behavior / plans. +- Key fidelity: one template per fetch renders read and write keys from the fetch's own representation; + the L1/L2 keys share one preimage core. +- Write gate: never reducible to `!HasErrors`; store failures never fail a request. +- Lock discipline: one `CacheTransaction` per hook; + the arena is never touched outside a held transaction. + The client-policy aggregate carries its own mutex because it folds on failure paths outside transactions. +- Privacy: no identity ⇒ no L2; partition values are sha256-hashed and source-tagged; + tags and traces never carry identity material. +- Plan-cache safety: only static data is written at plan time. + +## 7. How it is tested + +### 7.1 Conventions + +- Full-value `assert.Equal` only — complete op logs, complete envelopes, complete responses; + no partial contains-checks and no golden files. +- Time via `testing/synctest` (unit suites); `-race` on the cache/resolve/cachingtesting suites. +- e2e fixtures are wgc-composed SDL with the composed `config.json` committed + (`execution/cachingtesting/compose.sh`, `graph.yaml`, `subgraphs/`); + composition reruns only when fixtures change, plans are never hand-written. +- Subgraph doubles are real `httptest` servers; + `SubgraphRule.Headers` sets response headers per fixture without recomposition. +- Self-contained subtests; scenario-matrix IDs in subtest names where a spec matrix exists. + +### 7.2 Unit suites — `v2/pkg/engine/cache` + +Run against a fake store with a full op log, under `synctest` clocks. + +| File | Behavior under test | +|---|---| +| `controller_test.go` | decision dispatch, the write-gate rows (transport/parse/GraphQL-error/null variants), handle lifecycle | +| `controller_batch_test.go` | one key per unique representation, batch full-hit/full-miss, bucket alignment | +| `controller_cache_control_test.go` | header-driven storability and TTL flowing through the controller | +| `controller_l1_test.go` | L1 writes/serves, structural isolation, sentinel behavior | +| `controller_negative_test.go` | negative sentinel: write rules, TTL source, serve-as-null | +| `controller_privacy_test.go` | partitioned access, no-identity L2 skip, scope guard both directions | +| `controller_rootfield_test.go` | root-field whole-response entries, shadow asymmetry | +| `controller_shadow_test.go` | stash → compare → overwrite; metadata excluded from the compare | +| `controller_store_test.go` | store-error degradation to miss / dropped writes, `OnStoreError` | +| `cache_control_test.go` | `Cache-Control` parser rows + the `resolveCaching` ladder | +| `cache_key_template_test.go` | entity key rendering: type conditions, unrenderable inputs, number/string unification | +| `cache_key_args_test.go` | argument digest and per-field argument suffixes | +| `cache_key_partition_test.go` | partition and header-hash segments, byte-for-byte prefixes | +| `cache_key_builder_test.go` | plan-time key spec freezing from representation nodes | +| `cache_tags_test.go` | tag vocabulary, `@key`-only entity digest | +| `envelope_test.go` | envelope encode/decode, undecodable-bytes-as-miss | +| `coverage_test.go` | coverage walk: nullability, type conditions, argument-suffixed names | +| `transform_test.go` | normalize/denormalize round trips across alias sets | +| `cache_response_test.go` | client-answer folding: min-freshness, zero rules, defer suppression | +| `optimize_l1_cache_test.go` | L1 narrowing: provider/consumer proof, defer-tree ancestry, cycle bounds | +| `configure_caching_test.go` | pass wiring and the planner no-op gate | +| `fetch_cache_configurator_test.go` (+ `_rootfield`, `_types`) | cascade resolution into per-fetch configs, vetoes, mixed-root-field decline | +| `observer_test.go` | trace assembly from handles | + +### 7.3 Plan and contract suites + +| File | Behavior under test | +|---|---| +| `v2/pkg/engine/plan/cache_provides_data_visitor_test.go` | the no-op gate; plans byte-identical with an empty caching config | +| `v2/pkg/engine/plan/cache_provides_data_visitor_port_test.go` | full ProvidesData tree fidelity per fetch | +| `v2/pkg/engine/plan/root_field_isolation_test.go` | cached root fields planned into isolated fetches | +| `v2/pkg/engine/plan/cacheconfig/*_test.go` | cascade `Resolve`, `@cache` extraction warnings, type-tier semantics | +| `v2/pkg/engine/resolve/cache_config_test.go` | `FetchCacheConfig.Equals` — plan dedup can never conflate cache policy | +| `v2/pkg/engine/resolve/cache_controller_test.go` | contract types (decisions, handle strings) | +| `v2/pkg/engine/resolve/cache_noop_test.go` | the runtime no-op gate: nil controller costs nothing | +| `v2/pkg/engine/resolve/cache_fetch_test.go`, `cache_node_copy_test.go` | fetch-interface accessors; field/node copies carry cache metadata | +| `v2/pkg/engine/resolve/batch_input_assembly_test.go` | deferred batch input assembly, reduced-keep rendering | + +### 7.4 End-to-end suites — `execution/cachingtesting` + +Every suite drives the REAL execution engine over real `httptest` subgraph doubles +and asserts complete client responses plus complete store-op logs. +`cachingtesting.go` is the plan harness, `enginetesting.go` the engine harness +(doubles, request counting, URL/clock normalizers). + +| File | Behavior under test (2-behavior.md section) | +|---|---| +| `entity_l2_test.go` | the miss → write → hit lifecycle, zero network on hit, hook dispatch (§2) | +| `entity_config_test.go` | the per-fetch cache config landing in real plans | +| `envelope_e2e_test.go` | stored bytes, corrupted-entry recovery, per-subgraph keyspace separation (§5) | +| `batch_e2e_test.go` | batch full-hit and mixed-run-without-partial refetch (§7) | +| `partial_e2e_test.go` | the reduced representations request, mixed-TTL expiry (§7) | +| `negative_e2e_test.go` | empty entities served as null from the sentinel (§5) | +| `cache_control_e2e_test.go` | response-header TTL beating and vetoing the static tiers (§8) | +| `cascade_e2e_test.go` | global/subgraph inheritance and vetoes (§4) | +| `type_declaration_e2e_test.go` | per-type lifetimes, `MaxAge: 0` veto, private type partitioning (§4, §9) | +| `args_key_e2e_test.go` | argument-variant entries, no ping-pong, aliased multi-variant reuse (§3.2) | +| `normalization_e2e_test.go` | alias-different operations sharing one entry (§5) | +| `rootfield_e2e_test.go` | root-field entries, alias-variant reuse, different-arguments miss (§3.5) | +| `isolation_e2e_test.go` | cached root fields fetch-isolated, independent expiry (§3.5) | +| `privacy_e2e_test.go` | partitions per requester, no-identity skip, runtime-private drop (§9) | +| `tags_e2e_test.go` | the tag vocabulary on every write, shared entity tags across variants (§11) | +| `client_headers_e2e_test.go` | `CacheResponseInfo`: countdown, no-store forcing, defer suppression (§10) | +| `store_batching_e2e_test.go` | one `GetMany` per fetch / one `SetMany` per request, store-error fallback (§14) | +| `l1_e2e_test.go` | in-request L1 reuse: a later fetch of the same entity, no second store lookup (§13) | +| `defer_l1_e2e_test.go` | cross-defer-group L1 serving, superset shapes (§13) | +| `shadow_e2e_test.go` | shadow read-compare-overwrite, origin always served (§12) | +| `art_e2e_test.go` | the cache section of the ART trace, key hashing (§15) | +| `provides_data_test.go` | ProvidesData trees over real federation plans, deferred fetches | +| `loader_bench_test.go` | allocation budget of the hit and miss paths | + +## 8. Out of scope / follow-ups + +- Mutation- and subscription-driven invalidation; user-defined cache tags; + `stale-while-revalidate` / `stale-if-error`; request-level `no-cache` bypass; + `s-maxage` (see notes); a cache debugger (ART + shadow mode cover the operator story). +- The invalidation endpoint and the Redis store implementation + (indexes, delete-by-tag, circuit breaking) live in the router repository, + bound by the tag vocabulary and the store contract above. +- Store-outage behavior is deliberate origin fallback: + pair caching with subgraph rate limiting operationally. diff --git a/docs/caching/2-behavior.md b/docs/caching/2-behavior.md new file mode 100644 index 0000000000..be1398484b --- /dev/null +++ b/docs/caching/2-behavior.md @@ -0,0 +1,472 @@ +# Caching behavior reference + +This document describes caching behavior only: +what the engine sends to subgraphs, what it stores, when it serves from cache, +and when it does not. +It contains no architecture and no implementation detail. +Every literal in this document (request bodies, keys, envelopes, tags) +is pinned verbatim by a test in `execution/cachingtesting`. + +Companion documents: +`1-readme.md` (components, configuration, testing map). + +## 1. The running example + +A federated graph with four subgraphs, as composed in `execution/cachingtesting`: + +- `users` — `Query.me: User` +- `products` — `User.favoriteProduct: Product`, `Query.products(first: Int): [Product]` +- `inventory` — `Product.stock: Int`, `Product.stockHistory(days: Int): [Int]`, `Product.warehouse: Warehouse` +- `reviews` — `Product.reviews: [Review]` + +`Product` is an entity with `@key(fields: "upc")`. +Caching is enabled for the `inventory` subgraph with `DefaultTTL: time.Minute`. + +## 2. One request, end to end + +Client query: + +```graphql +{ me { username favoriteProduct { upc stock } } } +``` + +The plan produces three fetches, executed as a chain: + +1. `users` root fetch — `{ me { username id } }` style root query. Uncached (no config). +2. `products` entity fetch for `User.favoriteProduct`. Uncached. +3. `inventory` entity fetch for `Product.stock`. Cached. + +### 2.1 First request — miss, fetch, write + +Before the inventory fetch goes out, the cache renders the item's key +from the exact representation the fetch is about to send, and looks it up. +The store receives one batched read: + +```text +GetMany ["v1:1:4f796e3bbd360fce"] -> miss +``` + +The fetch then goes to the subgraph unchanged. +This is the complete request body sent to `inventory`: + +```json +{"method":"POST","url":"http://inventory.service","header":{}, + "body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename stock}}}", + "variables":{"representations":[{"__typename":"Product","upc":"1"}]}}} +``` + +The subgraph answers: + +```json +{"data":{"_entities":[{"__typename":"Product","stock":5}]}} +``` + +The entity value is queued for writing, +and at request end the store receives one batched write: + +```text +SetMany [ + Key: v1:1:4f796e3bbd360fce + Value: {"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":,"scope":"public"}} + TTL: 60s + Tags: subgraph:1, type:1:Product, entity:1:Product:d3cc039c7a9789e7 +] +``` + +The client receives the full response; caching never changes it: + +```json +{"data":{"me":{"username":"jens","favoriteProduct":{"upc":"1","stock":5}}}} +``` + +### 2.2 Second request — hit, no network + +The same lookup now hits: + +```text +GetMany ["v1:1:4f796e3bbd360fce"] -> hit +``` + +The inventory subgraph receives **nothing** — zero requests. +The cached value is spliced into the response at the same position, +and the response is byte-identical to the first one. +A pure hit writes nothing: with one key per fetch, the read key IS the write key. + +The uncached `users` and `products` fetches go to the network on every request. + +## 3. Cache keys + +### 3.1 Entity keys + +```text +preimage = v1:{subgraph}[:h]:{"__typename":T,"representation":{...}[,"args":"D"][,"partition":"P"]} +L2 key = v1:{subgraph}[:h]:{16-hex xxhash64 of the preimage} +L1 key = {subgraph}:{"__typename":T,"representation":{...}[,"args":"D"]} +``` + +Worked example — the inventory fetch above (datasource ID `1`): + +```text +preimage: v1:1:{"__typename":"Product","representation":{"upc":"1"}} +L2 key: v1:1:4f796e3bbd360fce +L1 key: 1:{"__typename":"Product","representation":{"upc":"1"}} +``` + +The `representation` object is exactly what the fetch sends on the wire: +the entity's `@key` fields **plus its `@requires` values**, in node order, objects recursing. +So a derived field cached under one `@requires` input +can never serve a request whose fresh input differs. + +Key rendering rules: + +- `__typename` comes from the plan node when it is static + (the `@interfaceObject` remap bakes the interface name in), + else from the item itself. +- A field whose `OnTypeNames` exclude the item's concrete type is skipped. +- A `null` or absent key field makes the key unrenderable — + the item is a plain miss and nothing is written. +- Numbers and strings of the same literal render identically (`1` and `"1"`), + but `1` and `1.0` stay distinct keys (extra miss, never wrong data). +- An empty representation (`{}`) is unrenderable — it would collide across all entities. + +### 3.2 The `args` segment + +Present when the fetch's selection contains parameterized fields. + +```graphql +query($days: Int!) { me { favoriteProduct { upc stockHistory(days: $days) } } } +``` + +With `days: 3` and `days: 1`, the two requests produce **two independent entries**: +the preimage gains `"args":"<16-hex digest>"`, +a digest over the sorted normalized field paths with each field's argument-value suffix. +Interleaved traffic with different argument values never replaces each other's entries. + +Aliased multi-variant selections stay one entry: + +```graphql +{ euro: price(currency: "EURO") usd: price(currency: "USD") } +``` + +is a single fetch, a single key, a single cacheable entry — +both variants live inside the stored value under argument-suffixed names (§5). + +### 3.3 The `partition` segment (private fetches only) + +A statically-private fetch appends `"partition":""` to the preimage. +The hashed value is source-tagged before hashing: + +- provider identity: `sha256("i:" + identity)` +- forwarded-header fallback: `sha256("h:" + <16-hex header hash>)` + +so one source's literal text can never forge the other's partition. +Two requesters therefore hold two disjoint entries for the same entity. + +### 3.4 The `h` segment (public vary-by-headers) + +On a **public** fetch with `IncludeSubgraphHeaders`, +the forwarded subgraph header hash joins the visible prefix: +`v1:products:h<16-hex>:`. +Requests forwarding different headers never share entries. +On a private fetch the same hash is an identity source instead (§3.3), +so one fetch is partitioned by exactly one mechanism. + +### 3.5 Root-field keys + +A cached root field keys the **whole fetch response** under: + +```text +preimage = v1:{subgraph}[:h]:{TypeName}.{FieldName}:{name-sorted variables}[,"partition":"P"] +L2 key = v1:{subgraph}[:h]:{16-hex xxhash64} +``` + +Example coordinate: `Query.topProducts` with variables `{"first":1}`. + +- The query text is **not** part of the key: + alias-variant operations over the same field and variables share one entry. +- Variables are name-sorted, so argument order never fragments entries. +- Operations are normalized with variable extraction before planning, + so inline literals become variables and cannot collide under one key. +- Root fields are L2-only; they have no L1 key. + +**Known deviation (bug, see [6-open-issues.md](6-open-issues.md) and [5-testing-on-js-subgraphs.md](5-testing-on-js-subgraphs.md)):** +the variables in the preimage are the request's WHOLE variable set under the CLIENT's names, +not the arguments the fetch sends. +Two calls of one cached root field in a single operation therefore collide on one key +(a correctness bug — the surviving entry serves both aliases), +and operations differing only in variable naming fragment into separate entries +(a hit-rate cost). +Entity keys are unaffected. + +### 3.6 L1 keys + +The L1 key is the raw preimage core — no version, no header hash, no partition, no digest. +Nothing persists (so no format version is needed), +and one request has one requester (so no partition is needed). + +### 3.7 What never affects keys + +Client query shape beyond the fetch identity: +field order, whitespace, aliases, operation names, fragment layout; +for ENTITY keys, variable names too. +(Root-field keys currently do vary by client variable names — the known deviation in §3.5.) + +## 4. When a value is cached — and when not + +A fetched value is written when ALL of the following hold: + +| Condition | Detail | +|---|---| +| The fetch is cache-configured | resolved from the config cascade; `nil` config = the fetch is invisible to the cache | +| The fetch succeeded | `!FetchFailed && !HasErrors && data != null`; a transport failure, empty body, parse failure, GraphQL error, or null data writes nothing | +| The response is storable | no `no-store` / `no-cache` in the response `Cache-Control` | +| A TTL resolved > 0 | header `max-age`, else type declaration, else subgraph default, else global default; clamped by `MaxTTL` | +| The key rendered | every referenced representation field present and non-null | +| Privacy is satisfiable | a private fetch has a partition; a runtime-only `private` header on a public fetch drops the write | + +A value is NOT cached when any of these fail. The specific cases: + +- **No configuration**: the subgraph (or type, or root-field coordinate) is not configured. + The fetch runs exactly as in a non-caching build. +- **Type veto**: a type declared `@cache(maxAge: 0)` gets no cache configuration at all, + negative sentinel included, whatever the subgraph level says. +- **Subgraph veto**: `Enabled: false` disables the whole subgraph. +- **Mixed root fields**: a fetch resolving several root fields with differing cache settings + declines caching entirely (rare — the planner isolates cached root fields into their own fetches). +- **`no-store` / `no-cache` response header**: nothing is written, in either layer. +- **Resolved TTL <= 0**: no L2 entry (L1 is unaffected — it is request-scoped). +- **Failed fetch / GraphQL errors**: nothing is written; existing entries are untouched. +- **Runtime-only `private`**: a statically-public fetch answered with `Cache-Control: private` + skips both store writes (L1 keeps serving within the request); + `CacheObserver.OnUncacheablePrivate("response-private")` fires. +- **Private without identity**: a statically-private fetch with no provider identity + and no header fallback skips L2 entirely — reads and writes; + `OnUncacheablePrivate("no-identity")` fires. +- **Unrenderable key**: the item is fetched and merged normally, just never cached. + +## 5. What is stored + +Every L2 entry is one envelope: + +```json +{"data": {"__typename":"Product","stock":5}, + "cc": {"ttl": 60, "created": 1785852117, "scope": "public"}} +``` + +- `cc.ttl` is the lifetime the entry was written with (whole seconds), + `cc.created` the unix second of the write, + `cc.scope` `"public"` or `"private"`. +- Storage is replace-only: one write moment per entry, one honest TTL. + There is no merge-into-existing-entry; a newer write replaces the older entry whole. + +`data` is stored **normalized**: + +- Aliases are resolved to schema field names. + A query selecting `productName: name` stores the value under `name`, + and a later query selecting `label: name` is served from the same entry, under `label`. +- Parameterized fields are stored under argument-suffixed names: + `stockHistory(days: 3)` stores as `stockHistory_<16-hex value hash>`, + so `stockHistory(days: 1)` can never be served a `days: 3` value. +- Fields the plan did not select (key fields, `__typename`) are preserved as-is. + +The **negative sentinel** is `{"data":null,"cc":{...}}`: +written when a successful entity fetch resolves an entity to nothing +(`_entities` returns null for it) and `NegativeCacheTTL > 0`. +On a later read the entity is served as null without a subgraph fetch. +Its lifetime is always `NegativeCacheTTL`, never the header `max-age` — +how long a value stays fresh says nothing about how long an entity stays nonexistent. + +## 6. When a cached entry is served — and when it is a miss + +An entry that exists in the store is served only when ALL of: + +- **It decodes**: undecodable or foreign bytes are a miss the next write repairs — never an error. +- **The scope matches**: an entry recorded `"private"` read through a public key derivation + (or the reverse) is configuration drift; it is discarded as a miss + and counted via `OnScopeMismatch`, in both directions. +- **It covers the selection**: the entry contains every field the fetch provides, + with null accepted only where the schema allows it. + Wider entries serve narrower queries; + a narrower entry is a miss and the refetch replaces it with the wider value. + Argument-suffixed names make an argument-mismatched field a miss, not a wrong hit. +- **It is fresh**: the store reports expired entries as absent; + remaining freshness also feeds the client cache answer (§10). + +A negative sentinel short-circuits: the entity is known missing, no coverage walk runs. + +## 7. Batch entity fetches + +A batch fetch (`_entities` over N array items) renders **one key per unique representation**. +Duplicate representations collapse into one bucket. +The lookup is still one store call: + +```text +GetMany [key1, key2, ... keyN] +``` + +Three outcomes: + +- **Full hit** — every bucket covered: the network fetch is skipped entirely, + each cached value spliced at its original positions. +- **Full miss / partial without the flag** — any bucket missing and + `EnablePartialCacheLoad` off: the full batch goes to the subgraph, + and every entity in the response is written back (one entry per unique representation). +- **Partial** — `EnablePartialCacheLoad` on: covered buckets serve from cache, + and the subgraph receives a REDUCED representations list containing only the missing ones. + +The reduced request is literal. +With product 1's reviews cached and product 2's missing, +the reviews subgraph receives exactly: + +```json +{"query":"query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename reviews {body}}}}", + "variables":{"representations":[{"__typename":"Product","upc":"2"}]}} +``` + +The response realigns to the original batch positions: +cached and fetched entities appear exactly where they belong. +A failed partial fetch still serves the covered buckets; +only the fetched subset is lost to the normal error path. + +One `Cache-Control` header governs a whole batch response — +every entity entry written from it shares the resolved TTL. + +Mixed TTLs across subgraphs partition naturally: +when only the short-TTL subgraph's entry expires, +only that subgraph is re-fetched and the fresh entries keep serving. + +## 8. TTL resolution + +Per fetch result, first match wins: + +```text +Cache-Control: no-store | no-cache -> not cached, either layer +Cache-Control: max-age=N -> entry TTL = N seconds (runtime truth) +else: type declaration MaxAge -> static tier, most specific first + else subgraph DefaultTTL + else global DefaultTTL (root fields: coordinate TTL first) +resolved TTL <= 0 -> no L2 entry +MaxTTL (when set) -> clamps whichever source won +``` + +Header parsing behavior: + +- Recognized: `max-age`, `no-store`, `no-cache`, `private`. Everything else is skipped, + `s-maxage` deliberately included. +- Parsing never fails: a malformed directive is dropped and the static tier decides. +- The FIRST well-formed `max-age` wins; `no-store`/`no-cache`/`private` are sticky. +- `no-cache` is treated as `no-store`: this cache cannot revalidate, + so the conservative reading is not to store. +- A `max-age` LOWER than the static TTL wins too — the header is truth, not a floor. + +## 9. Privacy behavior + +A fetch is **statically private** when its subgraph `Scope`, +type declaration scope, or root-field entry scope says PRIVATE. +Private widens down the cascade, never up. + +| Situation | Behavior | +|---|---| +| Private fetch, provider names the requester | entries live under the requester's partition (§3.3); full read/write behavior per requester | +| Private fetch, no provider identity, `IncludeSubgraphHeaders` set | the forwarded-header hash is the identity; same partitioning | +| Private fetch, no identity at all | the fetch skips L2 entirely — no read, no write, sentinel included; L1 keeps working unpartitioned; `OnUncacheablePrivate("no-identity")` | +| Public fetch, response says `Cache-Control: private` | both store writes dropped, L1 keeps serving within the request; `OnUncacheablePrivate("response-private")` | +| Private fetch, response says `private` | the header confirms the declaration; entries written into the partition as usual | + +Envelopes record their scope, and a scope mismatch on read is a counted miss (§6). +L1 is per-request and therefore inherently per-requester: it is never partitioned. +Tags and traces never carry identity material. + +## 10. The client cache answer + +After resolution the router reads `Context.CacheResponseInfo()` and emits headers. +The answer folds one contribution per fetch: + +- A **served** entry contributes what is LEFT of its lifetime + (a 60s entry served 20s after its write contributes 40s). +- A **freshly written** entry contributes the TTL it was written with. +- An **uncacheable** part — `no-store`, zero TTL, failed fetch, private-without-identity, + or any fetch executed without cache configuration — contributes zero, + and one zero makes the whole response `NoStore`. +- An **L1-served** part contributes nothing (its originating fetch already folded). + +Resulting client policy: + +- `HasPolicy == false` — the operation touched no cache-configured fetch, + or the response used `@defer` (headers ship with the first frame, + so no answer can describe the whole response). Emit nothing. +- `NoStore == true` — emit `Cache-Control: no-store`. +- Otherwise — emit `Cache-Control: max-age=[, private]`, + where `MaxAge` is the MINIMUM across contributions and counts down between requests. +- `Tags` (only with `EmitCdnTags`) is the sorted union of the contributing entries' tags. + +## 11. Invalidation tags + +Every written entry carries, in this order: + +```text +subgraph:{name} +type:{name}:{TypeName} +entity:{name}:{TypeName}:{16-hex digest of the @key fields only} // entity entries +``` + +Example (inventory datasource `1`, Product upc "1"): +`subgraph:1`, `type:1:Product`, `entity:1:Product:d3cc039c7a9789e7`. + +The entity digest covers the `@key` subset alone — +no `@requires` values, no argument digest, no partition — +so every variant of one entity (argument variants, requires variants, private partitions) +shares the tag, and a single purge clears them all, sentinels included. +Root-field entries carry the two coarse tags with the coordinate's type (`type:{name}:Query`). +Tags ride on the store item, never inside the stored value. + +## 12. Shadow mode + +`ShadowMode` reads but never serves: + +1. The lookup runs normally and stashes what WOULD have been served. +2. The fetch always goes to the network, in full. +3. The fresh `data` is byte-compared against the stashed value + (`CacheObserver.CompareShadow`; envelope metadata excluded — only staleness of data counts). +4. The fresh value overwrites the entry. + +The response is always the origin's. +This is the safe-rollout mode: it measures staleness without risking a stale serve. +Root fields shadow asymmetrically: read, then force-refetch, no compare +(their whole-response value has no per-item compare surface). + +## 13. The request-lifetime layer (L1) + +- Holds decoded, normalized values under raw preimage keys; no envelopes, no bytes. +- Scope: ONE request, including all of its `@defer` groups. + An initial-response fetch that stores `{stock, warehouse}` serves a later + defer-group fetch that needs only `{stock}` — with zero store operations. +- Reads apply the same coverage and negative-sentinel rules as L2. +- Only `no-store` disables L1 writes; a zero TTL does not (L1 has no TTL). +- Values are isolated by structural copy at both boundaries, + so later merges can never corrupt a stored value. +- Private data lands in L1 unpartitioned by design: + one request is one requester. + +## 14. Store interaction contract + +- Exactly ONE `GetMany` per cache-participating fetch, however many items it batches. +- Exactly ONE `SetMany` per request, at request end, carrying every deferred write. +- A `GetMany` error (or a mis-sized answer) degrades to an all-miss; the fetch falls back to the origin. +- A `SetMany` error drops the writes. +- Neither ever fails the request; both fire `CacheObserver.OnStoreError(op, subgraph, keyCount, err)`. +- Store outage behavior is deliberate origin fallback — + pair caching with subgraph rate limiting operationally. + +## 15. Observability signals + +| Signal | Fires when | +|---|---| +| `OnFetchObserved` | once per cache-touched fetch, at request end (or at trace flush): decision, served-from layer, per-item key / hit / negative / remaining TTL | +| `CompareShadow` | once per shadow-mode fetch result, before the write-back | +| `OnStoreError` | once per failed store round trip | +| `OnUncacheablePrivate` | at most once per fetch, reason `"response-private"` or `"no-identity"` | +| `OnScopeMismatch` | once per discarded wrong-scope entry | + +The ART trace carries a per-fetch cache section with the same data. +`HashAnalyticsKeys` hashes key material in all trace output. diff --git a/docs/caching/3-onboarding.md b/docs/caching/3-onboarding.md new file mode 100644 index 0000000000..7ee88155c5 --- /dev/null +++ b/docs/caching/3-onboarding.md @@ -0,0 +1,573 @@ +# Caching onboarding guide + +This is the handover document for an engineer taking over the response-caching feature. +It explains the mental model, walks the actual code path of a cached request, +gives a deep dive into every area with the reasoning behind its design, +and ends with how to work on the code day to day. + +How to use the doc set: + +- Read this document once, top to bottom — it is the tour. +- [2-behavior.md](2-behavior.md) is the behavior contract with worked wire-level examples; + use it as the reference when you need to know "what exactly happens when…". +- [1-readme.md](1-readme.md) is the index: configuration surface, file map, test map. +- The working notes and reports live in this folder (see §8) — read them before planning new work. + +## 1. The mental model + +### 1.1 What is cached + +The engine caches **subgraph fetches**, never whole client responses. +A federated query plan is a tree of fetches (root fetches and `_entities` fetches), +and each fetch is independently cacheable. +This is the same granularity Apollo Router's response cache uses, +and it is what makes partial reuse work: +one request's inventory data serves another request's completely different query, +as long as both plans produce an inventory fetch with the same identity. + +Two layers hold values: + +- **L1** is a per-request, in-memory map of decoded `*astjson.Value`s. + It exists because one request can plan the same entity fetch several times — + most importantly across `@defer` groups — and the second occurrence + should cost neither network nor a store round trip. + It dies with the request, so it needs no versioning, no privacy partitions, no TTL. +- **L2** is the external store (Redis in production, fakes in tests) + behind the two-method `Store` interface. + It is the only place bytes are marshaled, + and every entry is wrapped in a self-describing envelope. + +### 1.2 The identity idea: the key is what the fetch sends + +The single most important design decision: +**a fetch's cache key is derived from the exact representation object the fetch sends to the subgraph**. +Not from the query text, not from a hand-configured key template, not from `@key` metadata alone — +from the merged representation node that the planner builds +and that the loader renders into the `representations` variable. + +Consequences worth internalizing: + +- Read key == write key == fetch identity, structurally guaranteed. + There is no way for a lookup to use a different identity than the write, + because both render from the same frozen node against the same item. +- `@requires` values are part of the key. + A field computed from a `@requires` input (say, `shippingEstimate` requiring `weight`) + is cached per input value, so a changed input can never serve a stale derived value. +- Anything the client does that does not change what the fetch sends — + aliases, selection order, operation names, fragment layout — cannot fragment the cache. + +### 1.3 The seam: the loader is blind + +The loader (the component that executes fetches and merges results) +knows almost nothing about caching. +It calls four hooks around each fetch and branches on exactly one thing: +the `Decision` enum (`Fetch` / `SkipFullHit` / `FetchPartial` / `FetchShadow`). +Everything else — keys, envelopes, TTLs, privacy, tags — lives behind the +`resolve.CacheController` / `resolve.RequestCache` interfaces, +implemented by the `cache` package. + +This seam is load-bearing: + +- The `resolve` package holds only contract types (`cache_controller.go`) + and never imports the `cache` package, so there is no cycle + and the loader compiles without any cache logic. +- With a nil controller the loader never allocates a handle, never takes a lock, + never enters cache code — the **runtime no-op gate**. +- All cache behavior is testable through the seam with recording fakes, + without touching loader internals. + +### 1.4 The three planes + +Work happens at three times, and each plane only produces data for the next: + +1. **Configuration** (integrator startup): + the declarative cascade in `plan/cacheconfig` — global defaults, + per-subgraph overrides, per-type declarations, per-root-field entries. + Pure data, no cache logic, importable by everything. +2. **Plan time** (per operation, cacheable): + a second planner walk records what each fetch returns (`ProvidesData`), + the path builder isolates cached root fields into their own fetches, + and postprocess resolves the cascade into one `resolve.FetchCacheConfig` per fetch + and freezes the key spec from the fetch's representation node. + Only static data is produced — plans stay shareable across requests. +3. **Runtime** (per request): + the controller renders keys against the request's items, + reads L1 then the store, decides, splices or writes. + Everything request-specific (argument values, requester identity, header hashes) + is derived here and only here. + +If you remember one rule when extending the feature: +**push work to the earliest plane that can hold it**. +Plan-time work is amortized across every request that reuses the plan. + +## 2. Life of a cached request — the code path + +The walkthrough below names the actual functions, in call order. +Scenario: `{ me { favoriteProduct { upc stock } } }`, +where the `inventory` subgraph (datasource `1`) is configured with `DefaultTTL: time.Minute`. +The plan chains three fetches: `users` root → `products` entity → `inventory` entity. + +### 2.1 Plan time + +1. `plan.Planner.Plan` finishes its normal planning walks, then — + only when `Configuration.Caching != nil` — runs `cacheProvidesDataVisitor.walk` + on a dedicated walker (`plan/cache_provides_data_visitor.go`). + For every planner (= every fetch) it builds the exact field tree that fetch returns: + the inventory fetch's tree is `{stock}` with `OnTypeNames: [Product]`. + Aliases (`Field.OriginalName`), argument bindings (`Field.CacheArgs`), + and the entity-boundary reset are recorded here. + The trees attach to the plan as a side table keyed by `*FetchInfo` + (`GraphQLResponse.CacheProvidesData()`), shared by the initial response and all defer groups. +2. Postprocess calls `cache.Configurator.ConfigureCaching` + (wired in `postprocess/postprocess.go`, entry in `cache/configure_caching.go`). + For each fetch, `fetch_cache_configurator.go` resolves the cascade: + `caching.Resolve("inventory")` yields the effective subgraph config, + `Entities([Product])` says "cached, TTL 1m, public", + and a `resolve.FetchCacheConfig` is assembled and attached to the fetch. + `cache_key_builder.go` freezes the key spec: + a pointer to the fetch's own representation node plus scope metadata. +3. `optimize_l1_cache.go` walks all fetch trees of the response + (root plus every defer group) and narrows `cfg.L1`: + only fetches that provably have an L1 provider/consumer partner keep it, + so a lone entity fetch does not pay L1 write costs for nothing. + +### 2.2 Request start + +4. The loader reaches the inventory fetch in `resolveSingle` + and calls `Loader.cachePrepare` (`resolve/loader.go`). + The two uncached fetches before it took the other branch: + a configured controller with a config-less fetch fires `RequestCache.OnUncachedFetch`, + which only tells the client-policy aggregate + "part of this response came from outside the cache". +5. `Loader.cacheRequest` lazily creates the per-request surface: + `Controller.BeginRequest` (`cache/controller.go`) runs at most once per request, + under the request's data lock, + and the returned `requestCache` is shared by reference across all defer-group loaders. + +### 2.3 The lookup + +6. `requestCache.PrepareFetch` → `prepareFetch`. + It opens ONE `CacheTransaction` (`in.Arena.Begin()`), + which takes the request's single `DataBuffer` lock for the whole hook body — + this is the entire concurrency story, there are no internal mutexes + (except the client-policy aggregate's own, see §3.9). +7. `newFetchKeyTemplate` builds the per-fetch key template ONCE: + `resolveL2Access` decides store access and the privacy partition (§3.7), + `argsDigest` folds parameterized-field argument values (§3.3). +8. `prepareItems` renders each item's keys via `cacheKeyTemplate.render`: + the L1 key is the raw preimage, the L2 key the versioned digest. + `serveFromL1` checks the request-lifetime map first; + remaining items go into ONE `storeGetMany` call. +9. `applyStoreEntry` accepts or rejects each returned entry: + decode (`decodeEnvelope`), scope check (`servableScope`), + then either the negative-sentinel short-circuit or the coverage walk (`covers`). + Accepted values are stored on the handle in NORMALIZED form and populate L1. +10. The decision falls out of the item states: + every item covered → `DecisionSkipFullHit`; + some covered and `EnablePartialCacheLoad` → `DecisionFetchPartial` + (with `handle.BatchFetchKeep` marking the still-missing buckets); + a shadow-mode read that found something to compare → `DecisionFetchShadow` + (the loader treats it exactly like a miss); otherwise `DecisionFetch`. + +### 2.4 The fetch (or its absence) + +11. On `SkipFullHit` the loader skips the network load entirely, + and `mergeResult` early-returns into `OnFetchSkipped`, + where `spliceCachedItem` denormalizes each cached value + to the requesting operation's aliases (`denormalizeToSelection`) + and merges it at the fetch's merge path. + A pure hit owes no writes. +12. On `FetchPartial` the loader's `assembleBatchInput` renders the final batch input + from pre-rendered per-bucket segments (`resolve/batch_input_assembly.go`), + keeping only the missing representations — the reduced list is never parsed back from bytes. +13. On `Fetch`/`FetchShadow` the fetch runs unchanged. + +### 2.5 The merge and the write + +14. After merge processing, `Loader.cacheMerge` dispatches on the decision: + `OnFetchSkipped` for full hits, `OnFetchResult` for everything else + (the partial arm splices covered buckets AND realigns + merges the fetched ones + in `onPartialBatchResult`, one hook, one lock acquisition). +15. `OnFetchResult` applies the write gate — + `!FetchFailed && !HasErrors && ResponseData != nil && != null`; + `EmptyEntity` is the one non-failure that still writes (the negative sentinel) — + then `cachingDecisionFor` runs the storability ladder (§3.6) + over the response's `Cache-Control` header and the static config. +16. `writeFetchedValue` normalizes the value to schema shape (`normalizeToSchema`), + puts it into L1, and `deferSet` encodes the envelope and queues the write. + Nothing hits the store yet. +17. Shadow mode inserts one step before the write: + `CacheObserver.CompareShadow` byte-compares the stashed would-have-served value + against the fresh data. + +### 2.6 Request end + +18. After the whole tree (root + every defer group) resolves, + `requestCache.EndRequest` flushes all queued writes in ONE `SetMany` + and finalizes observation. + It runs after the request arenas are released, + so it must never touch arena-owned values — everything it consumes is plain heap data + (this is a real trap, see §6). +19. The router reads `Context.CacheResponseInfo()` for the client cache answer (§3.9). + +## 3. Deep dives + +### 3.1 The configuration cascade (`plan/cacheconfig`) + +The cascade is three levels of pure data: +`GlobalCacheConfig` → `SubgraphCacheConfig` (pointer fields, `nil` = inherit) → +`TypeCacheConfig` / `RootFieldCacheConfig`. +Consumers never walk the levels themselves; +`CachingConfiguration.Resolve(subgraphID)` produces an `EffectiveSubgraphConfig`, +and its two methods answer the only two questions the planner asks: + +- `Entities(typeNames)` — for an entity fetch over one or more concrete types + (an abstract-type batch fetch can resolve several). + Each type contributes its declaration or the subgraph default; + the fetch takes the MINIMUM lifetime and turns private if ANY contribution is private. + A `MaxAge: 0` declaration is a veto for the whole fetch, sentinel included. +- `RootField(typeName, fieldName)` — an entry must exist for the exact coordinate; + a root field is never cached by a bare `DefaultTTL`. + The TTL ladder (coordinate → subgraph → global) fills a zero TTL in the entry. + +Why enablement is derived rather than switched: +a positive resolved TTL, a `NegativeCacheTTL`, or shadow mode IS the intent to cache; +a separate boolean would just be one more thing to keep consistent. +`ExtractTypeCacheConfigs` (`cache_directive.go`) turns `@cache(maxAge:, scope:)` +directives from a subgraph SDL into the `Types` map, +skip-and-warn on malformed declarations — configuration reading never fails a boot. + +### 3.2 The provides-data walk (`plan/cache_provides_data_visitor.go`) + +The cache needs to know, per fetch, the exact tree of fields that fetch RETURNS — +for coverage checks, for normalization, and for the argument digest. +The main planning walk cannot give this cheaply +(its visitor state is deep in fetch construction), +so a second, filter-free walk runs after planning, +reading `fieldPlanners` (the field → planner-IDs attribution the main walk left behind). + +Mechanics worth knowing before touching it: + +- It maintains a per-planner frame stack (`currentFields`) mirroring the walk depth, + and pops frames by field ref (`popFields`). +- The **entity-boundary reset**: a nested entity fetch provides the ENTITY's fields, + not the path from the query root down to it. + When the walk enters the field where a nested fetch's entity begins, + the tree for that planner restarts at the entity object, + and its direct children get `OnTypeNames` (the entity type condition). +- Aliases: the tree's `Field.Name` is the RESPONSE key (the alias); + `OriginalName` carries the schema name when they differ. + `ComputeHasAliases` then marks every object with aliased or parameterized fields below, + which is the gate the transform walks and the args digest run on — + unaliased, argument-free fetches skip all of that work. +- Arguments: `captureFieldCacheArgs` records `(argName, variableName)` pairs — + the VALUES are resolved per request, plan-time only records the binding. + Root-operation-field arguments are deliberately not captured per field; + they are part of the root-field key instead. + +The walk is gated on `Caching != nil` and proven plan-identical when the config enables nothing. + +### 3.3 Keys (`cache/cache_key_template.go`, `cache_key_builder.go`) + +`buildEntitySpec` / `buildRootFieldSpec` freeze the plan-time spec: +for entities, literally a pointer to the fetch's representation node +(plan-owned, read-only at runtime). +At request time `newCacheKeyTemplate` derives one template per fetch, +and `render` produces both keys per item from ONE canonical rendering: + +```text +body = {"__typename":"Product","representation":{"upc":"1"}[,"args":""] +L1 = 1:} +preimage = v1:1:[,"partition":""]} +L2 = v1:1: +``` + +Details that answer most "why" questions: + +- The canonical rendering writes bytes directly (no intermediate astjson values) — + this path is the hit path's hot loop and was profiled into this shape. +- The rendering rules mirror the fetch input rules exactly: + conditioned fields skip non-matching types, null/absent key fields abort, + and an aborted key means "this item is simply not cached", never an error. +- Numbers are unified with strings of the same literal (`1` == `"1"`), + but no float parsing happens (`1` != `1.0`) — a conservative extra miss + beats corrupting a 64-bit integer beyond 2^53. +- The `args` digest exists to stop interleaved traffic with different argument values + from replacing each other's entries on every write (the "ping-pong" problem). + It is a digest of sorted normalized field PATHS with per-field value-hash suffixes, + so it is order-, alias-, and variable-name-independent. +- The format version (`cacheFormatVersion = "v1"`) leads the key AND its hashed preimage. + Changing anything about the layout or envelope means bumping it, + which makes every old entry unreachable instead of misreadable. + There is deliberately no migration story — caches refill. +- Root-field keys hash `{TypeName}.{FieldName}:{name-sorted variables}`. + Query text is excluded so alias variants share entries; + this is safe because operations are normalized with variable extraction, + so literals cannot hide in the query text. + KNOWN BUG: the variable set is the request's, not the fetch's — + two calls of one cached root field in one operation collide on one key, + and client variable names fragment entries (see `6-open-issues.md`). + +### 3.4 Transforms and coverage (`cache/transform.go`, `coverage.go`) + +Values are stored NORMALIZED and served DENORMALIZED: + +- `normalizeToSchema` (write path) rewrites response keys to schema names + (via `OriginalName`) with argument suffixes folded in + (`stockHistory(days:3)` → `stockHistory_<16-hex>`), + recursively, preserving unselected fields (`__typename`, key fields) as-is. +- `denormalizeToSelection` (serve path) rebuilds the value + in the requesting operation's alias shape, in selection order, + appending cached-only extras so no data is lost on write-back. + It always builds a fresh transaction-owned value, + which doubles as the aliasing-safe copy for the splice. +- `normalizedFieldName` is the single derivation both walks and the coverage walk share — + the three key spaces cannot diverge because there is only one function. + +`covers` is the always-on serve guard: +an entry is served only if it contains every field of the fetch's ProvidesData tree, +null accepted only where the schema allows it, +conditioned fields checked against the value's own `__typename`. +Because stored names carry argument suffixes, +an argument-mismatched field fails coverage — a miss, never a wrong hit. + +### 3.5 The envelope (`cache/envelope.go`) + +Every L2 value is `{"data":…,"cc":{"ttl":…,"created":…,"scope":…}}`. +The `cc` record makes an entry self-describing: +remaining freshness is computable from the entry alone +(`ttl - (now - created)`), so the store's own `RemainingTTL` report is optional. +Decode failures of any kind are a miss the next write repairs — never an error. +The negative sentinel is `"data":null` with the same `cc` record. + +The envelope used to carry a `types` map as a schema-drift guard; +it was removed 2026-08-10. +**There is currently NO schema-drift protection**: +an entry written before a schema change is served as long as it decodes and covers. +The open answer is deploy-time purging by `type:` tags (see `6-open-issues.md`). + +### 3.6 Freshness (`cache/cache_control.go`) + +`parseResponseCacheControl` reads `max-age`, `no-store`, `no-cache`, `private` +(first well-formed `max-age` wins, storability flags sticky, malformed dropped), +and `resolveCaching` runs the two-tier ladder: +header `max-age` is the runtime truth, the static cascade the fallback, +`no-store`/`no-cache` kill both layers, `MaxTTL` clamps the winner. +The decision is per fetch RESULT — one HTTP response, one header, one TTL, +shared by every entity entry written from a batch. + +Two subtleties: + +- `no-cache` maps to "do not store" because this cache cannot revalidate. +- A runtime-only `private` (header says private, statics say public) + drops the store writes but keeps L1 — inside one request the data is one requester's anyway. + +### 3.7 Privacy (`resolveL2Access`, `cache_key_template.go` partitions) + +Statically-private fetches key every entry under a partition segment: +sha256 of the requester identity, source-tagged before hashing +(`i:` for the `PrivatePartitionProvider` hook, `h:` for the forwarded-header hash) +so the two sources can never forge each other. +The provider is called at most once per subgraph per request (`hookIdentity` caches it), +because it is an integrator callback that may parse a JWT. + +The load-bearing rule: **no identity ⇒ no L2 at all** for that fetch — +no read, no write, sentinel included — +because a shared key would leak one requester's data to everyone. +L1 stays fully functional unpartitioned (one request = one requester), +so privacy costs cross-request reuse, never in-request reuse. +Envelopes record their scope and `servableScope` discards mismatches in both directions — +that guard catches configuration drift between deployments. + +### 3.8 Tags (`cache/cache_tags.go`) + +Keys are identity and never externally addressable +(they contain hashes of representation values); +tags are the deliberate addressing layer for invalidation. +Every write carries `subgraph:{name}`, `type:{name}:{TypeName}`, +and for entities `entity:{name}:{TypeName}:{digest of the @key subset ONLY}`. +The entity digest excluding `@requires`/args/partitions is the point: +every variant of one entity shares one tag, +so "this entity changed" is a single purge that clears values, +argument variants, private copies, and sentinels alike. +Tags ride on the store `Item`, never inside the envelope — +index maintenance and delete-by-tag are the store implementation's business. + +### 3.9 The client cache answer (`cache/cache_response.go`) + +`responseAggregate` folds one contribution per fetch at the point where +that fetch's cacheability is DECIDED (including failure paths and prepare give-ups), +which is why it carries its own mutex instead of the transaction lock — +some folds happen outside any transaction. +The rules: min remaining freshness wins, any uncacheable part forces `NoStore`, +an L1-served part contributes nothing (its origin fetch already folded), +a config-less fetch is a zero that cannot stand alone +(an operation the cache never touched has NO policy, not `no-store`), +and `@defer` suppresses the whole answer +(headers ship with the first frame and cannot describe the rest). +The aggregate outlives the request cache +(`SetCacheResponseInfoSource` survives `endCacheRequest`) +so the router can read it after resolution. + +### 3.10 Observability (`cache/observer.go`, ART) + +`CacheObserver` is composed inside the controller — the loader never sees it. +`TraceObserver` assembles a per-fetch `CacheTrace` +(decision, served-from layer, per-item key/hit/negative/remaining-TTL) +and attaches it to the fetch's ART trace. +Because the trace extension serializes DURING `Resolve` +while `EndRequest` runs after the response is written, +the resolver calls `FlushTraces` right before rendering when tracing is on — +idempotent per handle, same no-arena contract as `EndRequest`. + +## 4. Testing: how to run, what exists, how to extend + +Commands (run from the module directory, `v2/` or `execution/`): + +```sh +gotestsum --format=short -- ./pkg/engine/cache/... -race # unit suites (v2/) +gotestsum --format=short -- ./cachingtesting/... -race # e2e suites (execution/) +golangci-lint run ./pkg/engine/cache/... # lint, config resolves from repo root +``` + +The complete file-by-file test map is in [README §7](1-readme.md#7-how-it-is-tested). +The layering logic: + +- **Unit suites** (`v2/pkg/engine/cache/*_test.go`) drive the controller directly + with a fake store that records a full op log, + under `testing/synctest` so TTL arithmetic is exact + (sleep past an expiry inside the bubble — instant in fake time). +- **Plan/contract suites** pin plan shapes and the seam contract + (no-op gates, `Equals` dedup safety, fetch-interface polymorphism). +- **e2e suites** (`execution/cachingtesting`) run the REAL engine + over real `httptest` subgraph doubles and assert complete responses, + complete store-op logs, and subgraph request counts. + The doubles are rule-based (`Rule(match, response)`) and count requests, + so "zero network on hit" is a first-class assertion. + +Adding an e2e scenario: + +1. Check whether the committed fixture schema already supports it + (`execution/cachingtesting/subgraphs/*.graphql`, composed `config.json`). +2. If not, edit the subgraph SDL and rerun `compose.sh` (needs `npx wgc`); + commit both the SDL and the regenerated `config.json` — + tests never compose at runtime. +3. Write a new `*_e2e_test.go` file per logical area — never append to an existing one. + Fresh `FakeStore` per subtest; assert full op logs with `NormalizeStoreOpsClock`; + pin envelope values literally. +4. Every pinned key digest embeds the format version — + if you change key material, expect to re-pin digests + (get the new values from the failure output, they are authoritative). + +Conventions that are enforced in review: +full-value equality only, no `.golden` files, no `Contains`, +`t.Context()` everywhere, `require` for preconditions vs `assert` for checks, +fresh test files per unit, self-contained subtests over shared helpers. + +## 5. Change recipes + +**Add a config knob** — +add the field to `GlobalCacheConfig` (+ pointer twin on `SubgraphCacheConfig` if per-subgraph), +thread it through `Resolve`/`EffectiveSubgraphConfig`, +consume it in `fetch_cache_configurator.go` into `FetchCacheConfig`, +extend `FetchCacheConfig.Equals` AND its per-field mutation rows in +`resolve/cache_config_test.go` (a field missing from `Equals` silently conflates +plans under dedup), and cover it in `cacheconfig` unit tests plus one e2e. + +**Add an observability signal** — +extend `resolve.CacheObserver` (interface change: update `TraceObserver` +and the `RecordingObserver` double in `cachetesting/fakes.go`), +fire it from the controller at the decision point, +and pin it in `observer_test.go` plus the relevant e2e op log. + +**Change anything about key material or the envelope** — +bump `cacheFormatVersion`. +Old entries become unreachable by construction; that is the migration story. +Then re-pin every digest in the test suites. + +**Touch the loader hooks** — +re-read the concurrency comment on `requestCache` first. +Every mutable field is guarded by the external `CacheTransaction` lock; +a new hook must either open a transaction or provably touch only its own data. +Run the resolve and cachingtesting suites with `-race` — they are built to catch this. + +**Anything involving `@defer`** — +remember the request cache is SHARED across defer-group loaders, +L1 is the mechanism that makes cross-group reuse work, +and the client cache answer is suppressed for deferred responses. + +## 6. Gotchas — the traps that already bit + +- **The EndRequest arena trap.** + `EndRequest` (and `FlushTraces`) run after the request arena is released. + Dereferencing any arena-owned `astjson.Value` still on a handle + (`ItemCacheState.Item`, `FromCache`, shadow stash values) reads reused memory. + Everything consumed at request end must be plain heap data — strings, durations, copied bytes. + The contract is written on `RequestCache.EndRequest`; take it literally. +- **Structural copies at L1 boundaries.** + Values entering and leaving L1 are `StructuralCopy`-isolated. + Skipping a copy "because it looks safe" lets a later merge mutate a cached value in place; + the corruption shows up in an unrelated request's response. +- **`Equals` and plan dedup.** + Fetch dedup compares `FetchCacheConfig` values. + A field added to the config but not to `Equals` means two fetches with different + cache policies can be merged into one — silently, and only under specific plans. +- **Stale LSP diagnostics.** + This codebase's history includes several rounds of diagnostics claiming + compile errors that did not exist on disk. + Trust `go build` / `go vet`, not the editor overlay. +- **Tabs vs the Edit tool.** + Go files use tabs; anchor edits on unique in-line substrings, + write new code with any indentation, and `gofmt -w` after. +- **The subgraph header is per HTTP response.** + Batch entity fetches get ONE `Cache-Control` for N entities; + do not design anything assuming per-entity freshness from the origin. +- **No schema-drift guard exists** (§3.5). + Do not assume stale-shaped entries are detected; they are not, by design, for now. + +## 7. Debugging toolbox + +- **The op log is the ground truth.** + `cachetesting.NewFakeStore()` records every `GetMany`/`SetMany` with keys, hit flags, + values, TTLs, and tags; most questions ("why did this miss?") are answered by + printing `store.Ops()` in a scratch test. +- **ART traces**: enable the trace extension in a cachingtesting scenario + (see `art_e2e_test.go`) to see the cache section per fetch — + decision, layer, per-item keys and hits — exactly as an operator would. +- **Shadow mode** answers "would the cache have been correct?" in production shape: + reads and compares without ever serving. +- **Recording controllers** (`cachetesting.NewRecordingController`) script decisions + per fetch path and record every hook call with its inputs — + the tool for loader-seam questions. +- When a key mystifies you, remember the L1 key IS the readable preimage; + log it instead of reverse-engineering the L2 digest. + +## 8. Current state and open work + +Branch state at handover (2026-08-11): +the feature is complete in this repository and lives on `tmp-caching-squashed` +(one squashed feature commit plus follow-ups; the original 13-commit history +is preserved on `tmp-caching`). +Nothing is pushed. + +Working documents in this folder: + +- [6-open-issues.md](6-open-issues.md) — open design notes and known bugs: + the root-field cache-key bug (§3.3; fix it before enabling root-field caching broadly), + schema-deploy invalidation-need detection (now the only drift answer, see §3.5), + `s-maxage` support (needs a second freshness number through the pipeline), + entity-interface caching verification (fixtures missing; key renderer analysis done). +- [5-testing-on-js-subgraphs.md](5-testing-on-js-subgraphs.md) — findings from running the engine against live + Apollo-federation JS subgraphs (what works, what does not). +- [4-redis-adapter-report.md](4-redis-adapter-report.md) — the researched design for the router-side Redis store + (tag indexes, delete-by-tag, cluster behavior, implementation checklist). + +Remaining work lives in the **router repository** by design: + +- The Redis `Store` implementation (see `4-redis-adapter-report.md`). +- The invalidation endpoint bound to the tag vocabulary. +- HTTP emission of `Cache-Control` / `Cache-Tag` from `CacheResponseInfo`. +- Composition carrying the `@cache` directive to the engine configuration. + +Known dead code: `FetchCacheConfig.PopulateL2OnMutation` and `MutationTTLOverride` +are declared and compared in `Equals` but never set or read — delete or implement. diff --git a/docs/caching/4-redis-adapter-report.md b/docs/caching/4-redis-adapter-report.md new file mode 100644 index 0000000000..ca15c27a92 --- /dev/null +++ b/docs/caching/4-redis-adapter-report.md @@ -0,0 +1,317 @@ +# Redis store adapter — design report + +What the router-repository Redis adapter must implement to back the engine's response caching, +and what the invalidation endpoint on top of it needs. +Sources: the engine store contract (`v2/pkg/engine/cache/controller.go`), +the behavior spec (`2-behavior.md` §11, §14), +and the live-verified Apollo Router response-cache internals +(FINDINGS.md in the apollo-response-caching investigation workspace, Router 2.17.0). + +## 1. The contract the adapter fills + +```go +type Store interface { + GetMany(ctx context.Context, keys []string) ([]Entry, error) + SetMany(ctx context.Context, items []Item) error +} +// Item{Key string, Value []byte, TTL time.Duration, Tags []string} +// Entry{Value []byte, RemainingTTL time.Duration, OK bool} +``` + +Facts the design leans on: + +- Exactly ONE `GetMany` per cache-participating fetch (N keys for an N-bucket batch), + exactly ONE `SetMany` per request, flushed at request end — after the response is written, + so `SetMany` latency is off the client path but still inside the request goroutine. +- `GetMany` must return exactly one `Entry` per key, in key order; + a mis-sized answer is treated as an error by the engine. +- `Entry.RemainingTTL` may be 0 ("store cannot report one"); + the engine computes served freshness from the envelope's own `cc.ttl`/`cc.created`, + and uses `RemainingTTL` for trace/analytics only. +- Errors never fail a request: a `GetMany` error degrades to an all-miss, + a `SetMany` error drops the writes, both fire `CacheObserver.OnStoreError`. + The adapter should therefore fail FAST, not retry into the request path. +- Values are opaque bytes to the engine (the envelope), replace-only, one TTL per entry. +- Every `Item` carries the stable tag vocabulary, coarsest first: + `subgraph:{name}`, `type:{name}:{TypeName}`, + and for entities `entity:{name}:{TypeName}:{16-hex @key digest}`. +- Entry keys are `v1:{subgraph}[:h]:{16-hex digest}` — + the subgraph is a plaintext prefix of every key, which matters for §6. + +## 2. Read path — `GetMany` + +Options: + +- `MGET k1..kN` — one round trip, O(N), values in request order, nil for absent keys. + Cluster caveat: `MGET` is a single multi-key command; + the server rejects it with `CROSSSLOT` when keys hash to different slots, + and go-redis routes the whole command by one key rather than splitting it. +- Pipelined per-key `GET` — one logical round trip in standalone mode, + and in cluster mode go-redis groups the pipeline's commands per node + and runs the sub-pipelines concurrently, so it is cluster-safe by construction. + +`RemainingTTL`: adding pipelined `PTTL` per key doubles the read command count +for a value the engine only surfaces in traces. +The envelope already carries the entry's own freshness record, +so the correctness-relevant remaining freshness never depends on the store's answer. + +**Recommendation:** +implement `GetMany` as a pipelined `GET` per key (works identically standalone and cluster), +special-case `len(keys) == 1` to a plain `GET`, +and return `RemainingTTL: 0` for every entry. +Offer an opt-in `ReportRemainingTTL` knob that adds pipelined `PTTL` calls +for installations that want exact trace numbers, default off. +Treat a per-key error inside the pipeline as a miss for that key (`OK: false`) rather than +failing the whole batch, but return a batch-level error when the connection itself failed — +the engine turns that into an all-miss anyway. + +## 3. Write path — `SetMany` + +Each item is independent: entries are replace-only and self-consistent, +so there is no cross-item atomicity requirement. +A torn batch (some items written, some dropped) leaves every written entry valid; +the dropped ones are re-written by a later request. + +**Recommendation:** +one pipeline per `SetMany` containing, per item: + +```text +SET {key} {value} PX {ttl_ms} +ZADD {index(tag)} GT {expiry_unix_ms} {key} # per indexed tag, see §4 +EXPIRE {index(tag)} {tag_ttl_s} NX # first write: the ZADD-created key has NO expiry +EXPIRE {index(tag)} {tag_ttl_s} GT # later writes: only ever EXTEND the index lifetime +``` + +`tag_ttl_s` is the item's TTL plus a small slack (Apollo uses entry TTL + 1s), +so an index never outlives its longest-lived member by more than the slack. +Use `PX` (relative) rather than `EXAT` for the value: +the engine hands the adapter a duration, not a deadline, +and relative expiry avoids clock-skew coupling between router and Redis. +The index score, by contrast, must be an absolute expiry timestamp (computed once, `now + TTL`), +because purging and pruning compare scores against wall-clock time. +`ZADD GT` (Redis ≥ 6.2) keeps a re-written entry from SHORTENING +an index's view of a member's lifetime when an older longer-lived write already registered it. +The `EXPIRE` pair (`NX`/`GT` options are Redis ≥ 7.0) is needed because +`EXPIRE ... GT` alone never fires on a key WITHOUT an expiry — +no-expiry counts as infinite — so the freshly ZADD-created index would live forever. +No MULTI/EXEC: a value written whose index member is lost only costs invalidation precision +for that one entry until it expires, which matches the engine's best-effort store stance. + +## 4. Tag indexes + +The invalidation endpoint needs tag → keys. +Two candidate structures per tag: + +- `SET` of entry keys — cheap adds, but members never expire; + a busy graph accumulates dead members forever without an external sweeper. +- `ZSET` with score = absolute expiry unix time — same add cost class, + members carry their own expiry information, + pruning is one `ZREMRANGEBYSCORE {index} -inf {now}`, + and purge-time reads can skip already-expired members for free. + +Apollo's live-verified choice is the ZSET: +members are full entry keys, score is the absolute expiry timestamp, +and the index key's own TTL is entry TTL + 1s. + +**Recommendation:** +ZSET per indexed tag, key `v1:idx:{tag}` — the `v1:` prefix keeps index and entry keyspaces +under one format version, and `idx` becomes a RESERVED subgraph name +(a datasource actually named `idx` would collide with the index namespace; +reject or rename it at adapter construction). +Score = expiry unix milliseconds. +Prune lazily on every purge (`ZREMRANGEBYSCORE` first) +plus a low-frequency background maintenance loop (Apollo runs one) — +e.g. iterate known index keys via `SCAN MATCH v1:idx:*` every few minutes +and `ZREMRANGEBYSCORE` each; cheap, incremental, and safe to skip under load. +Memory: one member costs the key string (~40–80 bytes for our digest keys) +plus roughly 60–90 bytes of ZSET overhead; +at one million entries × 2 indexed tags that is order-of ~300 MB — +which is exactly why the subgraph tag should NOT be a ZSET (§6). + +Mirror Apollo's documented caveat: indexes are additive-only. +Enabling an index later does not retro-index existing entries; +document that a flush (or waiting out the TTLs) is required. + +## 5. Delete-by-tag — the invalidation endpoint's primitive + +**Recommendation:** `InvalidateByTags(ctx, tags []string) (deleted int64, err error)`: + +```text +for each tag: + ZREMRANGEBYSCORE v1:idx:{tag} -inf {now_ms} # prune expired members first + loop: + keys = ZRANGE v1:idx:{tag} 0 511 # batches of ~512 + if empty: break + UNLINK keys... # count += reply + ZREM v1:idx:{tag} keys... + UNLINK v1:idx:{tag} +``` + +- `UNLINK` over `DEL`: same semantics, memory reclaim happens on a background thread, + so purging a large tag cannot stall the event loop other traffic runs on. +- Batching bounds both the reply size and the multi-key command width + (and in cluster mode go-redis fans the `UNLINK` batch out per node). +- Members deleted here stay ORPHANED in the OTHER tags' ZSETs + (an entity purge leaves the key listed under its type and subgraph tags). + That is harmless: purging an orphan is a no-op `UNLINK`, + and the member ages out of the index by score/TTL. + Apollo behaves the same way (endpoint deletes leave ZSET members to age out). +- Races with concurrent writes are acceptable: + a write that lands after the purge read is a FRESH entry that deserves to survive, + and a write that lands between `UNLINK` and `ZREM` merely re-orphans one member. + Replace-only entries mean no partially-invalidated value can exist. +- Return the summed `UNLINK` count so the endpoint can answer Apollo-style `{"count":N}`. + +## 6. The three granularities and their cardinalities + +| Tag | Cardinality of its key set | Index? | +|---|---|---| +| `entity:{sg}:{T}:{digest}` | a handful (arg variants, requires variants, partitions of ONE entity) | ZSET — this is the workhorse | +| `type:{sg}:{T}` | all cached entries of one type in one subgraph — thousands to millions | ZSET, but see below | +| `subgraph:{sg}` | every entry of the subgraph — up to the whole keyspace slice | NO index — use prefix SCAN | + +The entry-key layout makes the subgraph granularity index-free: +every key of subgraph `products` starts with `v1:products:`, header-hash variants included +(`v1:products:h:`), and partitioned keys too (the partition is inside the digest). + +**Recommendation:** +do not maintain the `subgraph:` ZSET at all — +implement subgraph purge as `SCAN MATCH v1:{sg}:* COUNT 1000` + batched `UNLINK`, +which also catches entries whose index members were lost. +`SCAN` is cursor-based and non-blocking; a subgraph purge is a rare, operator-initiated action +that can afford a full keyspace iteration. +Caveat: `MATCH` filters server-side but the cursor still walks the whole keyspace, +so on a shared Redis the cache should own its own logical DB (or run this rarely). +Skip `v1:idx:*` keys in the deletion (or purge the matching `v1:idx:*` too — cleaner). +Keep the ZSET for `type:` (bounded by a type's popularity, the schema-deploy purge unit) +and for `entity:` (tiny, the high-frequency business purge unit). +The engine still SENDS all three tags on every item; +which ones the adapter indexes is adapter configuration. + +## 7. Private partitions + +Partitioned entries differ only in the hashed key digest +(the `partition` segment is inside the hashed preimage) and carry the SAME tags as public ones — +by design, so one purge clears every requester's copy. +The ZSET design preserves this automatically: +each partitioned key is its own index member under the shared entity/type tag, +and the prefix SCAN for subgraph purge matches them all. +No identity material ever appears in tags or index keys — nothing to redact. + +## 8. Negative sentinels + +No special handling. +A sentinel is an ordinary item: envelope bytes `{"data":null,...}`, its own (shorter) TTL, +and the full tag set — the engine attaches tags to sentinels precisely so that +purging an entity also clears its "does not exist" record. +The adapter must not filter by value shape or TTL length; bytes are opaque. + +## 9. Cluster mode + +- Reads/writes: the pipelined per-key design (§2, §3) is already cluster-correct; + go-redis groups pipeline commands per node and runs them concurrently. + Apollo's storage layer solves the same problem from the other end: + it uses `MGET` and falls back to concurrent per-key `GET`s in cluster mode. + Starting with per-key pipelines skips the fallback complexity entirely. +- Do NOT hash-tag keys by subgraph (`v1:{products}:...`): + it would pin a whole subgraph's cache to one slot — a hot-spot and a memory-skew machine. + Losing slot co-location costs nothing here because no operation needs multi-key atomicity. +- Each tag's ZSET lives on one slot (single key), which is fine: + purge reads the ZSET, then fans `UNLINK` batches out per node. +- Subgraph purge via SCAN must iterate every master in the cluster + (go-redis `ForEachMaster` + per-node SCAN). + +## 10. Failure semantics — what the adapter still owes + +The engine already degrades gracefully; the adapter's job is to make failure CHEAP: + +- Per-op timeouts, separately configurable for read / write / invalidate + (Apollo exposes exactly this trio: `fetch_timeout`, `insert_timeout`, `invalidate_timeout`). + Respect the incoming context — the engine's request context bounds `GetMany`. +- A circuit breaker (Apollo ships one): + after M consecutive failures, open for T and answer `GetMany`/`SetMany` with an immediate error, + so a dead Redis costs nanoseconds per request instead of a timeout per fetch. + The engine's all-miss fallback turns this into "caching off" transparently. +- Bounded connection pool sized to the router's fetch parallelism; + pool exhaustion should fail fast, not queue behind the request. +- A max-value-size guard on write (skip the item, count it, no error to the engine) — + a single multi-megabyte entry should not be allowed to dominate memory and bandwidth. +- Never retry writes into the request path; drop and count. + +## 11. Operational concerns + +- **Expiry stampede**: the engine deliberately has no request coalescing, + so N concurrent requests after a popular entry expires all hit the origin. + Cheap mitigation in the adapter: optional DOWNWARD-only TTL jitter + (`redisTTL = ttl - rand(0..j%)`, default off, j ≤ 5). + Downward-only matters: the envelope records `cc.ttl`, + and a Redis TTL longer than the envelope's leaves entries in Redis + past the freshness the origin promised — + stale serves or dead weight, depending on how the read path treats them, + and neither is worth the jitter. + Real stampede protection (singleflight, stale-while-revalidate) is an engine follow-up, not adapter scope. +- **Eviction policy**: every cache key carries a TTL, so `volatile-ttl` or `volatile-lru` fit. + Avoid `allkeys-lru`: it can evict index ZSETs while their entries live, + silently breaking invalidation for those entries. +- **Compression**: the JSON envelope compresses 3–5× typically. + Worth having as an opt-in (LZ4/snappy above a size threshold, magic-byte prefix, + transparent on read since the adapter owns the bytes) — but ship without it first and measure. +- **Metrics** the adapter should emit (the engine's observer covers hit/miss semantics already): + op latency histograms per op kind, error and circuit-open counters, + payload size distribution, purge counts per tag kind, index ZSET sizes (sampled), + and skipped-oversize-write count. + +## 12. Schema-deploy invalidation (open design note) + +The engine has no schema-drift guard: +an entry written before a schema change is served as long as it decodes and covers the selection. +The agreed direction is composition-side diffing that purges `type:{sg}:{T}` for changed types. +The adapter needs nothing beyond §5 for this — +`InvalidateByTags` with a list of type tags is the whole API — +but it should accept MANY tags per call and return one summed count, +so a deploy purging dozens of types is one endpoint call and one audit line. +Until that lands, operators purge manually or size TTLs to deploy cadence. + +## 13. Comparison with Apollo Router's implementation + +| Aspect | This engine + proposed adapter | Apollo Router 2.17 (live-verified) | +|---|---|---| +| Entry key | `v1:{sg}[:h]:{16-hex xxhash64}` — short, digest-only | `version:1.2:subgraph:{sg}:type:{T}[:representation:{r}]:hash:{h}:data:{d}` — long, segmented, sha256 | +| Key inputs | fetch identity: representation + args + partition; NO query text | query-shape hash + supergraph SDL hash; every deploy cold-starts the cache | +| Cross-shape reuse | yes — coverage walk lets wider entries serve narrower queries | none — different shape ⇒ different hash ⇒ full miss | +| Value envelope | `{data, cc{ttl,created,scope}}`; tags NOT stored in the value | `{data, cache_control{created,maxAge,public}, cache_tags[...]}` | +| Tag index | ZSET `v1:idx:{tag}`, score = expiry ms; subgraph granularity via prefix SCAN, no index | ZSET `version:1.2:cache-tag:{...}`, score = expiry s, index TTL = entry TTL + 1s | +| Value expiry | `SET PX` relative | `EXAT` absolute | +| Index hygiene | lazy prune on purge + background `ZREMRANGEBYSCORE`; purge deletes the tag ZSET | background maintenance task; endpoint deletes leave ZSET members orphaned to age out | +| Invalidation API | router endpoint over `InvalidateByTags`; kinds map to tag strings | built-in endpoint, kinds subgraph/type/entity/cache_tag, 202 `{"count":N}`, shared-key auth | +| Batch reads | pipelined per-key GET (cluster-safe) | MGET with concurrent-GET fallback in cluster mode | +| Partial hits | per entity (reduced representations request) | per entity (`partial_hit` status) | +| Max-age vs config | header wins; static config is fallback; `MaxTTL` clamps | header wins outright; configured `ttl` is fallback, never a cap | + +## 14. Implementation checklist (ordered) + +1. Standalone client: pipelined `GetMany`/`SetMany` with PX TTLs, per-op timeouts, pool config. (S) +2. Unit tests against miniredis or a dockerized Redis: contract shape + (one Entry per key in order, opaque bytes round-trip, error ⇒ engine-visible error). (S) +3. Tag ZSET writes for `type:`/`entity:` tags, `ZADD GT` + `EXPIRE GT`. (S) +4. `InvalidateByTags`: prune → batched ZRANGE/UNLINK/ZREM → delete index; count return. (M) +5. Subgraph purge via per-master `SCAN MATCH v1:{sg}:*` + batched `UNLINK`. (M) +6. Circuit breaker + fail-fast behavior; wire `OnStoreError` expectations into tests. (M) +7. Cluster support pass: verify pipeline fan-out, per-master SCAN, no hash tags. (M) +8. Background index maintenance loop (`SCAN v1:idx:*` + `ZREMRANGEBYSCORE`). (S) +9. Metrics, max-size guard, optional TTL jitter, optional `ReportRemainingTTL`. (S) +10. Invalidation HTTP endpoint in the router: kind → tags mapping, shared-key auth, + `{"count":N}` responses, audit logging. (M) +11. Optional: compression behind a knob; measure first. (S) + +## 15. Open questions + +- User-defined cache tags (engine follow-up): once `Item.Tags` carries user values, + index cardinality becomes user-controlled — the adapter will want a per-tag-count guard + and possibly an allowlist, mirroring Apollo's `@cacheTag` format templates. +- `s-maxage` (engine follow-up, see notes): would lengthen entry TTLs relative to client TTLs — + no adapter change, but sizing assumptions shift toward long-lived entries + active purge. +- Format-version rollovers: bumping `v1:` orphans the old generation; + decide whether deploys should fire a `SCAN MATCH v0:*` cleanup or let TTLs drain it. +- Whether the type-tag ZSET should ALSO be optional (Apollo makes all indexes configurable); + recommended default: entity + type on, subgraph off (SCAN path instead). diff --git a/docs/caching/5-testing-on-js-subgraphs.md b/docs/caching/5-testing-on-js-subgraphs.md new file mode 100644 index 0000000000..0b5f37b416 --- /dev/null +++ b/docs/caching/5-testing-on-js-subgraphs.md @@ -0,0 +1,135 @@ +# 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). + 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. diff --git a/docs/caching/6-open-issues.md b/docs/caching/6-open-issues.md new file mode 100644 index 0000000000..6635ce5e56 --- /dev/null +++ b/docs/caching/6-open-issues.md @@ -0,0 +1,64 @@ +# 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. + +## 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 v1 (`docs/caching/specs/2026-08-06-header-driven-caching.md` §4.1): 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 §10 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: }`, 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 per-policy CacheName usually separates them 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. diff --git a/execution/cachingtesting/args_key_e2e_test.go b/execution/cachingtesting/args_key_e2e_test.go new file mode 100644 index 0000000000..643620120b --- /dev/null +++ b/execution/cachingtesting/args_key_e2e_test.go @@ -0,0 +1,302 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" +) + +// TestArgumentVariantsAreIndependentEntriesEndToEnd: interleaved traffic over +// two argument variants of one entity field warms TWO stable entries instead of +// replacing one shared entry on every request. Four requests, alternating the +// argument, give the hit pattern miss, miss, hit, hit — and the subgraph is +// asked exactly once per variant. +func TestArgumentVariantsAreIndependentEntriesEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + // One rule per argument value (the engine renames $days to $a in the + // rendered body); each rule's count proves how often its variant fetched. + days3 := Rule(`"a":3`, `{"data":{"_entities":[{"__typename":"Product","stockHistory":[1,2,3]}]}}`) + days1 := Rule(`"a":1`, `{"data":{"_entities":[{"__typename":"Product","stockHistory":[7]}]}}`) + inventory := Rules(days3, days1) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + query := `query($days: Int!) { me { favoriteProduct { upc stockHistory(days: $days) } } }` + + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[1,2,3]}}}}`, + ExecuteWithVariables(t, executionEngine, query, `{"days":3}`, controller)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[7]}}}}`, + ExecuteWithVariables(t, executionEngine, query, `{"days":1}`, controller)) + // The repeats are served from the entries the first two requests wrote — + // neither variant evicted the other. + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[1,2,3]}}}}`, + ExecuteWithVariables(t, executionEngine, query, `{"days":3}`, controller)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[7]}}}}`, + ExecuteWithVariables(t, executionEngine, query, `{"days":1}`, controller)) + + assert.Equal(t, int64(1), days3.Count.Load()) + assert.Equal(t, int64(1), days1.Count.Load()) + assert.Equal(t, int64(2), inventory.Requests()) + + // Two distinct keys — the argument value rides in the preimage — each read + // twice and written once, with its own envelope. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:1ea890ef1fe73466"}, + Hits: []bool{false}, // request 1: the days:3 entry does not exist yet + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + // request 1's write: the days:3 value under the days:3 key + Key: "v1:1:1ea890ef1fe73466", + Value: `{"data":{"stockHistory_f123752fc2272dfc":[1,2,3],"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + { + Kind: "GetMany", + Keys: []string{"v1:1:e58401b99256d16d"}, + Hits: []bool{false}, // request 2: days:1 looks under its OWN key and misses + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + // request 2's write: a SECOND entry, not a replacement + Key: "v1:1:e58401b99256d16d", + Value: `{"data":{"stockHistory_b487e21691ea4c86":[7],"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + // A DIFFERENT key, the SAME entity tag as the days:3 entry: + // the tag hashes the @key subset alone, so one purge of the + // product clears every argument variant of it. + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + { + Kind: "GetMany", + Keys: []string{"v1:1:1ea890ef1fe73466"}, + Hits: []bool{true}, // request 3: days:3 survived — days:1 wrote elsewhere + }, + { + Kind: "GetMany", + Keys: []string{"v1:1:e58401b99256d16d"}, + Hits: []bool{true}, // request 4: and days:1 survived too + }, + }, NormalizeStoreOpsClock(store.Ops())) +} + +// TestAliasedArgumentVariantsShareOneEntryEndToEnd: two variants of one +// parameterized field selected under aliases in a SINGLE operation stay fully +// cacheable — one key, one entry carrying both argument-suffixed names — and a +// second operation selecting the same two variants under DIFFERENT aliases is +// served from it. +func TestAliasedArgumentVariantsShareOneEntryEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + // The subgraph answers under the aliases the fetch sends. + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","recent":[1,2,3],"older":[7]}]}}`) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + firstBody := ExecuteWithVariables(t, executionEngine, + `query($long: Int!, $short: Int!) { me { favoriteProduct { upc recent: stockHistory(days: $long) older: stockHistory(days: $short) } } }`, + `{"long":3,"short":1}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","recent":[1,2,3],"older":[7]}}}}`, firstBody) + assert.Equal(t, int64(1), inventory.Requests()) + + // ONE entry for the whole selection, its aliases normalized away and both + // argument variants of stockHistory living side by side inside it. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:b26f0f685a0b663d"}, + Hits: []bool{false}, // first request: one key for both variants, nothing stored yet + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + // both variants in ONE entry, under their suffixed names + Key: "v1:1:b26f0f685a0b663d", + Value: `{"data":{"stockHistory_f123752fc2272dfc":[1,2,3],"stockHistory_b487e21691ea4c86":[7],"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + + // A differently-aliased operation with the SAME argument values renders the + // same digest, hence the same key, and is served without a fetch. + store.ResetOps() + secondBody := ExecuteWithVariables(t, executionEngine, + `query($a: Int!, $b: Int!) { me { favoriteProduct { upc fresh: stockHistory(days: $a) stale: stockHistory(days: $b) } } }`, + `{"a":3,"b":1}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","fresh":[1,2,3],"stale":[7]}}}}`, secondBody) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:b26f0f685a0b663d"}, + Hits: []bool{true}, // the other aliases derive the same digest, hence the same key + }, + }, store.Ops()) +} + +// TestArgumentlessSelectionKeepsItsKeyEndToEnd pins that a fetch selecting no +// parameterized field keys exactly as it did before the argument segment +// existed: the literal store key of the plain stock selection on the inventory +// subgraph, unchanged. +func TestArgumentlessSelectionKeepsItsKeyEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, // cold store: the plain stock selection misses + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + // the write lands on the read's key — no argument segment anywhere + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) +} + +// TestMatchingDigestStillRunsTheCoverageWalkEndToEnd: only PARAMETERIZED fields +// enter the digest, so two selections differing in a plain field share one key. +// The narrower entry is therefore still gated by the coverage walk — found in +// the store, rejected as not covering, refetched — and the widened entry then +// serves. +func TestMatchingDigestStillRunsTheCoverageWalkEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + // The warehouse selection identifies the first operation's fetch; the + // catch-all serves the second one, which asks for stock instead. + withWarehouse := Rule(`warehouse`, `{"data":{"_entities":[{"__typename":"Product","warehouse":{"location":"Berlin"},"stockHistory":[1,2,3]}]}}`) + withStock := Rule(``, `{"data":{"_entities":[{"__typename":"Product","stock":5,"stockHistory":[1,2,3]}]}}`) + inventory := Rules(withWarehouse, withStock) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + warehouseBody := ExecuteWithVariables(t, executionEngine, + `query($days: Int!) { me { favoriteProduct { upc warehouse { location } stockHistory(days: $days) } } }`, + `{"days":3}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","warehouse":{"location":"Berlin"},"stockHistory":[1,2,3]}}}}`, warehouseBody) + assert.Equal(t, int64(1), withWarehouse.Count.Load()) + + // Same entity, same argument value, a plain field swapped: the SAME key, + // found in the store, but the entry does not cover stock — so the fetch runs + // and rewrites the entry. + stockBody := ExecuteWithVariables(t, executionEngine, + `query($days: Int!) { me { favoriteProduct { upc stock stockHistory(days: $days) } } }`, + `{"days":3}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5,"stockHistory":[1,2,3]}}}}`, stockBody) + assert.Equal(t, int64(1), withStock.Count.Load()) + + // The rewritten entry covers the second selection: a repeat serves without a + // fetch. + repeatBody := ExecuteWithVariables(t, executionEngine, + `query($days: Int!) { me { favoriteProduct { upc stock stockHistory(days: $days) } } }`, + `{"days":3}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5,"stockHistory":[1,2,3]}}}}`, repeatBody) + assert.Equal(t, int64(1), withStock.Count.Load()) + assert.Equal(t, int64(2), inventory.Requests()) + + // One key throughout: Hits reports STORE presence, not servability — read 2 + // found the entry and the coverage walk still rejected it. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:1ea890ef1fe73466"}, + Hits: []bool{false}, // request 1: nothing written yet + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + // request 1's write: warehouse, no stock + Key: "v1:1:1ea890ef1fe73466", + Value: `{"data":{"warehouse":{"location":"Berlin"},"stockHistory_f123752fc2272dfc":[1,2,3],"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + { + Kind: "GetMany", + Keys: []string{"v1:1:1ea890ef1fe73466"}, + Hits: []bool{true}, // request 2: present, but it carries no stock + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + // request 2's write: the refetched value REPLACES the entry under the same key + Key: "v1:1:1ea890ef1fe73466", + Value: `{"data":{"stock":5,"stockHistory_f123752fc2272dfc":[1,2,3],"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + { + Kind: "GetMany", + Keys: []string{"v1:1:1ea890ef1fe73466"}, + Hits: []bool{true}, // request 3: covered this time, served + }, + }, NormalizeStoreOpsClock(store.Ops())) +} diff --git a/execution/cachingtesting/art_e2e_test.go b/execution/cachingtesting/art_e2e_test.go new file mode 100644 index 0000000000..c69e326f25 --- /dev/null +++ b/execution/cachingtesting/art_e2e_test.go @@ -0,0 +1,1556 @@ +package cachingtesting + +import ( + "bytes" + "encoding/json" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// normalizedTraceBody makes a traced response body pinnable: subgraph double +// URLs become their stable fixture form, real-clock cache-trace nanos become +// -1, and the whole body is indented for readable assertions. +func normalizedTraceBody(t *testing.T, subgraphs Subgraphs, body string) string { + t.Helper() + normalized := NormalizeCacheTraceClock(subgraphs.NormalizeURLs(body)) + var buf bytes.Buffer + require.NoError(t, json.Indent(&buf, []byte(normalized), "", " ")) + return buf.String() +} + +// TestARTCacheTraceEndToEnd asserts the COMPLETE response bodies — data plus +// the full ART trace in extensions, cache sections included — for the +// representative scenarios. Runs through the REAL ExecutionEngine over HTTP +// subgraph doubles. +func TestARTCacheTraceEndToEnd(t *testing.T) { + t.Run("L2 miss then hit", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cache.NewController(store, cache.NewTraceObserver()) + query := `{ me { favoriteProduct { upc stock } } }` + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + subgraphs := Subgraphs{"users": users, "products": products, "inventory": inventory} + executionEngine := NewEngine(t, caching, subgraphs) + + firstBody := normalizedTraceBody(t, subgraphs, ExecuteTraced(t, executionEngine, query, controller)) + assert.Equal(t, `{ + "data": { + "me": { + "favoriteProduct": { + "upc": "1", + "stock": 5 + } + } + }, + "extensions": { + "trace": { + "version": "1", + "info": { + "trace_start_time": "", + "trace_start_unix": 0, + "parse_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "normalize_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "validate_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "planner_stats": { + "duration_nanoseconds": 5, + "duration_pretty": "5ns", + "duration_since_start_nanoseconds": 20, + "duration_since_start_pretty": "20ns" + } + }, + "fetches": { + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "path": "", + "source_id": "3", + "source_name": "3", + "trace": { + "raw_input_data": {}, + "input": { + "body": { + "query": "{me {__typename id}}" + }, + "header": {}, + "method": "POST", + "url": "http://users.service" + }, + "output": { + "data": { + "me": { + "__typename": "User", + "id": "u1" + } + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://users.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "47" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 47 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "me", + "source_id": "0", + "source_name": "0", + "trace": { + "raw_input_data": { + "__typename": "User", + "id": "u1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on User {__typename favoriteProduct {upc __typename}}}}", + "variables": { + "representations": [ + { + "__typename": "User", + "id": "u1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://products.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "User", + "favoriteProduct": { + "__typename": "Product", + "upc": "1" + } + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://products.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "99" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 99 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "me.favoriteProduct", + "source_id": "1", + "source_name": "1", + "trace": { + "raw_input_data": { + "__typename": "Product", + "upc": "1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename stock}}}", + "variables": { + "representations": [ + { + "__typename": "Product", + "upc": "1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://inventory.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "Product", + "stock": 5 + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://inventory.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "59" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 59 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false, + "cache": { + "decision": "Fetch", + "hit": false, + "items": [ + { + "key": "v1:1:4f796e3bbd360fce", + "hit": false + } + ] + } + } + } + } + ] + } + } + } +}`, firstBody) + + // The second request is a FULL L2 hit: the inventory fetch is skipped + // (no input/output in its trace) and the cache section records the hit. + secondBody := normalizedTraceBody(t, subgraphs, ExecuteTraced(t, executionEngine, query, controller)) + assert.Equal(t, `{ + "data": { + "me": { + "favoriteProduct": { + "upc": "1", + "stock": 5 + } + } + }, + "extensions": { + "trace": { + "version": "1", + "info": { + "trace_start_time": "", + "trace_start_unix": 0, + "parse_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "normalize_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "validate_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "planner_stats": { + "duration_nanoseconds": 5, + "duration_pretty": "5ns", + "duration_since_start_nanoseconds": 20, + "duration_since_start_pretty": "20ns" + } + }, + "fetches": { + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "path": "", + "source_id": "3", + "source_name": "3", + "trace": { + "raw_input_data": {}, + "input": { + "body": { + "query": "{me {__typename id}}" + }, + "header": {}, + "method": "POST", + "url": "http://users.service" + }, + "output": { + "data": { + "me": { + "__typename": "User", + "id": "u1" + } + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://users.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "47" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 47 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "me", + "source_id": "0", + "source_name": "0", + "trace": { + "raw_input_data": { + "__typename": "User", + "id": "u1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on User {__typename favoriteProduct {upc __typename}}}}", + "variables": { + "representations": [ + { + "__typename": "User", + "id": "u1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://products.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "User", + "favoriteProduct": { + "__typename": "Product", + "upc": "1" + } + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://products.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "99" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 99 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "me.favoriteProduct", + "source_id": "1", + "source_name": "1", + "trace": { + "raw_input_data": { + "__typename": "Product", + "upc": "1" + }, + "single_flight_used": false, + "single_flight_shared_response": false, + "load_skipped": true, + "cache": { + "decision": "SkipFullHit", + "hit": true, + "items": [ + { + "key": "v1:1:4f796e3bbd360fce", + "served_from": "l2", + "hit": true, + "remaining_ttl_nanoseconds": -1 + } + ] + } + } + } + } + ] + } + } + } +}`, secondBody) + assert.Equal(t, int64(1), inventory.Requests()) + }) + + t.Run("two representations of one entity are two independent entries", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cache.NewController(store, cache.NewTraceObserver()) + // The deal -> product(sku) -> reviews(upc) -> product(upc) chain reaches + // ONE Product twice, but through two different representations: the + // first fetch sends {sku}, the second {upc}. The key IS the + // representation, so neither fetch can serve the other — both miss and + // both write, under different keys. + query := `{ deal(id: "d1") { product { name reviews { product { name } } } } }` + deals := Respond(`{"data":{"deal":{"__typename":"Deal","id":"d1","product":{"__typename":"Product","sku":"S1"}}}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","product":{"__typename":"Product","upc":"1"}}]}]}}`) + products := Rules( + Rule(`"sku":"S1"`, `{"data":{"_entities":[{"__typename":"Product","name":"Table","upc":"1"}]}}`), + Rule(`"upc":"1"`, `{"data":{"_entities":[{"__typename":"Product","name":"Table"}]}}`), + ) + subgraphs := Subgraphs{"deals": deals, "reviews": reviews, "products": products} + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": {DefaultTTL: ptr(time.Minute)}, + }, + } + executionEngine := NewEngine(t, caching, subgraphs) + + // The key hashes are deterministic (xxhash64 of the canonical + // representation preimage), so the WHOLE cache sections pin as literals. + body := normalizedTraceBody(t, subgraphs, ExecuteTraced(t, executionEngine, query, controller)) + assert.Equal(t, `{ + "data": { + "deal": { + "product": { + "name": "Table", + "reviews": [ + { + "product": { + "name": "Table" + } + } + ] + } + } + }, + "extensions": { + "trace": { + "version": "1", + "info": { + "trace_start_time": "", + "trace_start_unix": 0, + "parse_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "normalize_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "validate_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "planner_stats": { + "duration_nanoseconds": 5, + "duration_pretty": "5ns", + "duration_since_start_nanoseconds": 20, + "duration_since_start_pretty": "20ns" + } + }, + "fetches": { + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "path": "", + "source_id": "4", + "source_name": "4", + "trace": { + "raw_input_data": {}, + "input": { + "body": { + "query": "query($a: ID!){deal(id: $a){product {__typename sku}}}", + "variables": { + "a": "d1" + } + }, + "header": {}, + "method": "POST", + "url": "http://deals.service" + }, + "output": { + "data": { + "deal": { + "__typename": "Deal", + "id": "d1", + "product": { + "__typename": "Product", + "sku": "S1" + } + } + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://deals.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "95" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 95 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "deal.product", + "source_id": "0", + "source_name": "0", + "trace": { + "raw_input_data": { + "__typename": "Product", + "sku": "S1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename name upc}}}", + "variables": { + "representations": [ + { + "__typename": "Product", + "sku": "S1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://products.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "Product", + "name": "Table", + "upc": "1" + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://products.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "74" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 74 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false, + "cache": { + "decision": "Fetch", + "hit": false, + "items": [ + { + "key": "v1:0:6ad3afa747e670b2", + "hit": false + } + ] + } + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "deal.product", + "source_id": "2", + "source_name": "2", + "trace": { + "raw_input_data": { + "__typename": "Product", + "sku": "S1", + "name": "Table", + "upc": "1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename reviews {product {__typename upc}}}}}", + "variables": { + "representations": [ + { + "__typename": "Product", + "upc": "1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://reviews.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "Product", + "reviews": [ + { + "__typename": "Review", + "product": { + "__typename": "Product", + "upc": "1" + } + } + ] + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://reviews.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "130" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 130 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "BatchEntity", + "path": "deal.product.reviews.@.product", + "source_id": "0", + "source_name": "0", + "trace": { + "raw_input_data": { + "__typename": "Product", + "upc": "1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename name}}}", + "variables": { + "representations": [ + { + "__typename": "Product", + "upc": "1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://products.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "Product", + "name": "Table" + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://products.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "64" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 64 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false, + "cache": { + "decision": "Fetch", + "hit": false, + "items": [ + { + "key": "v1:0:b9d0094b63d1f2a8", + "hit": false + } + ] + } + } + } + } + ] + } + } + } +}`, body) + }) + + t.Run("shadow compare", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cache.NewController(store, cache.NewTraceObserver()) + query := `{ me { favoriteProduct { upc stock } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + subgraphs := Subgraphs{"users": users, "products": products, "inventory": inventory} + executionEngine := NewEngine(t, inventoryShadowCaching(), subgraphs) + + primeBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, primeBody) + + secondBody := normalizedTraceBody(t, subgraphs, ExecuteTraced(t, executionEngine, query, controller)) + assert.Equal(t, `{ + "data": { + "me": { + "favoriteProduct": { + "upc": "1", + "stock": 5 + } + } + }, + "extensions": { + "trace": { + "version": "1", + "info": { + "trace_start_time": "", + "trace_start_unix": 0, + "parse_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "normalize_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "validate_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "planner_stats": { + "duration_nanoseconds": 5, + "duration_pretty": "5ns", + "duration_since_start_nanoseconds": 20, + "duration_since_start_pretty": "20ns" + } + }, + "fetches": { + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "path": "", + "source_id": "3", + "source_name": "3", + "trace": { + "raw_input_data": {}, + "input": { + "body": { + "query": "{me {__typename id}}" + }, + "header": {}, + "method": "POST", + "url": "http://users.service" + }, + "output": { + "data": { + "me": { + "__typename": "User", + "id": "u1" + } + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://users.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "47" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 47 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "me", + "source_id": "0", + "source_name": "0", + "trace": { + "raw_input_data": { + "__typename": "User", + "id": "u1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on User {__typename favoriteProduct {upc __typename}}}}", + "variables": { + "representations": [ + { + "__typename": "User", + "id": "u1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://products.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "User", + "favoriteProduct": { + "__typename": "Product", + "upc": "1" + } + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://products.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "99" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 99 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Entity", + "path": "me.favoriteProduct", + "source_id": "1", + "source_name": "1", + "trace": { + "raw_input_data": { + "__typename": "Product", + "upc": "1" + }, + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename stock}}}", + "variables": { + "representations": [ + { + "__typename": "Product", + "upc": "1" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://inventory.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "Product", + "stock": 5 + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://inventory.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "59" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 59 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false, + "cache": { + "decision": "FetchShadow", + "hit": false, + "shadow": true, + "items": [ + { + "key": "v1:1:4f796e3bbd360fce", + "hit": false + } + ], + "shadow_compares": [ + { + "key": "v1:1:4f796e3bbd360fce", + "is_fresh": true, + "cache_age_nanoseconds": -1 + } + ] + } + } + } + } + ] + } + } + } +}`, secondBody) + // Shadow mode never serves from cache: BOTH requests hit inventory. + assert.Equal(t, int64(2), inventory.Requests()) + }) + + t.Run("partial batch", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cache.NewController(store, cache.NewTraceObserver()) + // The products double routes by the rendered first-argument variable; + // the reviews double by the representations: the priming run sends upc + // "1", the partial batch afterwards sends ONLY the missing upc "2". + products := Rules( + Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + Rule(`"variables":{"a":2}`, `{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`), + ) + reviews := Rules( + Rule(`"upc":"1"`, `{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","body":"great table"}]}]}}`), + Rule(`"upc":"2"`, `{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","body":"sturdy chair"}]}]}}`), + ) + subgraphs := Subgraphs{"products": products, "reviews": reviews} + executionEngine := NewEngine(t, reviewsPartialCaching(), subgraphs) + + primeBody := Execute(t, executionEngine, `{ products(first: 1) { upc reviews { body } } }`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"great table"}]}]}}`, primeBody) + + // One partial fetch: bucket 1 (upc "1") served from L2 under the primed + // key, bucket 2 (upc "2") fetched over the reduced batch and refreshed. + body := normalizedTraceBody(t, subgraphs, ExecuteTraced(t, executionEngine, `{ products(first: 2) { upc reviews { body } } }`, controller)) + assert.Equal(t, `{ + "data": { + "products": [ + { + "upc": "1", + "reviews": [ + { + "body": "great table" + } + ] + }, + { + "upc": "2", + "reviews": [ + { + "body": "sturdy chair" + } + ] + } + ] + }, + "extensions": { + "trace": { + "version": "1", + "info": { + "trace_start_time": "", + "trace_start_unix": 0, + "parse_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "normalize_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "validate_stats": { + "duration_nanoseconds": 0, + "duration_pretty": "", + "duration_since_start_nanoseconds": 0, + "duration_since_start_pretty": "" + }, + "planner_stats": { + "duration_nanoseconds": 5, + "duration_pretty": "5ns", + "duration_since_start_nanoseconds": 20, + "duration_since_start_pretty": "20ns" + } + }, + "fetches": { + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "path": "", + "source_id": "0", + "source_name": "0", + "trace": { + "raw_input_data": {}, + "input": { + "body": { + "query": "query($a: Int){products(first: $a){upc __typename}}", + "variables": { + "a": 2 + } + }, + "header": {}, + "method": "POST", + "url": "http://products.service" + }, + "output": { + "data": { + "products": [ + { + "__typename": "Product", + "upc": "1" + }, + { + "__typename": "Product", + "upc": "2" + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://products.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "93" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 93 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false + } + } + }, + { + "kind": "Single", + "fetch": { + "kind": "BatchEntity", + "path": "products", + "source_id": "2", + "source_name": "2", + "trace": { + "raw_input_data": [ + { + "__typename": "Product", + "upc": "1" + }, + { + "__typename": "Product", + "upc": "2" + } + ], + "input": { + "body": { + "query": "query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename reviews {body}}}}", + "variables": { + "representations": [ + { + "__typename": "Product", + "upc": "2" + } + ] + } + }, + "header": {}, + "method": "POST", + "url": "http://reviews.service" + }, + "output": { + "data": { + "_entities": [ + { + "__typename": "Product", + "reviews": [ + { + "__typename": "Review", + "body": "sturdy chair" + } + ] + } + ] + }, + "extensions": { + "trace": { + "request": { + "method": "POST", + "url": "http://reviews.service", + "headers": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip", + "deflate" + ], + "Content-Type": [ + "application/json" + ] + } + }, + "response": { + "status_code": 200, + "status": "200 OK", + "headers": { + "Content-Length": [ + "107" + ], + "Content-Type": [ + "application/json" + ] + }, + "body_size": 107 + } + } + } + }, + "single_flight_used": true, + "single_flight_shared_response": false, + "load_skipped": false, + "cache": { + "decision": "FetchPartial", + "hit": false, + "items": [ + { + "key": "v1:2:48d227258abb2a74", + "served_from": "l2", + "hit": true, + "remaining_ttl_nanoseconds": -1 + }, + { + "key": "v1:2:898c0bf202240771", + "hit": false + } + ] + } + } + } + } + ] + } + } + } +}`, body) + }) + + t.Run("regression: tracing off leaves fetch traces nil", func(t *testing.T) { + store := cachetesting.NewFakeStore() + query := `{ me { favoriteProduct { upc stock } } }` + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + // Tracing OFF: the response is the bare data — no extensions, no trace. + body := Execute(t, executionEngine, query, cachetesting.NewRealishCache(store, nil)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + }) +} diff --git a/execution/cachingtesting/batch_e2e_test.go b/execution/cachingtesting/batch_e2e_test.go new file mode 100644 index 0000000000..91e8ec3ad0 --- /dev/null +++ b/execution/cachingtesting/batch_e2e_test.go @@ -0,0 +1,132 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// reviewsEntityCaching enables entity caching for the reviews subgraph's +// Product (the batch entity fetch under products). +func reviewsEntityCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(time.Minute)}, + }, + } +} + +// TestBatchEntityL2EndToEnd: request 1 populates one entry PER entity from the +// batch response; request 2 is a full-batch hit with ZERO network to reviews. +// Runs through the REAL ExecutionEngine over HTTP subgraph doubles. +func TestBatchEntityL2EndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + query := `{ products(first: 2) { upc reviews { body } } }` + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + executionEngine := NewEngine(t, reviewsEntityCaching(), Subgraphs{"products": products, "reviews": reviews}) + expected := `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"2","reviews":[{"body":"Wobbly"}]}]}}` + + firstBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, firstBody) + assert.Equal(t, int64(1), reviews.Requests()) + + // The batch reads BOTH entity keys in one call and writes both in one call. + firstOps := store.Ops() + require.Len(t, firstOps, 2) + require.Len(t, firstOps[0].Keys, 2) + key1, key2 := firstOps[0].Keys[0], firstOps[0].Keys[1] + assert.NotEqual(t, key1, key2) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key1, key2}, + Hits: []bool{false, false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key1, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Solid"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + // Per-entity tags: the batch's items differ only in the + // digest of their own @key subset. + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: key2, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Wobbly"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(firstOps)) + + // Request 2's ops assert in isolation: a full-batch hit — the reviews + // upstream is NOT hit again, and one read of both keys, no writes. + store.ResetOps() + secondBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, secondBody) + assert.Equal(t, int64(1), reviews.Requests()) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key1, key2}, + Hits: []bool{true, true}, + }, + }, store.Ops()) +} + +// TestBatchEntityMixedRun: only ONE of two entities is primed; without +// PartialCaching the batch must fully refetch, produce the correct response, +// and write entries for ALL entities afterwards. +func TestBatchEntityMixedRun(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + + // The subgraph doubles route by REQUEST BODY: the one-product request + // primes upc 1; the two-product request returns both entities. The reviews + // double distinguishes the batches by their representations. + products := Rules( + Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + Rule(`"variables":{"a":2}`, `{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"3"}]}}`), + ) + reviews := Rules( + Rule(`{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"3"}`, `{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"New"}]}]}}`), + Rule(`"upc":"1"`, `{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]}]}}`), + ) + executionEngine := NewEngine(t, reviewsEntityCaching(), Subgraphs{"products": products, "reviews": reviews}) + + // Prime ONLY upc 1 through a single-product run. + primeBody := Execute(t, executionEngine, `{ products(first: 1) { upc reviews { body } } }`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]}]}}`, primeBody) + require.Equal(t, int64(1), reviews.Requests()) + + // The mixed batch (upc 1 primed, upc 3 not) refetches EVERYTHING. + query := `{ products(first: 2) { upc reviews { body } } }` + mixedBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"3","reviews":[{"body":"New"}]}]}}`, mixedBody) + assert.Equal(t, int64(2), reviews.Requests()) + + // Afterwards BOTH entities are cached: a repeat of the mixed batch hits + // with no further reviews request. + repeatBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"3","reviews":[{"body":"New"}]}]}}`, repeatBody) + assert.Equal(t, int64(2), reviews.Requests()) +} diff --git a/execution/cachingtesting/cache_control_e2e_test.go b/execution/cachingtesting/cache_control_e2e_test.go new file mode 100644 index 0000000000..af47e5cbfe --- /dev/null +++ b/execution/cachingtesting/cache_control_e2e_test.go @@ -0,0 +1,329 @@ +package cachingtesting + +import ( + "net/http" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// TestCacheControlTTLEndToEnd drives the two-tier TTL ladder through the REAL +// ExecutionEngine over REAL HTTP upstreams, so the subgraph's Cache-Control +// header travels the whole loader path into the written entry. +func TestCacheControlTTLEndToEnd(t *testing.T) { + t.Run("header max-age beats the configured DefaultTTL", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(5 * time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := RespondCacheControl(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`, "max-age=60") + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + // Both the envelope's cc.ttl and the store item's TTL carry 60s — the + // runtime truth — instead of the configured 5m. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) + + t.Run("a subgraph that sends no Cache-Control leaves the configured DefaultTTL in charge", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(5 * time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":300,"created":-1,"scope":"public"}}`, + TTL: 5 * time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) + + t.Run("MaxTTL clamps the header value and shows up in cc.ttl", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{MaxTTL: 30 * time.Second}, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(5 * time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := RespondCacheControl(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`, "max-age=3600") + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + // The clamp is a deliberate deviation from origin authority: 30s, not the + // hour the subgraph asked for. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":30,"created":-1,"scope":"public"}}`, + TTL: 30 * time.Second, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) + + t.Run("a root-field coordinate without its own TTL inherits the subgraph DefaultTTL", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(2 * time.Minute), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + }, + } + first1 := Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"}]}}`) + products := Rules(first1) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products}) + + body := ExecuteWithVariables(t, executionEngine, `query($first: Int!) { products(first: $first) { upc name } }`, `{"first":1}`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","name":"Table"}]}}`, body) + + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + // The coordinate entry alone declares participation; its lifetime came + // from the subgraph DefaultTTL rung of the ladder. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"}]},"cc":{"ttl":120,"created":-1,"scope":"public"}}`, + TTL: 2 * time.Minute, + Tags: []string{ + "subgraph:0", + "type:0:Query", + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) +} + +// TestCacheControlStorabilityEndToEnd covers the directives that decide whether +// a subgraph result is kept at all, end to end. +func TestCacheControlStorabilityEndToEnd(t *testing.T) { + t.Run("no-store keeps the result out of BOTH layers", func(t *testing.T) { + store := cachetesting.NewFakeStore() + // The initial inventory fetch selects {stock, warehouse} and answers + // no-store; the deferred fetch of the SAME representation selects {stock} + // alone and would ride L1 if anything had been written there. Its canned + // stock is tampered to 999, so an L1 serve is visible in the response. + products := Rules( + Rule(`product(upc: $a)`, `{"data":{"product":{"__typename":"Product","upc":"1"},"products":[{"__typename":"Product","upc":"1"}]}}`), + ) + initialFetch := &SubgraphRule{ + Match: `warehouse`, + Response: `{"data":{"_entities":[{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}}]}}`, + Headers: http.Header{"Cache-Control": []string{"no-store"}}, + } + deferredFetch := Rule(``, `{"data":{"_entities":[{"__typename":"Product","stock":999}]}}`) + inventory := Rules(initialFetch, deferredFetch) + executionEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"products": products, "inventory": inventory}) + + frames := ExecuteDefer(t, executionEngine, + `{ product(upc: "1") { stock warehouse { id location } } products(first: 1) { upc ... @defer { stock } } }`, + cachetesting.NewRealishCache(store, nil)) + assert.Equal(t, []string{ + `{"data":{"product":{"stock":5,"warehouse":{"id":"w1","location":"Berlin"}},"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + // stock 999, the tampered value: nothing was in L1 to serve, so the + // deferred group really fetched. + `{"incremental":[{"data":{"stock":999},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":false}`, + }, frames) + assert.Equal(t, int64(1), initialFetch.Count.Load()) + assert.Equal(t, int64(1), deferredFetch.Count.Load()) + + // Two lookups (one per fetch, neither served) and NOT ONE write: the + // deferred fetch answered without a Cache-Control and would have written, + // but it never reached the flush because its own result is a fresh miss + // whose write is the second op. + ops := store.Ops() + require.Len(t, ops, 3) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // The initial fetch's lookup. + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + // The deferred fetch's lookup under the SAME key: the no-store result + // left the entry unwritten, so it misses too. + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + // The request-end flush carries the DEFERRED fetch's value only — the + // no-store result contributed nothing. + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":999},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) + + t.Run("no-cache behaves as no-store: nothing is written", func(t *testing.T) { + store := cachetesting.NewFakeStore() + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(5 * time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := RespondCacheControl(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`, "no-cache, max-age=600") + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, cachetesting.NewRealishCache(store, nil)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + // The lookup happened; the max-age riding alongside no-cache never + // produced a write. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + }, store.Ops()) + }) + + t.Run("a runtime-private result writes no store entry and is reported once", func(t *testing.T) { + store := cachetesting.NewFakeStore() + observer := &cachetesting.RecordingObserver{} + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(5 * time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := RespondCacheControl(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`, "private, max-age=600") + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, cachetesting.NewRealishCache(store, observer)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + }, store.Ops()) + // One hint per fetch result, naming the datasource that declared private + // (datasource 1 is inventory, as its key prefix shows) and the remedy. + assert.Equal(t, []cache.UncacheablePrivate{ + {Subgraph: "1", Reason: cache.UncacheablePrivateResponseHeader}, + }, observer.UncacheablePrivate()) + + // The next request finds nothing and fetches again. + assert.Equal(t, body, Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, cachetesting.NewRealishCache(store, observer))) + assert.Equal(t, int64(2), inventory.Requests()) + }) +} diff --git a/execution/cachingtesting/cachingtesting.go b/execution/cachingtesting/cachingtesting.go new file mode 100644 index 0000000000..31644f4b20 --- /dev/null +++ b/execution/cachingtesting/cachingtesting.go @@ -0,0 +1,286 @@ +// Package cachingtesting is the plan-driven caching test harness: it loads the +// committed wgc-composed config.json of the dedicated caching subgraphs, runs +// the REAL v2 planner and postprocess over a query (with caching wired exactly +// as the engine Configuration wires it), and swaps every fetch's transport for +// an in-process fake. Tests then drive the public resolve entry points and +// assert complete responses — no hand-written plans, no golden files. +package cachingtesting + +import ( + "bytes" + "fmt" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/stretchr/testify/require" + "google.golang.org/protobuf/encoding/protojson" + + nodev1 "github.com/wundergraph/cosmo/router/gen/proto/wg/cosmo/node/v1" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astnormalization" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astparser" + "github.com/wundergraph/graphql-go-tools/v2/pkg/asttransform" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astvalidation" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/postprocess" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" + "github.com/wundergraph/graphql-go-tools/v2/pkg/operationreport" +) + +// PlanResult is the harness output: the postprocessed response (and defer +// response for defer plans) with all datasources swapped for fakes. +type PlanResult struct { + Response *resolve.GraphQLResponse + DeferResponse *resolve.GraphQLDeferResponse + Fakes *cachetesting.FakeRegistry + + // tb lets the name-keyed accessors fail fast on typo'd subgraph names + // instead of silently reading empty registry state. + tb testing.TB + // nameToID translates subgraph names to the ID-named datasources of the + // factory-built configuration, so tests can keep using subgraph names. + nameToID map[string]string +} + +// Inputs returns the exact input bytes every load of the fake datasource for +// the given SUBGRAPH NAME + fetch path received, in order. +func (p PlanResult) Inputs(name, path string) []string { + return p.Fakes.Inputs(p.datasourceID(name), path) +} + +// datasourceID resolves a subgraph name to its datasource ID; an unknown name +// fails the test immediately, so a typo can never make a LoadCount/Inputs +// assertion pass vacuously or register an unusable gate. +func (p PlanResult) datasourceID(name string) string { + p.tb.Helper() + id, ok := p.nameToID[name] + require.True(p.tb, ok, "unknown subgraph name %q", name) + return id +} + +// Gate attaches gate channels to the fake datasource for the given SUBGRAPH +// NAME + fetch path, re-swapping the trees so the gate takes effect. +func (p PlanResult) Gate(name, path string, gate cachetesting.DataSourceGate) { + p.Fakes.SetGate(p.datasourceID(name), path, gate) + if p.Response != nil { + cachetesting.SwapDataSources(p.Response.Fetches, p.Fakes) + } + if p.DeferResponse != nil { + cachetesting.SwapDataSources(p.DeferResponse.Response.Fetches, p.Fakes) + for _, g := range DeferGroups(p.DeferResponse) { + cachetesting.SwapDataSources(g.Fetches, p.Fakes) + } + } +} + +// LoadCount returns how often the fake datasource for the given SUBGRAPH NAME +// loaded at the given response path. +func (r PlanResult) LoadCount(subgraphName, path string) int64 { + return r.Fakes.LoadCount(r.datasourceID(subgraphName), path) +} + +// Plan runs the real planner + postprocess over query against the committed +// caching fixture config. The caching configuration's subgraph overrides are +// keyed by SUBGRAPH NAME (translated to datasource IDs internally); nil leaves +// caching fully unconfigured (the no-op baseline). responses feed the fake +// datasources and may also be keyed by subgraph name (or name:responsePath, +// responsePath, "*"). +func Plan(tb testing.TB, query string, caching *cacheconfig.CachingConfiguration, responses map[string]string) PlanResult { + tb.Helper() + + rc := routerConfig(tb) + factory := engine.NewFederationEngineConfigFactory(tb.Context()) + conf, err := factory.BuildEngineConfiguration(rc) + require.NoError(tb, err) + cfg := conf.PlannerConfig() + + def, parseReport := astparser.ParseGraphqlDocumentString(rc.EngineConfig.GraphqlSchema) + require.False(tb, parseReport.HasErrors(), "parse schema: %v", parseReport) + require.NoError(tb, asttransform.MergeDefinitionWithBaseSchema(&def)) + op, parseReport := astparser.ParseGraphqlDocumentString(query) + require.False(tb, parseReport.HasErrors(), "parse query: %v", parseReport) + + norm := astnormalization.NewWithOpts( + astnormalization.WithExtractVariables(), + astnormalization.WithInlineFragmentSpreads(), + astnormalization.WithRemoveFragmentDefinitions(), + astnormalization.WithRemoveUnusedVariables(), + astnormalization.WithEnableDefer(), + ) + var report operationreport.Report + norm.NormalizeOperation(&op, &def, &report) + astvalidation.DefaultOperationValidator().Validate(&op, &def, &report) + require.False(tb, report.HasErrors(), "normalize/validate: %s", report.Error()) + + nameToID := subgraphNameToDatasourceID(rc) + + // Wire caching exactly as NewExecutionEngine does for SetCaching: subgraph + // overrides keyed by datasource ID, FetchInfo force-enabled. + var processorOptions []postprocess.ProcessorOption + if caching != nil { + byID := cachingByDatasourceID(tb, caching, nameToID) + cfg.Caching = byID + cfg.DisableIncludeInfo = false + processorOptions = append(processorOptions, postprocess.EnableCaching(byID)) + } + + planner, err := plan.NewPlanner(cfg) + require.NoError(tb, err) + // Query plans are always included so tests can make full-value plan-shape + // assertions on the rendered fetch trees (instead of golden files). + raw := planner.Plan(&op, &def, "", &report, plan.IncludeQueryPlanInResponse()) + require.False(tb, report.HasErrors(), "plan: %s", report.Error()) + + postprocess.NewProcessor(processorOptions...).Process(raw) + + result := PlanResult{ + Fakes: cachetesting.NewFakeRegistry(translateResponseKeys(tb, responses, nameToID)), + tb: tb, + nameToID: nameToID, + } + switch p := raw.(type) { + case *plan.SynchronousResponsePlan: + result.Response = p.Response + case *plan.DeferResponsePlan: + result.Response = p.Response.Response + result.DeferResponse = p.Response + default: + tb.Fatalf("unsupported plan type %T", raw) + } + + cachetesting.SwapDataSources(result.Response.Fetches, result.Fakes) + for _, group := range DeferGroups(result.DeferResponse) { + cachetesting.SwapDataSources(group.Fetches, result.Fakes) + } + return result +} + +// cachingByDatasourceID re-keys the caching configuration's subgraph overrides +// from SUBGRAPH NAME to datasource ID — the key the engine matches fetches on. +func cachingByDatasourceID(tb testing.TB, caching *cacheconfig.CachingConfiguration, nameToID map[string]string) *cacheconfig.CachingConfiguration { + tb.Helper() + byID := &cacheconfig.CachingConfiguration{ + Global: caching.Global, + Subgraphs: make(map[string]cacheconfig.SubgraphCacheConfig, len(caching.Subgraphs)), + } + for name, subgraph := range caching.Subgraphs { + id, ok := nameToID[name] + require.True(tb, ok, "caching configured for unknown subgraph %q", name) + byID.Subgraphs[id] = subgraph + } + return byID +} + +// ResolveResponse drives the PUBLIC sync entry point over a harness plan with +// the given cache controller (nil = caching off) and returns the complete +// response body. +func ResolveResponse(tb testing.TB, resp *resolve.GraphQLResponse, controller resolve.CacheController) string { + tb.Helper() + + ctx := resolve.NewContext(tb.Context()) + if controller != nil { + ctx.SetCacheController(controller) + } + var buf bytes.Buffer + r := resolve.New(tb.Context(), resolve.ResolverOptions{MaxConcurrency: 16}) + _, err := r.ResolveGraphQLResponse(ctx, resp, nil, &buf) + require.NoError(tb, err) + return buf.String() +} + +// PrettyPlan renders the ENTIRE execution plan as one engine-pretty-printed +// string — the initial tree plus every defer group, each cached fetch carrying +// its cache config line — so plan tests assert the complete plan at once and +// read top to bottom. +func PrettyPlan(result PlanResult) string { + var b strings.Builder + b.WriteString(result.Response.Fetches.QueryPlan().PrettyPrint()) + for _, group := range DeferGroups(result.DeferResponse) { + fmt.Fprintf(&b, "Deferred (id: %d) ", group.DeferID) + b.WriteString(group.Fetches.QueryPlan().PrettyPrint()) + } + return b.String() +} + +// DeferGroups flattens a defer response's groups (the extracted Defers list +// plus the built DeferTree) so tests can reach every deferred fetch tree. +func DeferGroups(resp *resolve.GraphQLDeferResponse) []*resolve.DeferFetchGroup { + if resp == nil { + return nil + } + groups := append([]*resolve.DeferFetchGroup(nil), resp.Defers...) + return appendDeferTreeGroups(groups, resp.DeferTree) +} + +func appendDeferTreeGroups(groups []*resolve.DeferFetchGroup, node *resolve.DeferTreeNode) []*resolve.DeferFetchGroup { + if node == nil { + return groups + } + if node.Item != nil { + groups = append(groups, node.Item) + } + for _, child := range node.ChildNodes { + groups = appendDeferTreeGroups(groups, child) + } + return groups +} + +// routerConfig loads the committed wgc-composed config.json next to this file, +// so the harness works from any test package in the execution module. +func routerConfig(tb testing.TB) *nodev1.RouterConfig { + tb.Helper() + + _, thisFile, _, ok := runtime.Caller(0) + require.True(tb, ok, "cannot locate cachingtesting package dir") + data, err := os.ReadFile(filepath.Join(filepath.Dir(thisFile), "config.json")) + require.NoError(tb, err) + + var rc nodev1.RouterConfig + require.NoError(tb, protojson.Unmarshal(data, &rc)) + return &rc +} + +// subgraphNameToDatasourceID maps subgraph names to the datasource IDs the +// factory-built planner configuration uses (the router config keeps them in +// its subgraph list). +func subgraphNameToDatasourceID(rc *nodev1.RouterConfig) map[string]string { + out := make(map[string]string, len(rc.Subgraphs)) + for _, sg := range rc.Subgraphs { + out[sg.Name] = sg.Id + } + return out +} + +// translateResponseKeys rewrites subgraph-name response keys ("products", +// "products:path") to the datasource-ID keys FakeRegistry matches on at +// runtime; unknown prefixes (e.g. "*") pass through unchanged. Two source keys +// landing on the same registry key (a subgraph name AND its raw datasource ID) +// fail the test instead of letting map iteration pick a winner. +func translateResponseKeys(tb testing.TB, responses map[string]string, nameToID map[string]string) map[string]string { + tb.Helper() + out := make(map[string]string, len(responses)) + translated := make(map[string]string, len(responses)) + for key, value := range responses { + name, path, hasPath := strings.Cut(key, ":") + outKey := key + if id, ok := nameToID[name]; ok { + if hasPath { + outKey = id + ":" + path + } else { + outKey = id + } + } + if prev, collides := translated[outKey]; collides { + tb.Fatalf("response keys %q and %q both translate to %q", prev, key, outKey) + } + translated[outKey] = key + out[outKey] = value + } + return out +} diff --git a/execution/cachingtesting/cachingtesting_test.go b/execution/cachingtesting/cachingtesting_test.go new file mode 100644 index 0000000000..f6246e5100 --- /dev/null +++ b/execution/cachingtesting/cachingtesting_test.go @@ -0,0 +1,139 @@ +package cachingtesting + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" +) + +// ptr builds a pointer to a value, for the cascade's optional config fields. +func ptr[T any](value T) *T { + return &value +} + +// TestNoOpBaseline is the Phase 0 exit proof (appendix row A1 shape): with +// caching unconfigured, the response is byte-identical whether or not a runtime +// controller is set, and the only thing an attached controller hears is that +// the fetch ran outside the cache — no lookup, no merge hook, no write. +func TestNoOpBaseline(t *testing.T) { + query := `{ products(first: 2) { upc name } }` + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"},{"__typename":"Product","upc":"2","name":"Chair"}]}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"products": products}) + expected := `{"data":{"products":[{"upc":"1","name":"Table"},{"upc":"2","name":"Chair"}]}}` + + baselineBody := Execute(t, executionEngine, query, nil) + assert.Equal(t, expected, baselineBody) + + controller := cachetesting.NewRecordingController(nil) + withControllerBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, withControllerBody) + assert.Equal(t, baselineBody, withControllerBody) + assert.Equal(t, int64(1), controller.Begins()) + assert.Equal(t, []cachetesting.Call{ + {Op: "Uncached"}, // the one products fetch, which no policy covers + {Op: "End"}, + }, controller.Calls()) +} + +// TestFixtureSmoke executes one representative operation per fixture shape +// through the real engine over subgraph doubles, asserting the COMPLETE +// response body. +func TestFixtureSmoke(t *testing.T) { + t.Run("multi-key entity via second key set", func(t *testing.T) { + products := Respond(`{"data":{"productBySku":{"__typename":"Product","upc":"1","sku":"S1","name":"Table","price":100}}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"products": products}) + body := Execute(t, executionEngine, `{ productBySku(sku: "S1") { upc sku name price } }`, nil) + assert.Equal(t, `{"data":{"productBySku":{"upc":"1","sku":"S1","name":"Table","price":100}}}`, body) + }) + + t.Run("by-key root field", func(t *testing.T) { + products := Respond(`{"data":{"product":{"__typename":"Product","name":"Table"}}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"products": products}) + body := Execute(t, executionEngine, `{ product(upc: "1") { name } }`, nil) + assert.Equal(t, `{"data":{"product":{"name":"Table"}}}`, body) + }) + + t.Run("nested cross-subgraph entities", func(t *testing.T) { + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1","name":"Table"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5,"warehouse":{"location":"Berlin"}}]}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"users": users, "products": products, "inventory": inventory}) + body := Execute(t, executionEngine, `{ me { username favoriteProduct { name stock warehouse { location } } } }`, nil) + assert.Equal(t, `{"data":{"me":{"username":"jens","favoriteProduct":{"name":"Table","stock":5,"warehouse":{"location":"Berlin"}}}}}`, body) + }) + + t.Run("batch entity reviews", func(t *testing.T) { + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"products": products, "reviews": reviews}) + body := Execute(t, executionEngine, `{ products(first: 2) { upc reviews { body } } }`, nil) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"2","reviews":[{"body":"Wobbly"}]}]}}`, body) + }) + + t.Run("sibling root fields on one datasource", func(t *testing.T) { + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}],"promotions":[{"__typename":"Product","upc":"9"}]}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"products": products}) + body := Execute(t, executionEngine, `{ products(first: 1) { upc } promotions { upc } }`, nil) + assert.Equal(t, `{"data":{"products":[{"upc":"1"}],"promotions":[{"upc":"9"}]}}`, body) + }) + + t.Run("mixed ttl siblings across subgraphs", func(t *testing.T) { + products := Respond(`{"data":{"product":{"__typename":"Product","name":"Table","upc":"1"}}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"products": products, "inventory": inventory}) + body := Execute(t, executionEngine, `{ product(upc: "1") { name stock } }`, nil) + assert.Equal(t, `{"data":{"product":{"name":"Table","stock":5}}}`, body) + }) +} + +// TestDeferSupersetShape: the initial request's inventory entity fetch +// provides a STRICT SUPERSET (stock + warehouse) of the deferred inventory +// entity fetch in a later group (stock only), so cross-defer-group L1 serving +// is provable. Stays on the Plan harness: its whole point is the deferred +// group's PLANNED fetch shape, which no client-visible response can express. +func TestDeferSupersetShape(t *testing.T) { + query := ` + query { + me { favoriteProduct { upc stock warehouse { id location } } } + products(first: 1) { + upc + ... @defer { stock } + } + }` + result := Plan(t, query, nil, nil) + require.NotNil(t, result.DeferResponse, "expected a defer plan") + + groups := DeferGroups(result.DeferResponse) + require.NotEmpty(t, groups, "expected at least one defer group") + + rendered := make([]string, 0, len(groups)) + for _, group := range groups { + require.NotNil(t, group.Fetches) + rendered = append(rendered, group.Fetches.QueryPlan().PrettyPrint()) + } + // The deferred group holds ONLY the inventory (service "1") entity fetch + // selecting stock — a strict subset of the initial inventory fetch's + // {stock warehouse{id location}} for the same entity type. + assert.Equal(t, []string{`QueryPlan { + Fetch(service: "1") { + { + fragment Key on Product { + __typename + upc + } + } => + { + _entities(representations: $representations){ + ... on Product { + __typename + stock + } + } + } + } +} +`}, rendered) +} diff --git a/execution/cachingtesting/cascade_e2e_test.go b/execution/cachingtesting/cascade_e2e_test.go new file mode 100644 index 0000000000..3dfde3f265 --- /dev/null +++ b/execution/cachingtesting/cascade_e2e_test.go @@ -0,0 +1,228 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// TestCachingCascadeEndToEnd drives the configuration cascade through the REAL +// ExecutionEngine over a chain that reaches TWO subgraphs' entity fetches in a +// fixed order (users root -> products entity -> inventory entity), so the whole +// store op log pins as a literal. +func TestCachingCascadeEndToEnd(t *testing.T) { + t.Run("the global DefaultTTL alone caches every subgraph", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{DefaultTTL: time.Minute}, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + expected := `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}` + + assert.Equal(t, expected, Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller)) + + ops := store.Ops() + require.Len(t, ops, 3) + require.Len(t, ops[0].Keys, 1) + require.Len(t, ops[1].Keys, 1) + userKey, productKey := ops[0].Keys[0], ops[1].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // The products entity fetch (User) looks up first — it produces the + // representation the inventory fetch keys on. + { + Kind: "GetMany", + Keys: []string{userKey}, + Hits: []bool{false}, + }, + // The inventory entity fetch (Product) looks up second. + { + Kind: "GetMany", + Keys: []string{productKey}, + Hits: []bool{false}, + }, + // One request-end flush carrying both misses' values, each at the + // global TTL: neither subgraph has an entry in the cascade. + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: userKey, + Value: `{"data":{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:0", + "type:0:User", + "entity:0:User:19ce389448be3351", // id "u1" + }, + }, + { + Key: productKey, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + // A second request serves both entity fetches from L2: only the uncached + // users root field goes to the network again. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller)) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{userKey}, + Hits: []bool{true}, + }, + { + Kind: "GetMany", + Keys: []string{productKey}, + Hits: []bool{true}, + }, + }, store.Ops()) + assert.Equal(t, int64(2), users.Requests()) + assert.Equal(t, int64(1), products.Requests()) + assert.Equal(t, int64(1), inventory.Requests()) + }) + + t.Run("a per-subgraph TTL overrides the global one", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{DefaultTTL: time.Minute}, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(5 * time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + assert.Equal(t, + `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, + Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller)) + + ops := store.Ops() + require.Len(t, ops, 3) + require.Len(t, ops[0].Keys, 1) + require.Len(t, ops[1].Keys, 1) + userKey, productKey := ops[0].Keys[0], ops[1].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // The products entity fetch (User), inheriting the global TTL. + { + Kind: "GetMany", + Keys: []string{userKey}, + Hits: []bool{false}, + }, + // The inventory entity fetch (Product), on its own TTL. + { + Kind: "GetMany", + Keys: []string{productKey}, + Hits: []bool{false}, + }, + // The flush shows both TTLs side by side: inherited 1m for products, + // overridden 5m for inventory. + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: userKey, + Value: `{"data":{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:0", + "type:0:User", + "entity:0:User:19ce389448be3351", // id "u1" + }, + }, + { + Key: productKey, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":300,"created":-1,"scope":"public"}}`, + TTL: 5 * time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) + + t.Run("Enabled false vetoes one subgraph while the other stays cached", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{DefaultTTL: time.Minute}, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {Enabled: ptr(false)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + expected := `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}` + + assert.Equal(t, expected, Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller)) + + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + userKey := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // Only the products entity fetch reaches the store; the vetoed + // inventory fetch has no cache config at all. + { + Kind: "GetMany", + Keys: []string{userKey}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: userKey, + Value: `{"data":{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:0", + "type:0:User", + "entity:0:User:19ce389448be3351", // id "u1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + // A second request: the products fetch is served from L2, the vetoed + // inventory subgraph is fetched again. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller)) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{userKey}, + Hits: []bool{true}, + }, + }, store.Ops()) + assert.Equal(t, int64(1), products.Requests()) + assert.Equal(t, int64(2), inventory.Requests()) + }) +} diff --git a/execution/cachingtesting/client_headers_e2e_test.go b/execution/cachingtesting/client_headers_e2e_test.go new file mode 100644 index 0000000000..98ec9bca36 --- /dev/null +++ b/execution/cachingtesting/client_headers_e2e_test.go @@ -0,0 +1,424 @@ +package cachingtesting + +import ( + "net/http" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// TestClientCacheAnswerEndToEnd drives the client cache answer through the REAL +// ExecutionEngine over REAL HTTP upstreams: what the integrator reads back +// after an execution is folded from the same fetches that produced the +// response. The committed fixture names its datasources by subgraph id — "0" is +// products, "1" is inventory. +func TestClientCacheAnswerEndToEnd(t *testing.T) { + t.Run("the shortest-lived part decides the answer, and a warm request answers what is left", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(5 * time.Minute), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + query := `{ products(first: 1) { upc stock } }` + + var cold resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5}]}}`, + Execute(t, executionEngine, query, controller, engine.WithCacheResponseInfo(&cold))) + // Both parts were written in this request, so both contribute the + // lifetime they were written under: the inventory minute wins over the + // root field's five, with no clock in the arithmetic. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + }, cold) + + var warm resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5}]}}`, + Execute(t, executionEngine, query, controller, engine.WithCacheResponseInfo(&warm))) + // Neither subgraph was touched again: both parts came from their entries + // and contributed what is LEFT of them. + assert.Equal(t, int64(1), products.Requests()) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: -1, + }, NormalizeServedFreshness(warm)) + }) + + t.Run("a no-store part makes the whole response no-store", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(5 * time.Minute), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := RespondCacheControl(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`, "no-store") + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5}]}}`, + Execute(t, executionEngine, `{ products(first: 1) { upc stock } }`, controller, + engine.WithCacheResponseInfo(&info))) + // The root field's five minutes are not reported alongside the part the + // origin refused to have stored. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, info) + }) + + t.Run("a fetch of an unconfigured subgraph makes the response no-store", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + // users and products carry no policy at all: their data is as dynamic as + // this response gets, whatever the inventory entry is good for. + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, + Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller, + engine.WithCacheResponseInfo(&info))) + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, info) + + // The store side is untouched by the client answer: the inventory entry + // is written and serves the next request as usual. + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) + + t.Run("an operation with no cache-configured fetch answers nothing at all", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"}]}}`) + executionEngine := NewEngine(t, nil, Subgraphs{"products": products}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"products":[{"upc":"1","name":"Table"}]}}`, + Execute(t, executionEngine, `{ products(first: 1) { upc name } }`, controller, + engine.WithCacheResponseInfo(&info))) + // The EMPTY answer, not a no-store one: the integrator emits no cache + // header rather than forbidding a cache that was never consulted. + assert.Equal(t, resolve.CacheResponseInfo{}, info) + // Not one store round trip either: no fetch of this operation is the + // cache's business. + assert.Equal(t, []cachetesting.StoreOp(nil), store.Ops()) + }) + + t.Run("a private part marks the response private", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(5 * time.Minute), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + "inventory": { + DefaultTTL: ptr(time.Minute), + Scope: ptr(cacheconfig.CacheScopePrivate), + }, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5}]}}`, + Execute(t, executionEngine, `{ products(first: 1) { upc stock } }`, controller, + engine.WithCacheResponseInfo(&info), + engine.WithPrivatePartitionProvider(requesterIdentity("user-a")))) + // The private entry WAS written — into this requester's partition — so + // the response stays fresh for a minute, for them alone. One private + // part is enough to mark the response the public root field shares it + // with. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + Private: true, + }, info) + }) + + t.Run("a @defer operation answers nothing: its parts resolve after the headers ship", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + frames := ExecuteDefer(t, executionEngine, + `{ products(first: 1) { upc ... @defer { stock } } }`, controller, + engine.WithCacheResponseInfo(&info)) + assert.Equal(t, []string{ + `{"data":{"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"stock":5},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":false}`, + }, frames) + // The deferred inventory entry was still written — only the CLIENT + // answer is suppressed, because it would have shipped with the initial + // frame while that fetch was outstanding. + assert.Equal(t, resolve.CacheResponseInfo{}, info) + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, // the deferred group's lookup on a cold store + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) + + t.Run("CDN tags are the union of every contributing entry, sorted", func(t *testing.T) { + store := cachetesting.NewFakeStore() + caching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{EmitCdnTags: true}, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(5 * time.Minute), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + controller := cachetesting.NewRealishCache(store, nil, cache.WithGlobalConfig(caching.Global)) + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5}]}}`, + Execute(t, executionEngine, `{ products(first: 1) { upc stock } }`, controller, + engine.WithCacheResponseInfo(&info))) + // One address per contributing entry, coarse and fine: purging + // "subgraph:1" or the single product's entity tag both reach this + // response in the CDN. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + Tags: []string{ + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + "subgraph:0", + "subgraph:1", + "type:0:Query", + "type:1:Product", + }, + }, info) + }) + + t.Run("CDN tags stay unaccumulated while their emission knob is off", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(5 * time.Minute), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5}]}}`, + Execute(t, executionEngine, `{ products(first: 1) { upc stock } }`, controller, + engine.WithCacheResponseInfo(&info))) + // The entries carry their tags into the store all the same — only the + // response-side union is off. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + }, info) + ops := store.Ops() + writes := ops[len(ops)-1] + assert.Equal(t, "SetMany", writes.Kind) + assert.Equal(t, [][]string{ + { + "subgraph:0", + "type:0:Query", + }, + { + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, [][]string{writes.Items[0].Tags, writes.Items[1].Tags}) + }) + + t.Run("the client answer is off while its emission knob is off", func(t *testing.T) { + store := cachetesting.NewFakeStore() + caching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{EmitClientCacheControl: ptr(false)}, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + controller := cachetesting.NewRealishCache(store, nil, cache.WithGlobalConfig(caching.Global)) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, + Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller, + engine.WithCacheResponseInfo(&info))) + assert.Equal(t, resolve.CacheResponseInfo{}, info) + }) + + t.Run("a subgraph failure makes the response no-store", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + // Every fetch of the operation is cache-configured, so the no-store can + // come from nothing but the failed result itself. + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(5 * time.Minute), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Rules(&SubgraphRule{ + Response: `{"errors":[{"message":"inventory is down"}]}`, + Headers: http.Header{"Cache-Control": []string{"max-age=600"}}, + }) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + + var info resolve.CacheResponseInfo + assert.Equal(t, `{"errors":[{"message":"Failed to fetch from Subgraph '1' at Path 'products'."},{"message":"Cannot return null for non-nullable field 'Query.products.stock'.","path":["products",0,"stock"]}],"data":null}`, + Execute(t, executionEngine, `{ products(first: 1) { upc stock } }`, controller, + engine.WithCacheResponseInfo(&info))) + // The origin's own max-age never applies to an errored result: nothing + // was stored, so nothing may be. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, info) + // Both lookups happened; the flush carries the root field that answered + // and nothing of the subgraph that errored. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:0:013d56d080493bfa"}, // Query.products + Hits: []bool{false}, + }, + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, // the Product entity + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:0:013d56d080493bfa", + Value: `{"data":{"products":[{"__typename":"Product","upc":"1"}]},"cc":{"ttl":300,"created":-1,"scope":"public"}}`, + TTL: 5 * time.Minute, + Tags: []string{ + "subgraph:0", + "type:0:Query", + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) +} diff --git a/execution/cachingtesting/compose.sh b/execution/cachingtesting/compose.sh new file mode 100755 index 0000000000..d3bc25f778 --- /dev/null +++ b/execution/cachingtesting/compose.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash +set -euo pipefail + +echo "Composing caching test subgraphs" + +npx -y wgc@latest router compose -i graph.yaml -o config.json + +echo "Formatting config" +jq . config.json > config.json.tmp +mv config.json.tmp config.json diff --git a/execution/cachingtesting/config.json b/execution/cachingtesting/config.json new file mode 100644 index 0000000000..54968cce50 --- /dev/null +++ b/execution/cachingtesting/config.json @@ -0,0 +1,439 @@ +{ + "engineConfig": { + "defaultFlushInterval": "500", + "datasourceConfigurations": [ + { + "kind": "GRAPHQL", + "rootNodes": [ + { + "typeName": "Query", + "fieldNames": [ + "products", + "promotions", + "product", + "productBySku" + ] + }, + { + "typeName": "Product", + "fieldNames": [ + "upc", + "sku", + "name", + "price" + ] + }, + { + "typeName": "User", + "fieldNames": [ + "id", + "favoriteProduct" + ] + } + ], + "overrideFieldPathFromAlias": true, + "customGraphql": { + "fetch": { + "url": { + "staticVariableContent": "http://products.service" + }, + "method": "POST", + "body": {}, + "baseUrl": {}, + "path": {} + }, + "subscription": { + "enabled": true, + "url": { + "staticVariableContent": "http://products.service" + }, + "protocol": "GRAPHQL_SUBSCRIPTION_PROTOCOL_WS", + "websocketSubprotocol": "GRAPHQL_WEBSOCKET_SUBPROTOCOL_AUTO" + }, + "federation": { + "enabled": true, + "serviceSdl": "extend type Query {\n products(first: Int = 5): [Product!]!\n promotions: [Product!]!\n product(upc: String!): Product\n productBySku(sku: String!): Product\n}\ntype Product @key(fields: \"upc\") @key(fields: \"sku\") {\n upc: String!\n sku: String!\n name: String!\n price: Int!\n}\nextend type User @key(fields: \"id\") {\n id: ID! @external\n favoriteProduct: Product\n}\n" + }, + "upstreamSchema": { + "key": "0a7b3af7e196634fc2cabac28cac3901c52d849a" + } + }, + "requestTimeoutSeconds": "10", + "id": "0", + "keys": [ + { + "typeName": "Product", + "selectionSet": "upc" + }, + { + "typeName": "Product", + "selectionSet": "sku" + }, + { + "typeName": "User", + "selectionSet": "id" + } + ] + }, + { + "kind": "GRAPHQL", + "rootNodes": [ + { + "typeName": "Product", + "fieldNames": [ + "upc", + "stock", + "stockHistory", + "warehouse" + ] + } + ], + "childNodes": [ + { + "typeName": "Warehouse", + "fieldNames": [ + "id", + "location" + ] + } + ], + "overrideFieldPathFromAlias": true, + "customGraphql": { + "fetch": { + "url": { + "staticVariableContent": "http://inventory.service" + }, + "method": "POST", + "body": {}, + "baseUrl": {}, + "path": {} + }, + "subscription": { + "enabled": true, + "url": { + "staticVariableContent": "http://inventory.service" + }, + "protocol": "GRAPHQL_SUBSCRIPTION_PROTOCOL_WS", + "websocketSubprotocol": "GRAPHQL_WEBSOCKET_SUBPROTOCOL_AUTO" + }, + "federation": { + "enabled": true, + "serviceSdl": "extend type Product @key(fields: \"upc\") {\n upc: String! @external\n stock: Int!\n stockHistory(days: Int!): [Int!]!\n warehouse: Warehouse!\n}\ntype Warehouse {\n id: ID!\n location: String!\n}\n" + }, + "upstreamSchema": { + "key": "98e3da6ea5aef066a1f9661511e7c7e3993d4c4a" + } + }, + "requestTimeoutSeconds": "10", + "id": "1", + "keys": [ + { + "typeName": "Product", + "selectionSet": "upc" + } + ] + }, + { + "kind": "GRAPHQL", + "rootNodes": [ + { + "typeName": "Query", + "fieldNames": [ + "latestReviews", + "featuredReview" + ] + }, + { + "typeName": "User", + "fieldNames": [ + "id", + "reviews" + ] + }, + { + "typeName": "Product", + "fieldNames": [ + "upc", + "reviews" + ] + } + ], + "childNodes": [ + { + "typeName": "Review", + "fieldNames": [ + "id", + "body", + "author", + "product" + ] + } + ], + "overrideFieldPathFromAlias": true, + "customGraphql": { + "fetch": { + "url": { + "staticVariableContent": "http://reviews.service" + }, + "method": "POST", + "body": {}, + "baseUrl": {}, + "path": {} + }, + "subscription": { + "enabled": true, + "url": { + "staticVariableContent": "http://reviews.service" + }, + "protocol": "GRAPHQL_SUBSCRIPTION_PROTOCOL_WS", + "websocketSubprotocol": "GRAPHQL_WEBSOCKET_SUBPROTOCOL_AUTO" + }, + "federation": { + "enabled": true, + "serviceSdl": "extend type Query {\n latestReviews(first: Int = 5): [Review!]!\n featuredReview: Review\n}\ntype Review {\n id: ID!\n body: String!\n author: User!\n product: Product!\n}\nextend type User @key(fields: \"id\") {\n id: ID! @external\n reviews: [Review!]!\n}\nextend type Product @key(fields: \"upc\") {\n upc: String! @external\n reviews: [Review!]!\n}\n" + }, + "upstreamSchema": { + "key": "dd2fde369ba0ba0bda2edd5296fa2dc9ea3e988b" + } + }, + "requestTimeoutSeconds": "10", + "id": "2", + "keys": [ + { + "typeName": "User", + "selectionSet": "id" + }, + { + "typeName": "Product", + "selectionSet": "upc" + } + ] + }, + { + "kind": "GRAPHQL", + "rootNodes": [ + { + "typeName": "Query", + "fieldNames": [ + "me", + "user" + ] + }, + { + "typeName": "User", + "fieldNames": [ + "id", + "username" + ] + } + ], + "overrideFieldPathFromAlias": true, + "customGraphql": { + "fetch": { + "url": { + "staticVariableContent": "http://users.service" + }, + "method": "POST", + "body": {}, + "baseUrl": {}, + "path": {} + }, + "subscription": { + "enabled": true, + "url": { + "staticVariableContent": "http://users.service" + }, + "protocol": "GRAPHQL_SUBSCRIPTION_PROTOCOL_WS", + "websocketSubprotocol": "GRAPHQL_WEBSOCKET_SUBPROTOCOL_AUTO" + }, + "federation": { + "enabled": true, + "serviceSdl": "extend type Query {\n me: User\n user(id: ID!): User\n}\ntype User @key(fields: \"id\") {\n id: ID!\n username: String!\n}\n" + }, + "upstreamSchema": { + "key": "68714e916ae5c46b1ca8cbbfeabafcd03f78ff1d" + } + }, + "requestTimeoutSeconds": "10", + "id": "3", + "keys": [ + { + "typeName": "User", + "selectionSet": "id" + } + ] + }, + { + "kind": "GRAPHQL", + "rootNodes": [ + { + "typeName": "Query", + "fieldNames": [ + "deal" + ] + }, + { + "typeName": "Product", + "fieldNames": [ + "sku" + ] + } + ], + "childNodes": [ + { + "typeName": "Deal", + "fieldNames": [ + "id", + "product" + ] + } + ], + "overrideFieldPathFromAlias": true, + "customGraphql": { + "fetch": { + "url": { + "staticVariableContent": "http://deals.service" + }, + "method": "POST", + "body": {}, + "baseUrl": {}, + "path": {} + }, + "subscription": { + "enabled": true, + "url": { + "staticVariableContent": "http://deals.service" + }, + "protocol": "GRAPHQL_SUBSCRIPTION_PROTOCOL_WS", + "websocketSubprotocol": "GRAPHQL_WEBSOCKET_SUBPROTOCOL_AUTO" + }, + "federation": { + "enabled": true, + "serviceSdl": "extend type Query {\n deal(id: ID!): Deal\n}\ntype Deal {\n id: ID!\n product: Product!\n}\nextend type Product @key(fields: \"sku\") {\n sku: String! @external\n}\n" + }, + "upstreamSchema": { + "key": "7984b56f4b7be0a83fbf0fd0dd3a3416f1a3bd3d" + } + }, + "requestTimeoutSeconds": "10", + "id": "4", + "keys": [ + { + "typeName": "Product", + "selectionSet": "sku" + } + ] + } + ], + "fieldConfigurations": [ + { + "typeName": "Query", + "fieldName": "products", + "argumentsConfiguration": [ + { + "name": "first", + "sourceType": "FIELD_ARGUMENT" + } + ] + }, + { + "typeName": "Query", + "fieldName": "product", + "argumentsConfiguration": [ + { + "name": "upc", + "sourceType": "FIELD_ARGUMENT" + } + ] + }, + { + "typeName": "Query", + "fieldName": "productBySku", + "argumentsConfiguration": [ + { + "name": "sku", + "sourceType": "FIELD_ARGUMENT" + } + ] + }, + { + "typeName": "Query", + "fieldName": "latestReviews", + "argumentsConfiguration": [ + { + "name": "first", + "sourceType": "FIELD_ARGUMENT" + } + ] + }, + { + "typeName": "Query", + "fieldName": "user", + "argumentsConfiguration": [ + { + "name": "id", + "sourceType": "FIELD_ARGUMENT" + } + ] + }, + { + "typeName": "Query", + "fieldName": "deal", + "argumentsConfiguration": [ + { + "name": "id", + "sourceType": "FIELD_ARGUMENT" + } + ] + }, + { + "typeName": "Product", + "fieldName": "stockHistory", + "argumentsConfiguration": [ + { + "name": "days", + "sourceType": "FIELD_ARGUMENT" + } + ] + } + ], + "graphqlSchema": "schema {\n query: Query\n}\n\ntype Query {\n products(first: Int = 5): [Product!]!\n promotions: [Product!]!\n product(upc: String!): Product\n productBySku(sku: String!): Product\n latestReviews(first: Int = 5): [Review!]!\n featuredReview: Review\n me: User\n user(id: ID!): User\n deal(id: ID!): Deal\n}\n\ntype Product {\n upc: String!\n sku: String!\n name: String!\n price: Int!\n stock: Int!\n stockHistory(days: Int!): [Int!]!\n warehouse: Warehouse!\n reviews: [Review!]!\n}\n\ntype User {\n id: ID!\n favoriteProduct: Product\n reviews: [Review!]!\n username: String!\n}\n\ntype Warehouse {\n id: ID!\n location: String!\n}\n\ntype Review {\n id: ID!\n body: String!\n author: User!\n product: Product!\n}\n\ntype Deal {\n id: ID!\n product: Product!\n}", + "stringStorage": { + "0a7b3af7e196634fc2cabac28cac3901c52d849a": "schema {\n query: Query\n}\n\ndirective @external on FIELD_DEFINITION | OBJECT\n\ndirective @key(fields: openfed__FieldSet!, resolvable: Boolean = true) repeatable on INTERFACE | OBJECT\n\ntype Product @key(fields: \"upc\") @key(fields: \"sku\") {\n name: String!\n price: Int!\n sku: String!\n upc: String!\n}\n\ntype Query {\n product(upc: String!): Product\n productBySku(sku: String!): Product\n products(first: Int = 5): [Product!]!\n promotions: [Product!]!\n}\n\ntype User @key(fields: \"id\") {\n favoriteProduct: Product\n id: ID! @external\n}\n\nscalar openfed__FieldSet", + "98e3da6ea5aef066a1f9661511e7c7e3993d4c4a": "directive @external on FIELD_DEFINITION | OBJECT\n\ndirective @key(fields: openfed__FieldSet!, resolvable: Boolean = true) repeatable on INTERFACE | OBJECT\n\ntype Product @key(fields: \"upc\") {\n stock: Int!\n stockHistory(days: Int!): [Int!]!\n upc: String! @external\n warehouse: Warehouse!\n}\n\ntype Warehouse {\n id: ID!\n location: String!\n}\n\nscalar openfed__FieldSet", + "dd2fde369ba0ba0bda2edd5296fa2dc9ea3e988b": "schema {\n query: Query\n}\n\ndirective @external on FIELD_DEFINITION | OBJECT\n\ndirective @key(fields: openfed__FieldSet!, resolvable: Boolean = true) repeatable on INTERFACE | OBJECT\n\ntype Product @key(fields: \"upc\") {\n reviews: [Review!]!\n upc: String! @external\n}\n\ntype Query {\n featuredReview: Review\n latestReviews(first: Int = 5): [Review!]!\n}\n\ntype Review {\n author: User!\n body: String!\n id: ID!\n product: Product!\n}\n\ntype User @key(fields: \"id\") {\n id: ID! @external\n reviews: [Review!]!\n}\n\nscalar openfed__FieldSet", + "68714e916ae5c46b1ca8cbbfeabafcd03f78ff1d": "schema {\n query: Query\n}\n\ndirective @key(fields: openfed__FieldSet!, resolvable: Boolean = true) repeatable on INTERFACE | OBJECT\n\ntype Query {\n me: User\n user(id: ID!): User\n}\n\ntype User @key(fields: \"id\") {\n id: ID!\n username: String!\n}\n\nscalar openfed__FieldSet", + "7984b56f4b7be0a83fbf0fd0dd3a3416f1a3bd3d": "schema {\n query: Query\n}\n\ndirective @external on FIELD_DEFINITION | OBJECT\n\ndirective @key(fields: openfed__FieldSet!, resolvable: Boolean = true) repeatable on INTERFACE | OBJECT\n\ntype Deal {\n id: ID!\n product: Product!\n}\n\ntype Product @key(fields: \"sku\") {\n sku: String! @external\n}\n\ntype Query {\n deal(id: ID!): Deal\n}\n\nscalar openfed__FieldSet" + } + }, + "version": "00000000-0000-0000-0000-000000000000", + "subgraphs": [ + { + "id": "0", + "name": "products", + "routingUrl": "http://products.service" + }, + { + "id": "1", + "name": "inventory", + "routingUrl": "http://inventory.service" + }, + { + "id": "2", + "name": "reviews", + "routingUrl": "http://reviews.service" + }, + { + "id": "3", + "name": "users", + "routingUrl": "http://users.service" + }, + { + "id": "4", + "name": "deals", + "routingUrl": "http://deals.service" + } + ], + "featureFlagConfigs": {}, + "compatibilityVersion": "1:0.62.2" +} diff --git a/execution/cachingtesting/defer_l1_e2e_test.go b/execution/cachingtesting/defer_l1_e2e_test.go new file mode 100644 index 0000000000..b1e8a5fd46 --- /dev/null +++ b/execution/cachingtesting/defer_l1_e2e_test.go @@ -0,0 +1,381 @@ +package cachingtesting + +import ( + "context" + "errors" + "slices" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/execution/graphql" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// inventoryL1Caching enables entity caching for the inventory subgraph at the +// given TTL; L1 eligibility comes with it. +func inventoryL1Caching(ttl time.Duration) *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: &ttl}, + }, + } +} + +// executeDeferOnFlush is ExecuteDefer with a per-flushed-frame callback (called +// with all frames flushed so far), so tests can close subgraph gates off +// deterministic frame progress instead of latency. +func executeDeferOnFlush(tb testing.TB, executionEngine *engine.ExecutionEngine, query string, controller resolve.CacheController, onFlush func(frames []string)) []string { + tb.Helper() + var frames []string + writer := graphql.NewEngineResultWriter() + writer.SetFlushCallback(func(data []byte) { + frames = append(frames, string(data)) + onFlush(frames) + }) + require.NoError(tb, executionEngine.Execute(context.Background(), &graphql.Request{Query: query}, &writer, engine.WithCacheController(controller))) + if writer.Len() > 0 { + frames = append(frames, writer.String()) + } + return frames +} + +// TestDeferL1CrossGroupServing (N1 + M3): an entity cached by the INITIAL +// fetch serves a same-entity DEFERRED fetch in a later group — the deferred +// group's subgraph is never hit, both frames are complete, and the per-group +// loaders share ONE L1 through the by-reference Context (one BeginRequest). +func TestDeferL1CrossGroupServing(t *testing.T) { + query := `{ me { favoriteProduct { upc stock warehouse { id location } } } products(first: 1) { upc ... @defer { stock } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Rules( + Rule(`_entities`, `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`), + Rule(`products(first: $a)`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + ) + // TAMPERED fallback: the deferred group's stock-only request misses the + // warehouse rule, so if it ever touches the network the frame shows 999 + // and the assertion fails loudly. + tampered := Rule(``, `{"data":{"_entities":[{"__typename":"Product","stock":999}]}}`) + inventory := Rules( + Rule(`warehouse`, `{"data":{"_entities":[{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}}]}}`), + tampered, + ) + executionEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + store := cachetesting.NewFakeStore() + controller := &countingController{inner: cachetesting.NewRealishCache(store, nil)} + frames := ExecuteDefer(t, executionEngine, query, controller) + assert.Equal(t, []string{ + `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5,"warehouse":{"id":"w1","location":"Berlin"}}},"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"stock":5},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":false}`, + }, frames) + // The deferred group NEVER hit the network: inventory saw exactly the one + // initial superset fetch. + assert.Equal(t, int64(0), tampered.Count.Load()) + assert.Equal(t, int64(1), inventory.Requests()) + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // The initial fetch's lookup (miss); the deferred group rode L1 and + // never reached the store. + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + // Its request-end flush. + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + // M3: one BeginRequest — every group's loader worked on the same L1. + assert.Equal(t, int64(1), controller.begins.Load()) +} + +// TestDeferL1GroupToLaterGroup (N2): a DEFERRED fetch populates L1 that a +// LATER (nested) group is served from — ordering comes purely from the +// defer-group ancestry (no dependency edge links the two inventory fetches). +func TestDeferL1GroupToLaterGroup(t *testing.T) { + query := `{ products(first: 1) { upc ... @defer { stock warehouse { id location } ... @defer { reviews { product { stock } } } } } }` + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + // TAMPERED fallback: the nested group's stock-only inventory fetch must + // never fire. + tampered := Rule(``, `{"data":{"_entities":[{"__typename":"Product","stock":999}]}}`) + inventory := Rules( + Rule(`warehouse`, `{"data":{"_entities":[{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}}]}}`), + tampered, + ) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","product":{"__typename":"Product","upc":"1"}}]}]}}`) + executionEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"products": products, "inventory": inventory, "reviews": reviews}) + + store := cachetesting.NewFakeStore() + frames := ExecuteDefer(t, executionEngine, query, cachetesting.NewRealishCache(store, nil)) + assert.Equal(t, []string{ + `{"data":{"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"stock":5,"warehouse":{"id":"w1","location":"Berlin"}},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"pending":[{"id":"2","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"reviews":[{"product":{"stock":5}}]},"id":"2","subPath":[0]}],"completed":[{"id":"2"}],"hasNext":false}`, + }, frames) + // The nested group NEVER hit the network: inventory saw exactly the OUTER + // group's superset fetch. + assert.Equal(t, int64(0), tampered.Count.Load()) + assert.Equal(t, int64(1), inventory.Requests()) + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // The outer group's lookup (miss); the nested group rode L1 and never + // reached the store. + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + // Its request-end flush. + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) +} + +// endCountingController wraps a controller and counts EndRequest calls on the +// request caches it hands out. +type endCountingController struct { + inner resolve.CacheController + ends atomic.Int64 +} + +func (c *endCountingController) BeginRequest(ctx *resolve.Context) resolve.RequestCache { + return &endCountingCache{inner: c.inner.BeginRequest(ctx), ends: &c.ends} +} + +type endCountingCache struct { + inner resolve.RequestCache + ends *atomic.Int64 +} + +func (c *endCountingCache) PrepareFetch(in resolve.PrepareFetchInput) (resolve.Decision, *resolve.FetchCacheHandle) { + return c.inner.PrepareFetch(in) +} + +func (c *endCountingCache) OnUncachedFetch() { + c.inner.OnUncachedFetch() +} + +func (c *endCountingCache) OnFetchSkipped(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + return c.inner.OnFetchSkipped(h, in) +} + +func (c *endCountingCache) OnFetchResult(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + return c.inner.OnFetchResult(h, in) +} + +func (c *endCountingCache) EndRequest() { + c.ends.Add(1) + c.inner.EndRequest() +} + +// TestDeferSingleFlush (N3): exactly ONE EndRequest after ALL groups, and the +// L2 flush carries the deferred writes from the initial fetch AND the group — +// every Set sits AFTER every Get in the op log. +func TestDeferSingleFlush(t *testing.T) { + // The deferred selection is NOT covered by the initial fetch, so the group + // genuinely fetches and owes an L2 write. + query := `{ me { favoriteProduct { upc stock } } products(first: 1) { upc ... @defer { warehouse { id location } } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Rules( + Rule(`_entities`, `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`), + Rule(`products(first: $a)`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + ) + inventory := Rules( + Rule(`stock`, `{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`), + Rule(`warehouse`, `{"data":{"_entities":[{"__typename":"Product","warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}}]}}`), + ) + executionEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + store := cachetesting.NewFakeStore() + controller := &endCountingController{inner: cachetesting.NewRealishCache(store, nil)} + frames := ExecuteDefer(t, executionEngine, query, controller) + assert.Equal(t, []string{ + `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}},"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"warehouse":{"id":"w1","location":"Berlin"}},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":false}`, + }, frames) + assert.Equal(t, int64(1), controller.ends.Load()) + + ops := store.Ops() + require.Len(t, ops, 3) + // Both lookups (initial + deferred group) precede the SINGLE request-end + // flush, which carries the initial fetch's write and the group's. + assert.Equal(t, []string{"GetMany", "GetMany", "SetMany"}, []string{ops[0].Kind, ops[1].Kind, ops[2].Kind}) + require.Len(t, ops[2].Items, 2) + // The two flushed items are appended as their fetches complete, so their + // order is free — sort, then pin the complete value set. + values := []string{ + NormalizeEnvelopeClock(ops[2].Items[0].Value), + NormalizeEnvelopeClock(ops[2].Items[1].Value), + } + slices.Sort(values) + assert.Equal(t, []string{ + `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + `{"data":{"__typename":"Product","warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + }, values) +} + +// TestDeferSkipDoesNotReorderFrames (N4): a SkipFullHit on one sibling group +// flushes its frame while the OTHER sibling is still gated on its subgraph — +// the skip neither waits for nor reorders the fetching sibling. +func TestDeferSkipDoesNotReorderFrames(t *testing.T) { + query := `{ me { favoriteProduct { upc stock } } products(first: 1) { upc ... @defer { stock } ... @defer { warehouse { id } } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Rules( + Rule(`_entities`, `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`), + Rule(`products(first: $a)`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + ) + // Only the warehouse group LOADS (the stock group is L1-served); its HTTP + // response stays gated until `release` closes. + release := make(chan struct{}) + gated := &SubgraphRule{ + Match: `warehouse`, + Response: `{"data":{"_entities":[{"__typename":"Product","warehouse":{"__typename":"Warehouse","id":"w1"}}]}}`, + Gate: release, + } + stockRule := Rule(`stock`, `{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + inventory := Rules(gated, stockRule) + executionEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + // Pure gate ordering, no latency dependence: the gated sibling's frame can + // only flush after `release` closes, and `release` closes only once BOTH + // earlier frames (initial + the L1-served skip sibling's) have flushed — so + // the skip demonstrably did not wait for the gated fetch, and the full + // frame order is deterministic. + frames := executeDeferOnFlush(t, executionEngine, query, cachetesting.NewRealishCache(cachetesting.NewFakeStore(), nil), func(frames []string) { + if len(frames) == 2 { + close(release) + } + }) + assert.Equal(t, []string{ + `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}},"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]},{"id":"2","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"stock":5},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":true}`, + `{"incremental":[{"data":{"warehouse":{"id":"w1"}},"id":"2","subPath":[0]}],"completed":[{"id":"2"}],"hasNext":false}`, + }, frames) + // The skip group never touched the network: inventory saw exactly the + // initial stock fetch and the gated warehouse fetch. + assert.Equal(t, int64(1), stockRule.Count.Load()) + assert.Equal(t, int64(1), gated.Count.Load()) + assert.Equal(t, int64(2), inventory.Requests()) +} + +// erroringResultCache fails OnFetchResult when the fresh response contains +// the marker, leaving every other hook untouched. +type erroringResultController struct { + inner resolve.CacheController + marker string +} + +func (c *erroringResultController) BeginRequest(ctx *resolve.Context) resolve.RequestCache { + return &erroringResultCache{inner: c.inner.BeginRequest(ctx), marker: c.marker} +} + +type erroringResultCache struct { + inner resolve.RequestCache + marker string +} + +func (c *erroringResultCache) PrepareFetch(in resolve.PrepareFetchInput) (resolve.Decision, *resolve.FetchCacheHandle) { + return c.inner.PrepareFetch(in) +} + +func (c *erroringResultCache) OnUncachedFetch() { + c.inner.OnUncachedFetch() +} + +func (c *erroringResultCache) OnFetchSkipped(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + return c.inner.OnFetchSkipped(h, in) +} + +func (c *erroringResultCache) OnFetchResult(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + if in.ResponseData != nil && strings.Contains(string(in.ResponseData.MarshalTo(nil)), c.marker) { + return errFromHook + } + return c.inner.OnFetchResult(h, in) +} + +func (c *erroringResultCache) EndRequest() { + c.inner.EndRequest() +} + +var errFromHook = errors.New("cache hook failed") + +// TestDeferHookErrorIsolation (M5): one group's cache-hook error surfaces in +// THAT group's outcome; the sibling group's frame is complete and unaffected. +func TestDeferHookErrorIsolation(t *testing.T) { + query := `{ me { favoriteProduct { upc ... @defer { stock } } } products(first: 1) { upc ... @defer { warehouse { id } } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Rules( + Rule(`_entities`, `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`), + Rule(`products(first: $a)`, `{"data":{"products":[{"__typename":"Product","upc":"2"}]}}`), + ) + // Parallel sibling groups flush in either order — gate the ERRORING group's + // subgraph fetch until the healthy sibling's frame has flushed, so the frame + // order is gate-deterministic and every frame can be pinned in full. + release := make(chan struct{}) + gated := &SubgraphRule{ + Match: `warehouse`, + Response: `{"data":{"_entities":[{"__typename":"Product","warehouse":{"__typename":"Warehouse","id":"w1"}}]}}`, + Gate: release, + } + inventory := Rules( + gated, + Rule(`stock`, `{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`), + ) + executionEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + controller := &erroringResultController{ + inner: cachetesting.NewRealishCache(cachetesting.NewFakeStore(), nil), + marker: "warehouse", + } + frames := executeDeferOnFlush(t, executionEngine, query, controller, func(frames []string) { + if len(frames) == 2 { + close(release) + } + }) + // The erroring group's frame carries ONLY the hook failure (no warehouse + // data); the sibling's frame is complete and unaffected. + assert.Equal(t, []string{ + `{"data":{"me":{"favoriteProduct":{"upc":"1"}},"products":[{"upc":"2"}]},"pending":[{"id":"1","path":["me","favoriteProduct"]},{"id":"2","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"stock":5},"id":"1"}],"completed":[{"id":"1"}],"hasNext":true}`, + `{"completed":[{"id":"2","errors":[{"message":"cache hook failed"}]}],"hasNext":false}`, + }, frames) +} diff --git a/execution/cachingtesting/enginetesting.go b/execution/cachingtesting/enginetesting.go new file mode 100644 index 0000000000..5b82689522 --- /dev/null +++ b/execution/cachingtesting/enginetesting.go @@ -0,0 +1,299 @@ +package cachingtesting + +import ( + "context" + "io" + "net/http" + "net/http/httptest" + "regexp" + "strings" + "sync" + "sync/atomic" + "testing" + + "github.com/jensneuse/abstractlogger" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/execution/graphql" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// The engine-based half of the harness: real ExecutionEngine over real HTTP +// subgraph upstreams (the federation_integration_static_test.go pattern), +// with caching wired through Configuration.SetCaching and the runtime +// controller attached per request via engine.WithCacheController. Plan() +// remains for PLAN-shape assertions (pretty-printed plans, ART trace +// internals, defer frames, gated in-process ordering, benchmarks); request +// execution goes through the engine. + +// SubgraphRule routes one canned response: the first rule whose Match +// substring appears in the incoming request body wins (empty Match matches +// everything). Count records how many requests the rule served. A non-nil +// Gate blocks the RESPONSE (after the request is recorded) until the channel +// is closed — the deterministic ordering handle for defer-group tests. +type SubgraphRule struct { + Match string + Response string + Gate <-chan struct{} + // Headers are extra response headers the upstream sets before writing the + // body — the knob for runtime cache control (`Cache-Control`). It lives at + // the HTTP-handler level, so no fixture SDL or recomposition is involved. + Headers http.Header + Count atomic.Int64 +} + +// Subgraph is one httptest upstream with routing rules and a request counter. +type Subgraph struct { + Rules []*SubgraphRule + + mu sync.Mutex + requests []string + server *httptest.Server + count atomic.Int64 +} + +// Requests returns how many requests the subgraph received in total. +func (s *Subgraph) Requests() int64 { + return s.count.Load() +} + +// Bodies returns the exact request bodies received, in order. +func (s *Subgraph) Bodies() []string { + s.mu.Lock() + defer s.mu.Unlock() + return append([]string(nil), s.requests...) +} + +// Subgraphs maps subgraph NAME to its upstream double. +type Subgraphs map[string]*Subgraph + +// Rules builds a Subgraph from ordered routing rules. +func Rules(rules ...*SubgraphRule) *Subgraph { + return &Subgraph{Rules: rules} +} + +// Respond builds a single-response Subgraph (every request gets response). +func Respond(response string) *Subgraph { + return Rules(&SubgraphRule{Response: response}) +} + +// RespondCacheControl builds a single-response Subgraph whose upstream returns +// the given Cache-Control header value with every response. +func RespondCacheControl(response, cacheControl string) *Subgraph { + return Rules(&SubgraphRule{ + Response: response, + Headers: http.Header{"Cache-Control": []string{cacheControl}}, + }) +} + +// Rule builds one routing rule. +func Rule(match, response string) *SubgraphRule { + return &SubgraphRule{Match: match, Response: response} +} + +func (s *Subgraph) start(tb testing.TB, name string) { + tb.Helper() + s.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + body, err := io.ReadAll(r.Body) + if err != nil { + tb.Errorf("subgraph %q: read body: %v", name, err) + http.Error(w, err.Error(), http.StatusInternalServerError) + return + } + s.count.Add(1) + s.mu.Lock() + s.requests = append(s.requests, string(body)) + s.mu.Unlock() + for _, rule := range s.Rules { + if rule.Match == "" || strings.Contains(string(body), rule.Match) { + rule.Count.Add(1) + if rule.Gate != nil { + <-rule.Gate + } + w.Header().Set("Content-Type", "application/json") + for name, values := range rule.Headers { + for _, value := range values { + w.Header().Add(name, value) + } + } + _, _ = w.Write([]byte(rule.Response)) + return + } + } + tb.Errorf("subgraph %q: no rule matched request body: %s", name, body) + http.Error(w, "no canned response", http.StatusInternalServerError) + })) + tb.Cleanup(s.server.Close) +} + +// NewEngine builds a real ExecutionEngine over the committed caching fixture +// federation, with every datasource pointed at its subgraph double and the +// caching configuration (its subgraph overrides keyed by SUBGRAPH NAME) wired +// through SetCaching. Every configured subgraph must have a double; +// unconfigured doubles fail the test on first use via their own rule mismatch. +func NewEngine(tb testing.TB, caching *cacheconfig.CachingConfiguration, subgraphs Subgraphs) *engine.ExecutionEngine { + tb.Helper() + + rc := routerConfig(tb) + nameToID := subgraphNameToDatasourceID(rc) + idToName := make(map[string]string, len(nameToID)) + for name, id := range nameToID { + idToName[id] = name + } + + // Point each datasource at its double BEFORE the engine configuration is + // built; a subgraph without a double keeps its unreachable fixture URL, so + // touching it fails loudly. + for _, ds := range rc.EngineConfig.DatasourceConfigurations { + name := idToName[ds.Id] + subgraph, ok := subgraphs[name] + if !ok { + continue + } + subgraph.start(tb, name) + require.NotNil(tb, ds.CustomGraphql, "datasource %q has no graphql config", name) + ds.CustomGraphql.Fetch.Url.StaticVariableContent = subgraph.server.URL + } + for name := range subgraphs { + _, ok := nameToID[name] + require.True(tb, ok, "unknown subgraph name %q", name) + } + + factory := engine.NewFederationEngineConfigFactory(tb.Context()) + conf, err := factory.BuildEngineConfiguration(rc) + require.NoError(tb, err) + + if caching != nil { + conf.SetCaching(*cachingByDatasourceID(tb, caching, nameToID)) + } + + executionEngine, err := engine.NewExecutionEngine(tb.Context(), abstractlogger.Noop{}, conf, resolve.ResolverOptions{MaxConcurrency: 16}) + require.NoError(tb, err) + return executionEngine +} + +// Execute runs one operation through the engine with the given runtime cache +// controller (nil = caching runtime off) and returns the full response body. +func Execute(tb testing.TB, executionEngine *engine.ExecutionEngine, query string, controller resolve.CacheController, options ...engine.ExecutionOptions) string { + return ExecuteWithVariables(tb, executionEngine, query, "", controller, options...) +} + +// ExecuteWithVariables is Execute with request variables (JSON, "" for none). +func ExecuteWithVariables(tb testing.TB, executionEngine *engine.ExecutionEngine, query, variables string, controller resolve.CacheController, options ...engine.ExecutionOptions) string { + tb.Helper() + request := &graphql.Request{Query: query} + if variables != "" { + request.Variables = []byte(variables) + } + if controller != nil { + options = append(options, engine.WithCacheController(controller)) + } + writer := graphql.NewEngineResultWriter() + require.NoError(tb, executionEngine.Execute(context.Background(), request, &writer, options...)) + return writer.String() +} + +// TracedExecutionOptions are the deterministic ART options for pinned traces: +// predictable timings, no connection-timing noise, trace in the extensions. +func TracedExecutionOptions() engine.ExecutionOptions { + return engine.WithRequestTraceOptions(resolve.TraceOptions{ + Enable: true, + ExcludeLoadStats: true, + EnablePredictableDebugTimings: true, + Debug: true, + IncludeTraceOutputInResponseExtensions: true, + }) +} + +// ExecuteTraced runs one operation with ART enabled and returns the full body +// including extensions.trace. +func ExecuteTraced(tb testing.TB, executionEngine *engine.ExecutionEngine, query string, controller resolve.CacheController, options ...engine.ExecutionOptions) string { + tb.Helper() + return Execute(tb, executionEngine, query, controller, append(options, TracedExecutionOptions())...) +} + +// ExecutePlanned runs one operation with the QueryPlan included in the +// response extensions and returns the full body. +func ExecutePlanned(tb testing.TB, executionEngine *engine.ExecutionEngine, query string, controller resolve.CacheController, options ...engine.ExecutionOptions) string { + tb.Helper() + return Execute(tb, executionEngine, query, controller, append(options, engine.WithIncludeQueryPlanInResponse())...) +} + +// ExecuteDefer runs one @defer operation and returns every flushed frame in +// delivery order. +func ExecuteDefer(tb testing.TB, executionEngine *engine.ExecutionEngine, query string, controller resolve.CacheController, options ...engine.ExecutionOptions) []string { + tb.Helper() + if controller != nil { + options = append(options, engine.WithCacheController(controller)) + } + var frames []string + writer := graphql.NewEngineResultWriter() + writer.SetFlushCallback(func(data []byte) { + frames = append(frames, string(data)) + }) + require.NoError(tb, executionEngine.Execute(context.Background(), &graphql.Request{Query: query}, &writer, options...)) + if writer.Len() > 0 { + frames = append(frames, writer.String()) + } + return frames +} + +// NormalizeURLs rewrites every subgraph double's ephemeral httptest URL to the +// stable fixture form http://.service so response pins stay literal. +func (s Subgraphs) NormalizeURLs(body string) string { + for name, subgraph := range s { + if subgraph.server != nil { + body = strings.ReplaceAll(body, subgraph.server.URL, "http://"+name+".service") + } + } + return body +} + +var ( + remainingTTLPattern = regexp.MustCompile(`"remaining_ttl_nanoseconds":[1-9][0-9]*`) + cacheAgePattern = regexp.MustCompile(`"cache_age_nanoseconds":[1-9][0-9]*`) + envelopeCreatedRegex = regexp.MustCompile(`"created":[0-9]+`) +) + +// NormalizeEnvelopeClock rewrites a stored envelope's real-clock write moment +// to -1 so full-value store pins stay literal; the exact value is pinned by the +// synctest envelope unit rows. +func NormalizeEnvelopeClock(value string) string { + return envelopeCreatedRegex.ReplaceAllString(value, `"created":-1`) +} + +// NormalizeStoreOpsClock applies NormalizeEnvelopeClock to every value in a +// store op log, so a whole log asserts as one literal. +func NormalizeStoreOpsClock(ops []cachetesting.StoreOp) []cachetesting.StoreOp { + for opIndex := range ops { + for itemIndex := range ops[opIndex].Items { + ops[opIndex].Items[itemIndex].Value = NormalizeEnvelopeClock(ops[opIndex].Items[itemIndex].Value) + } + } + return ops +} + +// NormalizeServedFreshness rewrites a positive client-answer freshness to -1 so +// a full-value answer pin stays literal. A SERVED entry's freshness is a +// real-clock countdown from the moment it was written, which no wall-clock +// assertion can pin; its exact arithmetic is pinned by the synctest unit rows. +// A freshly written part contributes its resolved lifetime instead, which is +// clock-free and asserted verbatim. +func NormalizeServedFreshness(info resolve.CacheResponseInfo) resolve.CacheResponseInfo { + if info.MaxAge > 0 { + info.MaxAge = -1 + } + return info +} + +// NormalizeCacheTraceClock rewrites the real-clock cache-trace fields (positive +// remaining-TTL and cache-age nanos) to -1 so full-body pins stay literal; +// their exact values are pinned by the synctest observer unit rows. +func NormalizeCacheTraceClock(body string) string { + body = remainingTTLPattern.ReplaceAllString(body, `"remaining_ttl_nanoseconds":-1`) + body = cacheAgePattern.ReplaceAllString(body, `"cache_age_nanoseconds":-1`) + return body +} diff --git a/execution/cachingtesting/entity_config_test.go b/execution/cachingtesting/entity_config_test.go new file mode 100644 index 0000000000..e16378df41 --- /dev/null +++ b/execution/cachingtesting/entity_config_test.go @@ -0,0 +1,240 @@ +package cachingtesting + +import ( + "bytes" + "encoding/json" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +func entityCachingFor(subgraphs ...string) *cacheconfig.CachingConfiguration { + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: make(map[string]cacheconfig.SubgraphCacheConfig, len(subgraphs)), + } + for _, name := range subgraphs { + caching.Subgraphs[name] = cacheconfig.SubgraphCacheConfig{DefaultTTL: ptr(time.Minute)} + } + return caching +} + +// TestEntityCacheConfigSyncPlan pins the full per-fetch cache config over a +// REAL sync execution: the reviews batch entity fetch is configured, the +// products root fetch stays uncached. The lone entity fetch has no L1 +// provider/consumer pair, so optimizeL1Cache narrows L1 off. Runs through the +// REAL ExecutionEngine with the QueryPlan in the response extensions; the +// ENTIRE body (data + fetch tree with cache configs) is pinned. +func TestEntityCacheConfigSyncPlan(t *testing.T) { + controller := cachetesting.NewRealishCache(cachetesting.NewFakeStore(), nil) + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + subgraphs := Subgraphs{"products": products, "reviews": reviews} + executionEngine := NewEngine(t, entityCachingFor("reviews"), subgraphs) + body := ExecutePlanned(t, executionEngine, `{ products(first: 2) { upc reviews { body } } }`, controller) + var buf bytes.Buffer + require.NoError(t, json.Indent(&buf, []byte(subgraphs.NormalizeURLs(body)), "", " ")) + assert.Equal(t, `{ + "data": { + "products": [ + { + "upc": "1", + "reviews": [ + { + "body": "Solid" + } + ] + }, + { + "upc": "2", + "reviews": [ + { + "body": "Wobbly" + } + ] + } + ] + }, + "extensions": { + "queryPlan": { + "version": "1", + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "subgraphName": "0", + "subgraphId": "0", + "fetchId": 0 + } + }, + { + "kind": "Single", + "fetch": { + "kind": "BatchEntity", + "path": "products", + "subgraphName": "2", + "subgraphId": "2", + "fetchId": 1, + "dependsOnFetchIds": [ + 0 + ], + "dependencies": [ + { + "coordinate": { + "typeName": "Product", + "fieldName": "reviews" + }, + "isUserRequested": true, + "dependsOn": [ + { + "fetchId": 0, + "subgraph": "0", + "coordinate": { + "typeName": "Product", + "fieldName": "upc" + }, + "isKey": true, + "isRequires": false + } + ] + } + ], + "cache": "{l1:false l2:true subgraph:2 ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:Entity type:Product field: representation:true providesData:true populateL2OnMutation:false mutationTTL:0s}" + } + } + ] + } + } +}`, buf.String()) +} + +// TestEntityCacheConfigDeferPlan pins that DEFER-GROUP entity fetches carry +// config too: the initial inventory fetch and the deferred inventory fetch are +// both configured from the same policy. This is a planner-level test that pins +// plan-internal state not visible in a client response: the queryPlan response +// extension only covers the synchronous fetch tree, so the deferred group's +// fetch (and its cache config) can only be asserted on the Plan() result. +func TestEntityCacheConfigDeferPlan(t *testing.T) { + query := ` + query { + me { favoriteProduct { upc stock warehouse { id location } } } + products(first: 1) { + upc + ... @defer { stock } + } + }` + result := Plan(t, query, entityCachingFor("inventory"), nil) + require.NotNil(t, result.DeferResponse) + + assert.Equal(t, `QueryPlan { + Sequence { + Parallel { + Fetch(service: "3") { + { + me { + __typename + id + } + } + } + Fetch(service: "0") { + { + products(first: $a){ + upc + __typename + } + } + } + } + Fetch(service: "0") { + { + fragment Key on User { + __typename + id + } + } => + { + _entities(representations: $representations){ + ... on User { + __typename + favoriteProduct { + upc + __typename + } + } + } + } + } + Flatten(path: "me.favoriteProduct") { + Fetch(service: "1") { + { + fragment Key on Product { + __typename + upc + } + } => + Cache: {l1:true l2:true subgraph:1 ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:Entity type:Product field: representation:true providesData:true populateL2OnMutation:false mutationTTL:0s} + { + _entities(representations: $representations){ + ... on Product { + __typename + stock + warehouse { + id + location + } + } + } + } + } + } + } +} +Deferred (id: 1) QueryPlan { + Fetch(service: "1") { + { + fragment Key on Product { + __typename + upc + } + } => + Cache: {l1:true l2:true subgraph:1 ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:Entity type:Product field: representation:true providesData:true populateL2OnMutation:false mutationTTL:0s} + { + _entities(representations: $representations){ + ... on Product { + __typename + stock + } + } + } + } +} +`, PrettyPlan(result)) +} + +// TestEntityCacheConfigDeterminism executes the same operation through TWO +// independent engines (one engine would serve the repeat from its execution +// plan cache) and asserts the two full response bodies — data plus the +// queryPlan extension with its rendered cache configs — are byte-identical. +func TestEntityCacheConfigDeterminism(t *testing.T) { + query := `{ products(first: 2) { upc reviews { body } } }` + + run := func(t *testing.T) string { + controller := cachetesting.NewRealishCache(cachetesting.NewFakeStore(), nil) + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + subgraphs := Subgraphs{"products": products, "reviews": reviews} + executionEngine := NewEngine(t, entityCachingFor("reviews", "inventory"), subgraphs) + return subgraphs.NormalizeURLs(ExecutePlanned(t, executionEngine, query, controller)) + } + + first := run(t) + second := run(t) + assert.Equal(t, first, second) +} diff --git a/execution/cachingtesting/entity_l2_test.go b/execution/cachingtesting/entity_l2_test.go new file mode 100644 index 0000000000..22bec75b57 --- /dev/null +++ b/execution/cachingtesting/entity_l2_test.go @@ -0,0 +1,248 @@ +package cachingtesting + +import ( + "context" + "errors" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/execution/graphql" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// inventoryCaching enables entity caching for the inventory subgraph. +func inventoryCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } +} + +// countingController wraps a controller to count BeginRequest calls (B rows). +type countingController struct { + inner resolve.CacheController + begins atomic.Int64 +} + +func (c *countingController) BeginRequest(ctx *resolve.Context) resolve.RequestCache { + c.begins.Add(1) + return c.inner.BeginRequest(ctx) +} + +// TestEntityL2EndToEnd is the end-to-end L2 entity hit: request 1 misses and +// writes at request end; request 2 serves from L2 with the subgraph double +// proving ZERO network for the cached fetch; complete responses asserted; the +// lifecycle counts (lazy single BeginRequest, single EndRequest) ride along. +// Runs through the REAL ExecutionEngine; the engine exposes no execution +// option for loader hooks, so the C7 LoaderHooks contract (no hooks for the +// skipped fetch) stays pinned by the resolve-level suites. +func TestEntityL2EndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + query := `{ me { username favoriteProduct { upc stock } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + expected := `{"data":{"me":{"username":"jens","favoriteProduct":{"upc":"1","stock":5}}}}` + + // Request 1: miss + write-through. + firstObserver := &cachetesting.RecordingObserver{} + firstController := &countingController{inner: cachetesting.NewRealishCache(store, firstObserver)} + firstBody := Execute(t, executionEngine, query, firstController) + assert.Equal(t, expected, firstBody) + assert.Equal(t, int64(1), users.Requests()) + assert.Equal(t, int64(1), products.Requests()) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, int64(1), firstController.begins.Load()) + firstBegins, firstEnds := firstObserver.Counts() + assert.Equal(t, 1, firstBegins) + assert.Equal(t, 1, firstEnds) + + firstOps := store.Ops() + require.Len(t, firstOps, 2) + require.Len(t, firstOps[0].Keys, 1) + key := firstOps[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(firstOps)) + + // Request 2: L2 hit; the inventory subgraph is never hit again. The op log + // resets so request 2's ops assert in isolation; a fresh controller keeps + // the BeginRequest count per-request. + store.ResetOps() + secondController := &countingController{inner: cachetesting.NewRealishCache(store, nil)} + secondBody := Execute(t, executionEngine, query, secondController) + + assert.Equal(t, expected, secondBody) + // The uncached subgraphs fetched again (counts accumulate across the two + // requests through the one engine); inventory stayed at ONE. + assert.Equal(t, int64(2), users.Requests()) + assert.Equal(t, int64(2), products.Requests()) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, int64(1), secondController.begins.Load()) + // Read key == write key (key fidelity): request 2's ONLY op is a read + // under the SAME key request 1 wrote, and it hits. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{true}, + }, + }, store.Ops()) +} + +// TestEntityL2DispatchRows covers the C dispatch/lifecycle rows through the +// REAL ExecutionEngine: decisions route to the right merge hook, the handle +// keeps pointer identity from prepare to merge (C8), and hook errors +// propagate (O). +func TestEntityL2DispatchRows(t *testing.T) { + t.Run("[C] DecisionFetch dispatches to OnFetchResult with handle identity", func(t *testing.T) { + handle := &resolve.FetchCacheHandle{Decision: resolve.DecisionFetch} + controller := cachetesting.NewRecordingController(map[string]cachetesting.ScriptedDecision{ + "me.favoriteProduct": {Decision: resolve.DecisionFetch, Handle: handle}, + }) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + subgraphs := Subgraphs{"users": users, "products": products, "inventory": inventory} + executionEngine := NewEngine(t, inventoryCaching(), subgraphs) + + body := Execute(t, executionEngine, `{ me { username favoriteProduct { upc stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"username":"jens","favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + // Only the cached inventory fetch hits the lookup and merge hooks: + // Prepare + Result + End. The two fetches ahead of it carry no policy and + // only announce themselves, which is what keeps the response from being + // advertised as keepable. + // InputBytes carries the double's ephemeral URL; normalize it so the pin + // stays literal. EmptyEntity is the loader's RAW signal (entity fetch + // whose data._entities is a non-null array); the controller only treats + // it as a negative result when ResponseData is also null. + calls := controller.Calls() + for i := range calls { + calls[i].InputBytes = subgraphs.NormalizeURLs(calls[i].InputBytes) + } + assert.Equal(t, []cachetesting.Call{ + {Op: "Uncached"}, // the users root fetch + {Op: "Uncached"}, // the products entity fetch for favoriteProduct + { + Op: "Prepare", + FetchPath: "me.favoriteProduct", + Items: 1, + InputBytes: `{"method":"POST","url":"http://inventory.service","header":{},"body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename stock}}}","variables":{"representations":[{"__typename":"Product","upc":"1"}]}}}`, + Decision: resolve.DecisionFetch, + }, + { + Op: "Result", + FetchPath: "me.favoriteProduct", + Items: 1, + ResponseData: `{"__typename":"Product","stock":5}`, + EmptyEntity: true, + StatusCode: 200, + }, + {Op: "End"}, + }, calls) + assert.Equal(t, []*resolve.FetchCacheHandle{handle}, controller.ResultHandles()) + assert.Equal(t, int64(1), controller.Begins()) + }) + + t.Run("[C3/C6] SkipFullHit skips the network with NO spurious error", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + query := `{ me { username favoriteProduct { upc stock } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + expected := `{"data":{"me":{"username":"jens","favoriteProduct":{"upc":"1","stock":5}}}}` + + // A real full hit: seed the store through a first request, then replay. + warmupBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, warmupBody) + warmupOps := store.Ops() + require.Len(t, warmupOps, 2) + require.Len(t, warmupOps[0].Keys, 1) + key := warmupOps[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(warmupOps)) + + // The replay resolves cleanly (Execute fails the test on any resolver + // error) with ZERO further network to inventory: a single read, no writes. + store.ResetOps() + body := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, body) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{true}, + }, + }, store.Ops()) + }) + + t.Run("[O] merge-hook errors propagate to the caller", func(t *testing.T) { + fake := cachetesting.NewFakeRequestCache(map[string]cachetesting.ScriptedDecision{ + "me.favoriteProduct": {Decision: resolve.DecisionFetch, Handle: &resolve.FetchCacheHandle{Decision: resolve.DecisionFetch}}, + }) + fake.SetError("me.favoriteProduct", "Result", errors.New("cache write exploded")) + controller := cachetesting.NewFakeCacheController(fake) + + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + // Execute requires success, so drive the engine directly for the error. + writer := graphql.NewEngineResultWriter() + err := executionEngine.Execute(context.Background(), &graphql.Request{Query: `{ me { username favoriteProduct { upc stock } } }`}, &writer, engine.WithCacheController(controller)) + require.EqualError(t, err, "cache write exploded") + }) +} diff --git a/execution/cachingtesting/envelope_e2e_test.go b/execution/cachingtesting/envelope_e2e_test.go new file mode 100644 index 0000000000..926f36ec4f --- /dev/null +++ b/execution/cachingtesting/envelope_e2e_test.go @@ -0,0 +1,160 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// TestEnvelopeEndToEnd drives the stored value's envelope through the REAL +// ExecutionEngine: what lands in the store and how the key's subgraph segment +// keeps two subgraphs' entries for one entity apart. +func TestEnvelopeEndToEnd(t *testing.T) { + t.Run("the stored value carries data and cache control", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock warehouse { id location } } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5,"warehouse":{"id":"w1","location":"Berlin"}}}}}`, body) + + // The write moment is real-clock; everything else is pinned literally. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + // Tags live on the store Item; the envelope above carries + // none of them. + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) + + t.Run("one entity cached by two subgraphs produces two keyspace-separated entries", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{DefaultTTL: time.Minute}, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory, "reviews": reviews}) + + body := Execute(t, executionEngine, `{ products(first: 1) { upc stock reviews { body } } }`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5,"reviews":[{"body":"Solid"}]}]}}`, body) + + // The SAME representation {"__typename":"Product","upc":"1"} is cached + // once per subgraph: the subgraph segment leads both the visible key and + // the hashed preimage, so the entries can never collide or be reused + // across subgraphs (datasource 1 is inventory, 2 is reviews). The two + // entity fetches are siblings and run in parallel, so the entries are + // read back by key instead of from the order-dependent op log. + inventoryValue, ok := store.Value("v1:1:4f796e3bbd360fce") + require.True(t, ok) + assert.Equal(t, + `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + NormalizeEnvelopeClock(string(inventoryValue))) + reviewsValue, ok := store.Value("v1:2:48d227258abb2a74") + require.True(t, ok) + assert.Equal(t, + `{"data":{"__typename":"Product","reviews":[{"body":"Solid"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + NormalizeEnvelopeClock(string(reviewsValue))) + + // Request 2 serves both entity fetches from their own subgraph's entry; + // the uncached products root field goes to the network again. + assert.Equal(t, `{"data":{"products":[{"upc":"1","stock":5,"reviews":[{"body":"Solid"}]}]}}`, + Execute(t, executionEngine, `{ products(first: 1) { upc stock reviews { body } } }`, controller)) + assert.Equal(t, int64(2), products.Requests()) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, int64(1), reviews.Requests()) + }) +} + +// TestEnvelopeLegacyBytesEndToEnd: an entry that is not a decodable envelope +// (a pre-envelope value, corruption) is a plain miss — never an error — and the +// fetch's own write replaces it. +func TestEnvelopeLegacyBytesEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + // A bare, unenveloped entity value under an otherwise valid key. + store.Seed("v1:1:4f796e3bbd360fce", []byte(`{"__typename":"Product","stock":9}`), time.Minute) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller) + // The undecodable entry never reaches the response. + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{true}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + + // The replacement entry is a normal envelope and serves the next request. + store.ResetOps() + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, + Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller)) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{true}, + }, + }, store.Ops()) +} diff --git a/execution/cachingtesting/graph.yaml b/execution/cachingtesting/graph.yaml new file mode 100644 index 0000000000..4fbe56d582 --- /dev/null +++ b/execution/cachingtesting/graph.yaml @@ -0,0 +1,22 @@ +version: 1 +subgraphs: + - name: products + routing_url: http://products.service + schema: + file: subgraphs/products.graphql + - name: inventory + routing_url: http://inventory.service + schema: + file: subgraphs/inventory.graphql + - name: reviews + routing_url: http://reviews.service + schema: + file: subgraphs/reviews.graphql + - name: users + routing_url: http://users.service + schema: + file: subgraphs/users.graphql + - name: deals + routing_url: http://deals.service + schema: + file: subgraphs/deals.graphql diff --git a/execution/cachingtesting/isolation_e2e_test.go b/execution/cachingtesting/isolation_e2e_test.go new file mode 100644 index 0000000000..fd2e8bd82c --- /dev/null +++ b/execution/cachingtesting/isolation_e2e_test.go @@ -0,0 +1,371 @@ +package cachingtesting + +import ( + "bytes" + "encoding/json" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// isolationCaching configures two sibling root fields on the products +// subgraph with DIFFERENT settings. +func isolationCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", TTL: time.Minute}, + {TypeName: "Query", FieldName: "promotions", TTL: 5 * time.Minute}, + }, + }, + }, + } +} + +// TestRootFieldIsolationPlans covers the isolation rows through the REAL +// ExecutionEngine: each scenario executes like a client with the QueryPlan in +// the response extensions, pinning the ENTIRE body — data plus the sync fetch +// tree with its per-fetch cache configs. +func TestRootFieldIsolationPlans(t *testing.T) { + t.Run("two cached siblings with different policies become two parallel fetches", func(t *testing.T) { + controller := cachetesting.NewRealishCache(cachetesting.NewFakeStore(), nil) + products := Rules( + Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + Rule(`promotions`, `{"data":{"promotions":[{"__typename":"Product","upc":"9"}]}}`), + ) + subgraphs := Subgraphs{"products": products} + executionEngine := NewEngine(t, isolationCaching(), subgraphs) + body := ExecutePlanned(t, executionEngine, `{ products(first: 1) { upc } promotions { upc } }`, controller) + var buf bytes.Buffer + require.NoError(t, json.Indent(&buf, []byte(subgraphs.NormalizeURLs(body)), "", " ")) + assert.Equal(t, `{ + "data": { + "products": [ + { + "upc": "1" + } + ], + "promotions": [ + { + "upc": "9" + } + ] + }, + "extensions": { + "queryPlan": { + "version": "1", + "kind": "Sequence", + "children": [ + { + "kind": "Parallel", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "subgraphName": "0", + "subgraphId": "0", + "fetchId": 0, + "cache": "{l1:false l2:true subgraph:0 ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:RootField type:Query field:products representation:false providesData:true populateL2OnMutation:false mutationTTL:0s}" + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Single", + "subgraphName": "0", + "subgraphId": "0", + "fetchId": 1, + "cache": "{l1:false l2:true subgraph:0 ttl:5m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:RootField type:Query field:promotions representation:false providesData:true populateL2OnMutation:false mutationTTL:0s}" + } + } + ] + } + ] + } + } +}`, buf.String()) + }) + + t.Run("cached + uncached sibling: cached isolated, uncached separate without config", func(t *testing.T) { + controller := cachetesting.NewRealishCache(cachetesting.NewFakeStore(), nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", TTL: time.Minute}, + }, + }, + }, + } + products := Rules( + Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + Rule(`promotions`, `{"data":{"promotions":[{"__typename":"Product","upc":"9"}]}}`), + ) + subgraphs := Subgraphs{"products": products} + executionEngine := NewEngine(t, caching, subgraphs) + body := ExecutePlanned(t, executionEngine, `{ products(first: 1) { upc } promotions { upc } }`, controller) + var buf bytes.Buffer + require.NoError(t, json.Indent(&buf, []byte(subgraphs.NormalizeURLs(body)), "", " ")) + assert.Equal(t, `{ + "data": { + "products": [ + { + "upc": "1" + } + ], + "promotions": [ + { + "upc": "9" + } + ] + }, + "extensions": { + "queryPlan": { + "version": "1", + "kind": "Sequence", + "children": [ + { + "kind": "Parallel", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "subgraphName": "0", + "subgraphId": "0", + "fetchId": 0, + "cache": "{l1:false l2:true subgraph:0 ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:RootField type:Query field:products representation:false providesData:true populateL2OnMutation:false mutationTTL:0s}" + } + }, + { + "kind": "Single", + "fetch": { + "kind": "Single", + "subgraphName": "0", + "subgraphId": "0", + "fetchId": 1 + } + } + ] + } + ] + } + } +}`, buf.String()) + }) + + t.Run("caching off: one merged fetch, no cache config on it", func(t *testing.T) { + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}],"promotions":[{"__typename":"Product","upc":"9"}]}}`) + subgraphs := Subgraphs{"products": products} + executionEngine := NewEngine(t, nil, subgraphs) + body := ExecutePlanned(t, executionEngine, `{ products(first: 1) { upc } promotions { upc } }`, nil) + var buf bytes.Buffer + require.NoError(t, json.Indent(&buf, []byte(subgraphs.NormalizeURLs(body)), "", " ")) + assert.Equal(t, `{ + "data": { + "products": [ + { + "upc": "1" + } + ], + "promotions": [ + { + "upc": "9" + } + ] + }, + "extensions": { + "queryPlan": { + "version": "1", + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "subgraphName": "0", + "subgraphId": "0", + "fetchId": 0 + } + } + ] + } + } +}`, buf.String()) + }) + + t.Run("entity-root-node trap: a nested entity under an isolated root still merges into its subtree", func(t *testing.T) { + // TWO fetches only: the isolated products root (its own subtree intact) + // and the inventory entity fetch sequenced after it — the products + // subtree was NOT torn apart into more fetches. + controller := cachetesting.NewRealishCache(cachetesting.NewFakeStore(), nil) + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + subgraphs := Subgraphs{"products": products, "inventory": inventory} + executionEngine := NewEngine(t, isolationCaching(), subgraphs) + body := ExecutePlanned(t, executionEngine, `{ products(first: 1) { upc stock } }`, controller) + var buf bytes.Buffer + require.NoError(t, json.Indent(&buf, []byte(subgraphs.NormalizeURLs(body)), "", " ")) + assert.Equal(t, `{ + "data": { + "products": [ + { + "upc": "1", + "stock": 5 + } + ] + }, + "extensions": { + "queryPlan": { + "version": "1", + "kind": "Sequence", + "children": [ + { + "kind": "Single", + "fetch": { + "kind": "Single", + "subgraphName": "0", + "subgraphId": "0", + "fetchId": 0, + "cache": "{l1:false l2:true subgraph:0 ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:RootField type:Query field:products representation:false providesData:true populateL2OnMutation:false mutationTTL:0s}" + } + }, + { + "kind": "Single", + "fetch": { + "kind": "BatchEntity", + "path": "products", + "subgraphName": "1", + "subgraphId": "1", + "fetchId": 1, + "dependsOnFetchIds": [ + 0 + ], + "dependencies": [ + { + "coordinate": { + "typeName": "Product", + "fieldName": "stock" + }, + "isUserRequested": true, + "dependsOn": [ + { + "fetchId": 0, + "subgraph": "0", + "coordinate": { + "typeName": "Product", + "fieldName": "upc" + }, + "isKey": true, + "isRequires": false + } + ] + } + ] + } + } + ] + } + } +}`, buf.String()) + }) + + // This subtest is a planner-level test that pins plan-internal state not + // visible in a client response: the queryPlan response extension only + // covers the synchronous fetch tree, so the deferred group's plan (and its + // fetch placement) can only be asserted on the Plan() result itself. + t.Run("defer composition: an isolated root's deferred sub-fetch lands in its defer group", func(t *testing.T) { + result := Plan(t, `{ products(first: 1) { upc ... @defer { stock } } }`, isolationCaching(), nil) + require.NotNil(t, result.DeferResponse) + assert.Equal(t, `QueryPlan { + Fetch(service: "0") { + Cache: {l1:false l2:true subgraph:0 ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:RootField type:Query field:products representation:false providesData:true populateL2OnMutation:false mutationTTL:0s} + { + products(first: $a){ + upc + __typename + } + } + } +} +Deferred (id: 1) QueryPlan { + Fetch(service: "1") { + { + fragment Key on Product { + __typename + upc + } + } => + { + _entities(representations: $representations){ + ... on Product { + __typename + stock + } + } + } + } +} +`, PrettyPlan(result)) + }) +} + +// TestRootFieldIsolationIndependentServing: the two isolated siblings cache +// and expire INDEPENDENTLY — one entry expires (forced), the other still hits. +// Runs through the REAL ExecutionEngine: the products double routes each +// isolated fetch by its request body, one rule per root field. +func TestRootFieldIsolationIndependentServing(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + query := `{ products(first: 1) { upc } promotions { upc } }` + productsRule := Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + promotionsRule := Rule(`promotions`, `{"data":{"promotions":[{"__typename":"Product","upc":"9"}]}}`) + products := Rules(productsRule, promotionsRule) + executionEngine := NewEngine(t, isolationCaching(), Subgraphs{"products": products}) + expected := `{"data":{"products":[{"upc":"1"}],"promotions":[{"upc":"9"}]}}` + + firstBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, firstBody) + // TWO isolated fetches, one per root field, both to the products double. + assert.Equal(t, int64(1), productsRule.Count.Load()) + assert.Equal(t, int64(1), promotionsRule.Count.Load()) + + // One read per isolated fetch, then the shared request-end write of both. + ops := store.Ops() + require.Len(t, ops, 3) + // The two fetches run in parallel: identify the products entry by its + // EXACT stored value instead of relying on written-item order. + var productsKey, promotionsKey string + for _, item := range ops[2].Items { + switch NormalizeEnvelopeClock(item.Value) { + case `{"data":{"products":[{"__typename":"Product","upc":"1"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`: + productsKey = item.Key + case `{"data":{"promotions":[{"__typename":"Product","upc":"9"}]},"cc":{"ttl":300,"created":-1,"scope":"public"}}`: + promotionsKey = item.Key + } + } + require.NotEmpty(t, productsKey) + require.NotEmpty(t, promotionsKey) + assert.NotEqual(t, productsKey, promotionsKey) + + // Force-expire ONLY the products entry (the store double lets tests age an + // entry without real sleeping; TTL expiry semantics are pinned by the + // synctest unit rows). + value, ok := store.Value(productsKey) + require.True(t, ok) + store.Seed(productsKey, value, -time.Second) + + secondBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, secondBody) + // The products fetch expired and refetched; promotions still hit: exactly + // ONE of the two isolated fetches touched the network again. + assert.Equal(t, int64(2), productsRule.Count.Load()) + assert.Equal(t, int64(1), promotionsRule.Count.Load()) +} diff --git a/execution/cachingtesting/l1_e2e_test.go b/execution/cachingtesting/l1_e2e_test.go new file mode 100644 index 0000000000..98b867d7af --- /dev/null +++ b/execution/cachingtesting/l1_e2e_test.go @@ -0,0 +1,191 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// l1ChainQuery is the same-representation inventory chain: the INITIAL tree +// resolves product(upc:"1") through inventory selecting {stock, warehouse}, and +// the DEFERRED group resolves products(first:1)[0] — the very same product — +// through inventory selecting {stock} alone. Both fetches send the identical +// representation {__typename:"Product", upc:"1"}, so single-key L1 shares one +// entry between them, the deferred selection is covered by the initial value, +// and the defer-group ancestry orders provider before consumer. +const l1ChainQuery = `{ product(upc: "1") { stock warehouse { id location } } products(first: 1) { upc ... @defer { stock } } }` + +// l1ChainDoubles builds the doubles for l1ChainQuery. deferredStock +// parameterizes the DEFERRED fetch's canned stock so tests can TAMPER it +// (accidental network use then fails loudly). +func l1ChainDoubles(deferredStock string) (products *Subgraph, initialFetch, deferredFetch *SubgraphRule, inventory *Subgraph) { + products = Rules( + Rule(`product(upc: $a)`, `{"data":{"product":{"__typename":"Product","upc":"1"},"products":[{"__typename":"Product","upc":"1"}]}}`), + ) + // The initial fetch is the only one selecting warehouse; the deferred fetch + // selects stock alone and falls through to the second rule. + initialFetch = Rule(`warehouse`, `{"data":{"_entities":[{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}}]}}`) + deferredFetch = Rule(``, `{"data":{"_entities":[{"__typename":"Product","stock":`+deferredStock+`}]}}`) + return products, initialFetch, deferredFetch, Rules(initialFetch, deferredFetch) +} + +// TestL1InRequestReuseEndToEnd: the initial inventory fetch populates L1 under +// the representation both fetches send; the DEFERRED fetch of the same product +// is served from L1 with ZERO network and without a second store lookup. Runs +// through the REAL ExecutionEngine. +func TestL1InRequestReuseEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + products, initialFetch, deferredFetch, inventory := l1ChainDoubles("999") + executionEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"products": products, "inventory": inventory}) + + frames := ExecuteDefer(t, executionEngine, l1ChainQuery, cachetesting.NewRealishCache(store, nil)) + assert.Equal(t, []string{ + `{"data":{"product":{"stock":5,"warehouse":{"id":"w1","location":"Berlin"}},"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + // stock 5, not the tampered 999: the deferred group read L1. + `{"incremental":[{"data":{"stock":5},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":false}`, + }, frames) + assert.Equal(t, int64(1), initialFetch.Count.Load()) + assert.Equal(t, int64(0), deferredFetch.Count.Load()) + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // The initial fetch's lookup (miss); the deferred fetch rode L1 and + // never reached the store. + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + // Its request-end flush. + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) +} + +// TestL1ModeMatrixEndToEnd (J rows): the same operation under NO-OP and under +// caching produces byte-identical frames; the modes differ ONLY in network and +// store traffic. The deferred fetch's canned response matches the cached value +// here (the tampered variant is TestL1InRequestReuseEndToEnd's job), so byte +// equality across modes is meaningful. Two caching configurations → two +// engines, each over its own doubles. +func TestL1ModeMatrixEndToEnd(t *testing.T) { + // NO-OP: no caching config, no controller — the baseline frames. + noopProducts, _, noopDeferred, noopInventory := l1ChainDoubles("5") + noopEngine := NewEngine(t, nil, Subgraphs{"products": noopProducts, "inventory": noopInventory}) + noopFrames := ExecuteDefer(t, noopEngine, l1ChainQuery, nil) + assert.Equal(t, []string{ + `{"data":{"product":{"stock":5,"warehouse":{"id":"w1","location":"Berlin"}},"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + `{"incremental":[{"data":{"stock":5},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":false}`, + }, noopFrames) + assert.Equal(t, int64(1), noopDeferred.Count.Load()) // the baseline really fetches it + + // L1+L2: identical frames; the initial fetch misses L2 once and flushes its + // single write, and the deferred fetch rides L1 — neither network nor store. + bothStore := cachetesting.NewFakeStore() + bothProducts, bothInitial, bothDeferred, bothInventory := l1ChainDoubles("5") + bothEngine := NewEngine(t, inventoryL1Caching(time.Minute), Subgraphs{"products": bothProducts, "inventory": bothInventory}) + controller := cachetesting.NewRealishCache(bothStore, nil) + bothFrames := ExecuteDefer(t, bothEngine, l1ChainQuery, controller) + assert.Equal(t, noopFrames, bothFrames) + assert.Equal(t, int64(0), bothDeferred.Count.Load()) + ops := bothStore.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + // The initial fetch's lookup (miss). + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + // Its request-end flush; ONE key per item, so one written item. + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + // A SECOND request through the same engine hits L2 on the initial fetch and + // L1 on the deferred one; its ops assert in isolation. + bothStore.ResetOps() + secondFrames := ExecuteDefer(t, bothEngine, l1ChainQuery, controller) + assert.Equal(t, noopFrames, secondFrames) + assert.Equal(t, int64(1), bothInitial.Count.Load()) // no NEW network fetch + assert.Equal(t, int64(0), bothDeferred.Count.Load()) + // Exactly one op: the initial fetch's L2 hit. A served hit owes no write + // (read key == write key), and the deferred fetch rides that request's L1. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{true}, + }, + }, bothStore.Ops()) +} + +// TestL1LazyInitAndParallelWrites (M1 + M2): two parallel eligible entity +// fetches trigger exactly ONE BeginRequest, and their concurrent writes to the +// shared request cache produce an uncorrupted response (run under -race). +// One request through the engine, so the countingController's begins count is +// exactly this request's. +func TestL1LazyInitAndParallelWrites(t *testing.T) { + store := cachetesting.NewFakeStore() + query := `{ me { favoriteProduct { stock } } products(first: 2) { stock } }` + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Rules( + Rule(`"representations"`, `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`), + Rule(`"variables":{"a":2}`, `{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`), + ) + // The batch fetch is the only one whose representations carry upc 2, so it + // must be matched first; the remaining upc-1 body is the single fetch. + batchFetch := Rule(`"upc":"2"`, `{"data":{"_entities":[{"__typename":"Product","stock":5},{"__typename":"Product","stock":7}]}}`) + singleFetch := Rule(`"upc":"1"`, `{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + inventory := Rules(batchFetch, singleFetch) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + controller := &countingController{inner: cachetesting.NewRealishCache(store, nil)} + body := Execute(t, executionEngine, query, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"stock":5}},"products":[{"stock":5},{"stock":7}]}}`, body) + // M1: exactly one BeginRequest despite two parallel eligible fetches. + assert.Equal(t, int64(1), controller.begins.Load()) + // M2: both fetches wrote (single write + batch writes) without corruption. + assert.Equal(t, int64(1), singleFetch.Count.Load()) + assert.Equal(t, int64(1), batchFetch.Count.Load()) +} diff --git a/execution/cachingtesting/loader_bench_test.go b/execution/cachingtesting/loader_bench_test.go new file mode 100644 index 0000000000..1dabea1baa --- /dev/null +++ b/execution/cachingtesting/loader_bench_test.go @@ -0,0 +1,279 @@ +package cachingtesting + +import ( + "context" + "sync" + "testing" + "time" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// benchStore is the benchmark L2 store: a plain RWMutex map with NO op +// logging, so the measurements show the loader + cache hot paths and not the +// test double's bookkeeping. +type benchStore struct { + mu sync.RWMutex + data map[string]benchEntry +} + +type benchEntry struct { + value []byte + expiresAt time.Time +} + +func newBenchStore() *benchStore { + return &benchStore{data: make(map[string]benchEntry)} +} + +func (s *benchStore) GetMany(_ context.Context, keys []string) ([]cache.Entry, error) { + entries := make([]cache.Entry, len(keys)) + s.mu.RLock() + defer s.mu.RUnlock() + for i, key := range keys { + entry, ok := s.data[key] + if !ok { + continue + } + entries[i] = cache.Entry{ + Value: entry.value, + RemainingTTL: time.Until(entry.expiresAt), + OK: true, + } + } + return entries, nil +} + +func (s *benchStore) SetMany(_ context.Context, items []cache.Item) error { + s.mu.Lock() + defer s.mu.Unlock() + for _, item := range items { + s.data[item.Key] = benchEntry{value: item.Value, expiresAt: time.Now().Add(item.TTL)} + } + return nil +} + +// discardWriter drops the rendered response (rendering cost stays included, +// buffer growth noise does not). +type discardWriter struct{} + +func (discardWriter) Write(p []byte) (int, error) { return len(p), nil } + +// benchResolve plans once and resolves the SAME plan per iteration — the +// router's production mode (plans are cached and reused) — with ONE resolver +// and one controller across iterations and a fresh Context per request. +func benchResolve(b *testing.B, result PlanResult, controller resolve.CacheController) { + b.Helper() + r := resolve.New(context.Background(), resolve.ResolverOptions{MaxConcurrency: 1024}) + b.ReportAllocs() + for b.Loop() { + ctx := resolve.NewContext(context.Background()) + if controller != nil { + ctx.SetCacheController(controller) + } + if _, err := r.ResolveGraphQLResponse(ctx, result.Response, nil, discardWriter{}); err != nil { + b.Fatal(err) + } + } +} + +// BenchmarkLoader measures the loader hot paths per fetch type, with and +// without caching. All caching variants are steady-state HITS (primed before +// the loop) unless named otherwise. +func BenchmarkLoader(b *testing.B) { + entityQuery := `{ me { username favoriteProduct { upc stock } } }` + entityResponses := map[string]string{ + "users": `{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`, + "products:me": `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`, + "inventory:me.favoriteProduct": `{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`, + } + entityCaching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Hour)}, + }, + } + + batchQuery := `{ products(first: 2) { upc reviews { body } } }` + batchResponses := map[string]string{ + "products": `{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`, + "reviews": `{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`, + } + batchCaching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(time.Hour)}, + }, + } + partialCaching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": { + DefaultTTL: ptr(time.Hour), + EnablePartialCacheLoad: ptr(true), + }, + }, + } + + rootFieldQuery := `query($first: Int!) { products(first: $first) { upc name } }` + rootFieldResponses := map[string]string{ + "products": `{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"}]}}`, + } + rootFieldCaching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", TTL: time.Hour}, + }, + }, + }, + } + + chainQuery := `{ deal(id: "d1") { product { name reviews { product { name } } } } }` + chainResponses := map[string]string{ + "deals": `{"data":{"deal":{"__typename":"Deal","id":"d1","product":{"__typename":"Product","sku":"S1"}}}}`, + "products:deal.product": `{"data":{"_entities":[{"__typename":"Product","name":"Table","upc":"1"}]}}`, + "reviews": `{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","product":{"__typename":"Product","upc":"1"}}]}]}}`, + "products:deal.product.reviews.@.product": `{"data":{"_entities":[{"__typename":"Product","name":"Table"}]}}`, + } + chainCaching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": {DefaultTTL: ptr(time.Hour)}, + }, + } + + prime := func(b *testing.B, result PlanResult, controller resolve.CacheController) { + b.Helper() + r := resolve.New(context.Background(), resolve.ResolverOptions{MaxConcurrency: 1024}) + ctx := resolve.NewContext(context.Background()) + ctx.SetCacheController(controller) + if _, err := r.ResolveGraphQLResponse(ctx, result.Response, nil, discardWriter{}); err != nil { + b.Fatal(err) + } + } + + b.Run("entity/no-cache", func(b *testing.B) { + benchResolve(b, Plan(b, entityQuery, nil, entityResponses), nil) + }) + b.Run("entity/l2-hit", func(b *testing.B) { + result := Plan(b, entityQuery, entityCaching, entityResponses) + controller := cache.NewController(newBenchStore(), nil) + prime(b, result, controller) + benchResolve(b, result, controller) + }) + b.Run("entity/l2-miss-write", func(b *testing.B) { + // Every iteration misses and writes: missStore never returns hits and + // swallows writes, keeping the steady-state miss+write path measurable + // without unbounded map growth. + result := Plan(b, entityQuery, entityCaching, entityResponses) + controller := cache.NewController(missStore{}, nil) + benchResolve(b, result, controller) + }) + + b.Run("batch/no-cache", func(b *testing.B) { + benchResolve(b, Plan(b, batchQuery, nil, batchResponses), nil) + }) + b.Run("batch/l2-hit", func(b *testing.B) { + result := Plan(b, batchQuery, batchCaching, batchResponses) + controller := cache.NewController(newBenchStore(), nil) + prime(b, result, controller) + benchResolve(b, result, controller) + }) + b.Run("batch/partial-hit", func(b *testing.B) { + // One of two entities primed: every iteration filters the batch and + // fetches the other (the canned response only matches the REDUCED + // request, so the partial path is proven exercised). + primeResult := Plan(b, `{ products(first: 1) { upc reviews { body } } }`, partialCaching, map[string]string{ + "products": `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`, + "reviews": `{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]}]}}`, + }) + store := newBenchStore() + controller := cache.NewController(store, nil) + prime(b, primeResult, controller) + // partialShapeStore serves the primed upc 1 entry but drops the + // iteration's upc 2 write-backs, so the one-of-two-primed partial + // shape holds for every iteration. + result := Plan(b, batchQuery, partialCaching, map[string]string{ + "products": `{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`, + "reviews": `{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`, + }) + partial := &partialShapeStore{inner: store} + partialController := cache.NewController(partial, nil) + benchResolve(b, result, partialController) + }) + + b.Run("rootfield/no-cache", func(b *testing.B) { + result := Plan(b, rootFieldQuery, nil, rootFieldResponses) + benchResolveWithVariables(b, result, `{"first":1}`, nil) + }) + b.Run("rootfield/l2-hit", func(b *testing.B) { + result := Plan(b, rootFieldQuery, rootFieldCaching, rootFieldResponses) + controller := cache.NewController(newBenchStore(), nil) + primeWithVariables(b, result, `{"first":1}`, controller) + benchResolveWithVariables(b, result, `{"first":1}`, controller) + }) + + b.Run("chain/no-cache", func(b *testing.B) { + benchResolve(b, Plan(b, chainQuery, nil, chainResponses), nil) + }) + b.Run("chain/l2-hit", func(b *testing.B) { + // Two entity fetches reach ONE Product through different + // representations ({sku} then {upc}), so they own independent entries + // and each hits L2 per request; the reviews hop between them stays + // uncached. + result := Plan(b, chainQuery, chainCaching, chainResponses) + controller := cache.NewController(newBenchStore(), nil) + prime(b, result, controller) + benchResolve(b, result, controller) + }) +} + +// missStore never hits and swallows writes: the steady-state miss+write path +// without unbounded map growth. +type missStore struct{} + +func (missStore) GetMany(_ context.Context, keys []string) ([]cache.Entry, error) { + return make([]cache.Entry, len(keys)), nil +} + +func (missStore) SetMany(context.Context, []cache.Item) error { return nil } + +// partialShapeStore serves reads from the primed inner store but drops writes, +// so the one-of-two-primed partial shape holds for every iteration. +type partialShapeStore struct { + inner *benchStore +} + +func (s *partialShapeStore) GetMany(ctx context.Context, keys []string) ([]cache.Entry, error) { + return s.inner.GetMany(ctx, keys) +} + +func (s *partialShapeStore) SetMany(context.Context, []cache.Item) error { return nil } + +func benchResolveWithVariables(b *testing.B, result PlanResult, variables string, controller resolve.CacheController) { + b.Helper() + r := resolve.New(context.Background(), resolve.ResolverOptions{MaxConcurrency: 1024}) + b.ReportAllocs() + for b.Loop() { + ctx := resolve.NewContext(context.Background()) + ctx.Variables = astjson.MustParseBytes([]byte(variables)) + if controller != nil { + ctx.SetCacheController(controller) + } + if _, err := r.ResolveGraphQLResponse(ctx, result.Response, nil, discardWriter{}); err != nil { + b.Fatal(err) + } + } +} + +func primeWithVariables(b *testing.B, result PlanResult, variables string, controller resolve.CacheController) { + b.Helper() + r := resolve.New(context.Background(), resolve.ResolverOptions{MaxConcurrency: 1024}) + ctx := resolve.NewContext(context.Background()) + ctx.Variables = astjson.MustParseBytes([]byte(variables)) + ctx.SetCacheController(controller) + if _, err := r.ResolveGraphQLResponse(ctx, result.Response, nil, discardWriter{}); err != nil { + b.Fatal(err) + } +} diff --git a/execution/cachingtesting/negative_e2e_test.go b/execution/cachingtesting/negative_e2e_test.go new file mode 100644 index 0000000000..138fc2630b --- /dev/null +++ b/execution/cachingtesting/negative_e2e_test.go @@ -0,0 +1,81 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// inventoryNegativeCaching enables entity caching with a negative TTL. +func inventoryNegativeCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(time.Minute), + NegativeCacheTTL: ptr(10 * time.Second), + }, + }, + } +} + +// TestNegativeCachingEndToEnd: request 1 fetches a nonexistent entity (the +// subgraph SUCCESSFULLY returns a null entity) and writes the sentinel; +// request 2 serves the same null response with ZERO network to inventory. +// Runs through the REAL ExecutionEngine over HTTP subgraph doubles. +func TestNegativeCachingEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + query := `{ me { favoriteProduct { upc stock } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"404"}}]}}`) + inventory := Respond(`{"data":{"_entities":[null]}}`) + executionEngine := NewEngine(t, inventoryNegativeCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + firstBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, int64(1), inventory.Requests()) + + // The sentinel was written with the NEGATIVE TTL. + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":null,"cc":{"ttl":10,"created":-1,"scope":"public"}}`, + TTL: 10 * time.Second, + // The sentinel carries the entity's full tag set, so a purge + // of the product also clears its "does not exist" record. + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:0256cf786a3c1be7", // upc "404" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + secondBody := Execute(t, executionEngine, query, controller) + // ZERO new network to inventory: the negative sentinel served. + assert.Equal(t, int64(1), inventory.Requests()) + + // The negative hit reproduces the empty-fetch response BYTE-IDENTICALLY — + // the same null bubble AND the same non-null error the uncached path + // renders; caching never changes the response (G6 end to end). + assert.Equal(t, firstBody, secondBody) + assert.Equal(t, `{"errors":[{"message":"Cannot return null for non-nullable field 'Query.me.favoriteProduct.stock'.","path":["me","favoriteProduct","stock"]}],"data":{"me":{"favoriteProduct":null}}}`, firstBody) +} diff --git a/execution/cachingtesting/normalization_e2e_test.go b/execution/cachingtesting/normalization_e2e_test.go new file mode 100644 index 0000000000..7b63a54f00 --- /dev/null +++ b/execution/cachingtesting/normalization_e2e_test.go @@ -0,0 +1,96 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" +) + +// TestAliasIndependentReuseEndToEnd: operation A caches the inventory entity +// under one alias; operation B selects the same field under a DIFFERENT alias +// and is served from the cache (zero inventory requests), each with its +// complete response asserted. Runs through the REAL ExecutionEngine. +func TestAliasIndependentReuseEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","inStock":5}]}}`) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + firstBody := Execute(t, executionEngine, `{ me { favoriteProduct { upc inStock: stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","inStock":5}}}}`, firstBody) + assert.Equal(t, int64(1), inventory.Requests()) + + // The STORED form is normalized to the schema name; the write key equals + // the miss-lookup's key (read key == write key — ops[0] is the read). + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"stock":5,"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + secondBody := Execute(t, executionEngine, `{ me { favoriteProduct { upc availability: stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","availability":5}}}}`, secondBody) + // Served from the cache: ZERO new inventory requests. + assert.Equal(t, int64(1), inventory.Requests()) +} + +// TestArgumentMismatchEndToEnd: the same entity field with DIFFERENT argument +// values must never share a cache entry — request B misses and fetches. +func TestArgumentMismatchEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + // One rule per distinct argument value (the engine renames $days to $a in + // the rendered body): the days:3 rule serves the first request only (the + // repeat must be a cache hit — its count pins that); the days:1 rule + // proves the different-arguments miss really fetched. + days3 := Rule(`"a":3`, `{"data":{"_entities":[{"__typename":"Product","stockHistory":[1,2,3]}]}}`) + days1 := Rule(`"a":1`, `{"data":{"_entities":[{"__typename":"Product","stockHistory":[7]}]}}`) + inventory := Rules(days3, days1) + executionEngine := NewEngine(t, inventoryCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + query := `query($days: Int!) { me { favoriteProduct { upc stockHistory(days: $days) } } }` + + firstBody := ExecuteWithVariables(t, executionEngine, query, `{"days":3}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[1,2,3]}}}}`, firstBody) + assert.Equal(t, int64(1), days3.Count.Load()) + + // Same variables → HIT (the suffix matches): no new days:3 request. + sameBody := ExecuteWithVariables(t, executionEngine, query, `{"days":3}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[1,2,3]}}}}`, sameBody) + assert.Equal(t, int64(1), days3.Count.Load()) + assert.Equal(t, int64(0), days1.Count.Load()) + + // Different variables → MISS: the fetch runs and returns the new data. + differentBody := ExecuteWithVariables(t, executionEngine, query, `{"days":1}`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[7]}}}}`, differentBody) + assert.Equal(t, int64(1), days1.Count.Load()) +} diff --git a/execution/cachingtesting/partial_e2e_test.go b/execution/cachingtesting/partial_e2e_test.go new file mode 100644 index 0000000000..3b6146746b --- /dev/null +++ b/execution/cachingtesting/partial_e2e_test.go @@ -0,0 +1,109 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// reviewsPartialCaching enables partial cache loading for the Product entity +// on the reviews subgraph. +func reviewsPartialCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": { + DefaultTTL: ptr(time.Minute), + EnablePartialCacheLoad: ptr(true), + }, + }, + } +} + +// TestPartialBatchEndToEnd: with one of two products' reviews already cached, +// the reviews subgraph receives EXACTLY the missing representation and the +// response is complete — cached and fetched reviews at their original +// positions. Runs through the REAL ExecutionEngine; the reduced batch is +// proven by pinning the reviews double's COMPLETE second request body. +func TestPartialBatchEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + products := Rules( + Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`), + Rule(`"variables":{"a":2}`, `{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`), + ) + // The second rule carries ONE entity — it can only answer a REDUCED + // single-representation batch; the Bodies() pin below proves the reduced + // request is what actually went over the wire. + reviews := Rules( + Rule(`"upc":"1"`, `{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","body":"great table"}]}]}}`), + Rule(`"upc":"2"`, `{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","body":"sturdy chair"}]}]}}`), + ) + executionEngine := NewEngine(t, reviewsPartialCaching(), Subgraphs{"products": products, "reviews": reviews}) + + // Prime product 1's reviews. + primeBody := Execute(t, executionEngine, `{ products(first: 1) { upc reviews { body } } }`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"great table"}]}]}}`, primeBody) + + // Two products now: product 1 covered, product 2 missing. + secondBody := Execute(t, executionEngine, `{ products(first: 2) { upc reviews { body } } }`, controller) + assert.Equal(t, + `{"data":{"products":[{"upc":"1","reviews":[{"body":"great table"}]},{"upc":"2","reviews":[{"body":"sturdy chair"}]}]}}`, + secondBody) + + // The EXACT subgraph input: only the missing representation was sent. + bodies := reviews.Bodies() + require.Len(t, bodies, 2) + assert.Equal(t, `{"query":"query($representations: [_Any!]!){_entities(representations: $representations){... on Product {__typename reviews {body}}}}","variables":{"representations":[{"__typename":"Product","upc":"2"}]}}`, bodies[1]) +} + +// TestPartialExpiryEndToEnd: mixed TTLs across subgraphs — when one policy's +// entry expires, only THAT subgraph is re-fetched; the still-fresh portion is +// served from cache. +func TestPartialExpiryEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(5 * time.Minute)}, + "inventory": {DefaultTTL: ptr(30 * time.Second)}, + }, + } + query := `{ products(first: 1) { upc stock reviews { body } } }` + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","body":"great table"}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory, "reviews": reviews}) + expected := `{"data":{"products":[{"upc":"1","stock":5,"reviews":[{"body":"great table"}]}]}}` + + firstBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, firstBody) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, int64(1), reviews.Requests()) + + // Age ONLY the short-TTL inventory entry past its TTL (store-double aging; + // the exact TTL arithmetic is pinned by the synctest unit rows). + var inventoryKey string + for _, op := range store.Ops() { + for _, item := range op.Items { + if item.TTL == 30*time.Second { + inventoryKey = item.Key + } + } + } + require.NotEmpty(t, inventoryKey) + value, ok := store.Value(inventoryKey) + require.True(t, ok) + store.Seed(inventoryKey, value, -time.Second) + + secondBody := Execute(t, executionEngine, query, controller) + assert.Equal(t, expected, secondBody) + // ONLY the expired portion hit the network: inventory refetched, reviews + // still served from its fresh entry. + assert.Equal(t, int64(2), inventory.Requests()) + assert.Equal(t, int64(1), reviews.Requests()) +} diff --git a/execution/cachingtesting/privacy_e2e_test.go b/execution/cachingtesting/privacy_e2e_test.go new file mode 100644 index 0000000000..d45fcd1796 --- /dev/null +++ b/execution/cachingtesting/privacy_e2e_test.go @@ -0,0 +1,343 @@ +package cachingtesting + +import ( + "net/http" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// requesterIdentity is the integrator's partition hook: the identity this +// request's private cache entries belong to, the same for every subgraph. An +// empty identity is the anonymous request the hook cannot name. +type requesterIdentity string + +func (r requesterIdentity) PrivatePartition(*resolve.Context, string) (string, bool) { + return string(r), r != "" +} + +// forwardedHeaders is the subgraph header source: one header line per subgraph +// request plus the hash the engine identifies it by — the hash the cache uses +// to vary public entries and to partition private ones. +type forwardedHeaders struct { + tenant string + hash uint64 +} + +func (f forwardedHeaders) HeadersForSubgraph(string) (http.Header, uint64) { + return http.Header{"X-Tenant": []string{f.tenant}}, f.hash +} + +func (f forwardedHeaders) HashAll() uint64 { + return f.hash +} + +// TestPrivatePartitionEndToEnd drives privacy through the REAL ExecutionEngine +// over REAL HTTP upstreams: who gets their own entry, who gets none, and what +// the store ends up holding. +func TestPrivatePartitionEndToEnd(t *testing.T) { + t.Run("two requesters alternate: two entries, each hit only by its own owner", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(time.Minute), + Scope: ptr(cacheconfig.CacheScopePrivate), + }, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + query := `{ me { favoriteProduct { upc stock } } }` + expected := `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}` + + // Request 1 (user-a): miss, one write. + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-a")))) + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + keyA := ops[0].Keys[0] + + // Request 2 (user-b): the SAME entity, a different key — so a miss again. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-b")))) + ops = store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + keyB := ops[0].Keys[0] + assert.NotEqual(t, keyA, keyB) + // Neither is the key a public inventory fetch derives (pinned literally by + // the public rows), so the partition really moved the entry. + assert.NotEqual(t, "v1:1:4f796e3bbd360fce", keyA) + assert.NotEqual(t, "v1:1:4f796e3bbd360fce", keyB) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{keyB}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: keyB, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"private"}}`, + TTL: time.Minute, + // The partition lives in the KEY only: user B's tags are + // byte-identical to user A's, so one purge of the product + // clears every requester's partition of it. + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + // Requests 3 and 4 repeat both identities: each hits its OWN entry, and a + // served hit owes no write. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-a")))) + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-b")))) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{keyA}, + Hits: []bool{true}, + }, + { + Kind: "GetMany", + Keys: []string{keyB}, + Hits: []bool{true}, + }, + }, store.Ops()) + // Exactly two inventory fetches for four requests: the two misses. + assert.Equal(t, int64(2), inventory.Requests()) + }) + + t.Run("an anonymous requester writes nothing but still reuses within its request", func(t *testing.T) { + store := cachetesting.NewFakeStore() + observer := &cachetesting.RecordingObserver{} + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(time.Minute), + Scope: ptr(cacheconfig.CacheScopePrivate), + }, + }, + } + products := Rules( + Rule(`product(upc: $a)`, `{"data":{"product":{"__typename":"Product","upc":"1"},"products":[{"__typename":"Product","upc":"1"}]}}`), + ) + // The initial fetch selects {stock, warehouse}; the DEFERRED fetch of the + // same representation selects {stock} alone and would ride L1. Its canned + // stock is tampered to 999, so any real network use is visible. + initialFetch := Rule(`warehouse`, `{"data":{"_entities":[{"__typename":"Product","stock":5,"warehouse":{"__typename":"Warehouse","id":"w1","location":"Berlin"}}]}}`) + deferredFetch := Rule(``, `{"data":{"_entities":[{"__typename":"Product","stock":999}]}}`) + inventory := Rules(initialFetch, deferredFetch) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "inventory": inventory}) + + frames := ExecuteDefer(t, executionEngine, + `{ product(upc: "1") { stock warehouse { id location } } products(first: 1) { upc ... @defer { stock } } }`, + cachetesting.NewRealishCache(store, observer), + engine.WithPrivatePartitionProvider(requesterIdentity(""))) + assert.Equal(t, []string{ + `{"data":{"product":{"stock":5,"warehouse":{"id":"w1","location":"Berlin"}},"products":[{"upc":"1"}]},"pending":[{"id":"1","path":["products"]}],"hasNext":true}`, + // stock 5, not the tampered 999: the deferred group read L1, which + // privacy never disables. + `{"incremental":[{"data":{"stock":5},"id":"1","subPath":[0]}],"completed":[{"id":"1"}],"hasNext":false}`, + }, frames) + assert.Equal(t, int64(1), initialFetch.Count.Load()) + assert.Equal(t, int64(0), deferredFetch.Count.Load()) + // Not one store op: no key was derived for either fetch. + assert.Equal(t, []cachetesting.StoreOp(nil), store.Ops()) + // One hint per fetch that lost its store access, naming the remedy. + assert.Equal(t, []cache.UncacheablePrivate{ + {Subgraph: "1", Reason: cache.UncacheablePrivateNoIdentity}, + {Subgraph: "1", Reason: cache.UncacheablePrivateNoIdentity}, + }, observer.UncacheablePrivate()) + }) + + t.Run("without a hook the forwarded header hash partitions the entries", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(time.Minute), + Scope: ptr(cacheconfig.CacheScopePrivate), + IncludeSubgraphHeaders: ptr(true), + }, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + query := `{ me { favoriteProduct { upc stock } } }` + expected := `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}` + + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithSubgraphHeadersBuilder(forwardedHeaders{tenant: "acme", hash: 111}))) + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + acmeKey := ops[0].Keys[0] + + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithSubgraphHeadersBuilder(forwardedHeaders{tenant: "globex", hash: 222}))) + ops = store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + globexKey := ops[0].Keys[0] + assert.NotEqual(t, acmeKey, globexKey) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{globexKey}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: globexKey, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"private"}}`, + TTL: time.Minute, + // The header-derived partition rides the key alone; the + // tags carry no header material either. + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + // The first tenant's repeat request hits its own entry — nothing crossed. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithSubgraphHeadersBuilder(forwardedHeaders{tenant: "acme", hash: 111}))) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{acmeKey}, + Hits: []bool{true}, + }, + }, store.Ops()) + }) + + t.Run("config drift: a private entry under a public key is discarded and refetched", func(t *testing.T) { + store := cachetesting.NewFakeStore() + observer := &cachetesting.RecordingObserver{} + // The deployment that wrote this entry had inventory PRIVATE; this one has + // it public, so the very key it reads carries a private-scoped value. + store.Seed("v1:1:4f796e3bbd360fce", + []byte(`{"data":{"__typename":"Product","stock":999},"cc":{"ttl":60,"created":1785852117,"scope":"private"}}`), + time.Minute) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, + cachetesting.NewRealishCache(store, observer)) + // stock 5 from the origin, never the seeded 999. + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Equal(t, map[cache.ScopeMismatch]int{ + {Subgraph: "1", StoredScope: "private"}: 1, + }, observer.ScopeMismatches()) + // The read HIT and was thrown away; the fresh public value replaced it. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{true}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) + + t.Run("a public subgraph keys exactly as it did before privacy existed", func(t *testing.T) { + store := cachetesting.NewFakeStore() + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(5 * time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, + cachetesting.NewRealishCache(store, nil), + // A partition provider that WOULD identify this requester changes + // nothing: only a private declaration partitions a key. + engine.WithPrivatePartitionProvider(requesterIdentity("user-a"))) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":300,"created":-1,"scope":"public"}}`, + TTL: 5 * time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) +} diff --git a/execution/cachingtesting/provides_data_test.go b/execution/cachingtesting/provides_data_test.go new file mode 100644 index 0000000000..626e3180c4 --- /dev/null +++ b/execution/cachingtesting/provides_data_test.go @@ -0,0 +1,160 @@ +package cachingtesting + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// enableCaching is the minimal caching configuration that makes the +// provides-data walk run; the configured values are irrelevant to +// ProvidesData itself. +func enableCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{"products": {}}, + } +} + +// TestProvidesDataFidelity is the fidelity gate over REAL federation plans +// (real fieldPlanners from the main walk, not synthetic attribution): the full +// per-fetch ProvidesData side-table is pinned for a root + batch-entity plan. +// This is a planner-level test that pins plan-internal state (the ProvidesData +// resolve.Object trees) not visible in a client response. +func TestProvidesDataFidelity(t *testing.T) { + result := Plan(t, `{ products(first: 2) { upc name reviews { body } } }`, enableCaching(), nil) + pd := result.Response.CacheProvidesData() + require.Len(t, pd, 2) + + byDS := make(map[string]*resolve.Object, len(pd)) + for info, obj := range pd { + require.NotContains(t, byDS, info.DataSourceID) + byDS[info.DataSourceID] = obj + } + + assert.Equal(t, map[string]*resolve.Object{ + // products root fetch: the full selection it returns, list-shaped. + "0": { + Fields: []*resolve.Field{ + { + Name: []byte("products"), + Value: &resolve.Array{ + Nullable: false, + Path: []string{"products"}, + Item: &resolve.Object{ + Nullable: false, + Fields: []*resolve.Field{ + { + Name: []byte("upc"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"upc"}, + }, + }, + { + Name: []byte("name"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"name"}, + }, + }, + { + Name: []byte("__typename"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"__typename"}, + }, + }, + }, + }, + }, + }, + }, + }, + // reviews batch entity fetch: the entity-boundary reset makes its tree + // start at the Product entity, with the entity type condition. + "2": { + Fields: []*resolve.Field{ + { + Name: []byte("reviews"), + Value: &resolve.Array{ + Nullable: false, + Path: []string{"reviews"}, + Item: &resolve.Object{ + Nullable: false, + Fields: []*resolve.Field{ + { + Name: []byte("body"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"body"}, + }, + }, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + }, + }, byDS) +} + +// TestProvidesDataDeferredFetchOwnTree pins that a DEFERRED fetch gets its own +// side-table entry (keyed per *FetchInfo, shared across the initial response +// and all defer groups): the deferred inventory fetch's tree is exactly +// {stock}, independent of the initial inventory fetch's larger tree. This is a +// planner-level test that pins plan-internal state (the deferred fetch's +// ProvidesData tree keyed by its *FetchInfo) not visible in a client response. +func TestProvidesDataDeferredFetchOwnTree(t *testing.T) { + query := ` + query { + me { favoriteProduct { upc stock warehouse { id location } } } + products(first: 1) { + upc + ... @defer { stock } + } + }` + result := Plan(t, query, enableCaching(), nil) + require.NotNil(t, result.DeferResponse) + pd := result.Response.CacheProvidesData() + require.NotEmpty(t, pd) + + groups := DeferGroups(result.DeferResponse) + require.Len(t, groups, 1) + deferredInfo := firstFetchInfo(t, groups[0].Fetches) + require.NotNil(t, deferredInfo) + + assert.Equal(t, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("stock"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"stock"}, + }, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + }, pd[deferredInfo]) +} + +// firstFetchInfo returns the FetchInfo of the first fetch item in the tree. +func firstFetchInfo(t *testing.T, node *resolve.FetchTreeNode) *resolve.FetchInfo { + t.Helper() + if node == nil { + return nil + } + if node.Item != nil && node.Item.Fetch != nil { + return node.Item.Fetch.FetchInfo() + } + for _, child := range node.ChildNodes { + if info := firstFetchInfo(t, child); info != nil { + return info + } + } + return nil +} diff --git a/execution/cachingtesting/rootfield_e2e_test.go b/execution/cachingtesting/rootfield_e2e_test.go new file mode 100644 index 0000000000..41bf73273b --- /dev/null +++ b/execution/cachingtesting/rootfield_e2e_test.go @@ -0,0 +1,92 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// productsRootFieldCaching enables root-field caching for Query.products on +// the products subgraph. +func productsRootFieldCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", TTL: time.Minute}, + }, + }, + }, + } +} + +// TestRootFieldL2EndToEnd: a cached root field is served from L2 on the second +// request with ZERO network, and an ALIAS-VARIANT operation over the same +// field and variables is served from the SAME entry; a different-arguments +// operation misses. Runs through the REAL ExecutionEngine, with one subgraph +// rule per distinct argument value. +func TestRootFieldL2EndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + query := `query($first: Int!) { products(first: $first) { upc name } }` + // The engine renames $first to $a in the rendered body: one rule per + // distinct argument value. + first1 := Rule(`"variables":{"a":1}`, `{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"}]}}`) + first5 := Rule(`"variables":{"a":5}`, `{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"}]}}`) + products := Rules(first1, first5) + executionEngine := NewEngine(t, productsRootFieldCaching(), Subgraphs{"products": products}) + + firstBody := ExecuteWithVariables(t, executionEngine, query, `{"first":1}`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","name":"Table"}]}}`, firstBody) + assert.Equal(t, int64(1), first1.Count.Load()) + + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key, + Value: `{"data":{"products":[{"__typename":"Product","upc":"1","name":"Table"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + // A whole-response root-field entry is not one entity, so it + // carries the two coarse tags only. + Tags: []string{ + "subgraph:0", + "type:0:Query", + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + // Same operation again: L2 hit, zero network. + secondBody := ExecuteWithVariables(t, executionEngine, query, `{"first":1}`, controller) + assert.Equal(t, firstBody, secondBody) + assert.Equal(t, int64(1), first1.Count.Load()) + + // ALIAS VARIANT over the same field + variables: served from the SAME entry. + aliasQuery := `query($first: Int!) { items: products(first: $first) { code: upc title: name } }` + aliasBody := ExecuteWithVariables(t, executionEngine, aliasQuery, `{"first":1}`, controller) + assert.Equal(t, `{"data":{"items":[{"code":"1","title":"Table"}]}}`, aliasBody) + assert.Equal(t, int64(1), first1.Count.Load()) + assert.Equal(t, int64(1), products.Requests()) + + // Different ARGUMENTS: a different key — miss, network runs. + differentBody := ExecuteWithVariables(t, executionEngine, query, `{"first":5}`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","name":"Table"}]}}`, differentBody) + assert.Equal(t, int64(1), first5.Count.Load()) +} diff --git a/execution/cachingtesting/shadow_e2e_test.go b/execution/cachingtesting/shadow_e2e_test.go new file mode 100644 index 0000000000..446a7b343a --- /dev/null +++ b/execution/cachingtesting/shadow_e2e_test.go @@ -0,0 +1,90 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// inventoryShadowCaching enables entity caching in SHADOW mode. +func inventoryShadowCaching() *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(time.Minute), + ShadowMode: ptr(true), + }, + }, + } +} + +// TestShadowModeEndToEnd: the response is ALWAYS the fresh network value even +// on an L2 hit; the shadow compare records the staleness probe. Runs through +// the REAL ExecutionEngine: all three requests carry the same body, so the +// inventory double's single rule is repointed between requests (the stock the +// subgraph currently reports), and each request builds its own controller so +// the RecordingObserver stays per-request. +func TestShadowModeEndToEnd(t *testing.T) { + store := cachetesting.NewFakeStore() + query := `{ me { favoriteProduct { upc stock } } }` + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventoryRule := Rule("", `{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + inventory := Rules(inventoryRule) + executionEngine := NewEngine(t, inventoryShadowCaching(), Subgraphs{"users": users, "products": products, "inventory": inventory}) + + // Request 1: shadow MISS — plain fetch + write. + firstObserver := &cachetesting.RecordingObserver{} + firstBody := Execute(t, executionEngine, query, cachetesting.NewRealishCache(store, firstObserver)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, firstBody) + assert.Equal(t, int64(1), inventory.Requests()) + assert.Empty(t, firstObserver.Compares()) + + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 1) + key := ops[0].Keys[0] + + // Request 2: L2 HIT under shadow — the subgraph now says stock=7 and the + // response MUST show 7 (fresh served, never the cached 5); the compare + // records the mismatch and L2 is overwritten with the fresh value. + inventoryRule.Response = `{"data":{"_entities":[{"__typename":"Product","stock":7}]}}` + secondObserver := &cachetesting.RecordingObserver{} + secondBody := Execute(t, executionEngine, query, cachetesting.NewRealishCache(store, secondObserver)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":7}}}}`, secondBody) + // Shadow mode ALWAYS fetches: the request count accumulates to 2. + assert.Equal(t, int64(2), inventory.Requests()) + assert.Equal(t, []cachetesting.ShadowCompare{ + {CacheKey: key, IsFresh: false}, + }, normalizeCompareAges(secondObserver.Compares())) + + value, ok := store.Value(key) + require.True(t, ok) + assert.Equal(t, + `{"data":{"__typename":"Product","stock":7},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + NormalizeEnvelopeClock(string(value))) + + // Request 3: unchanged data — the compare records IsFresh true; the + // response is still the network value. + thirdObserver := &cachetesting.RecordingObserver{} + thirdBody := Execute(t, executionEngine, query, cachetesting.NewRealishCache(store, thirdObserver)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":7}}}}`, thirdBody) + assert.Equal(t, int64(3), inventory.Requests()) + assert.Equal(t, []cachetesting.ShadowCompare{ + {CacheKey: key, IsFresh: true}, + }, normalizeCompareAges(thirdObserver.Compares())) +} + +// normalizeCompareAges zeroes the real-clock CacheAge before the structural +// assert; the EXACT age is pinned by the synctest H2 unit row. +func normalizeCompareAges(compares []cachetesting.ShadowCompare) []cachetesting.ShadowCompare { + for i := range compares { + compares[i].CacheAge = 0 + } + return compares +} diff --git a/execution/cachingtesting/store_batching_e2e_test.go b/execution/cachingtesting/store_batching_e2e_test.go new file mode 100644 index 0000000000..d8db08c6ce --- /dev/null +++ b/execution/cachingtesting/store_batching_e2e_test.go @@ -0,0 +1,293 @@ +package cachingtesting + +import ( + "errors" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// TestStoreBatchingEndToEnd drives the REAL ExecutionEngine and pins the store +// CALL SHAPE end to end: one read per fetch carrying every key it needs, one +// write per request carrying every deferred item, and the degradation contract +// when the store fails. +func TestStoreBatchingEndToEnd(t *testing.T) { + t.Run("a batch entity fetch reads all keys in one call and writes them in one call", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(time.Minute)}, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "reviews": reviews}) + + body := Execute(t, executionEngine, `{ products(first: 2) { upc reviews { body } } }`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"2","reviews":[{"body":"Wobbly"}]}]}}`, body) + assert.Equal(t, int64(1), reviews.Requests()) + + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 2) + key1, key2 := ops[0].Keys[0], ops[0].Keys[1] + assert.NotEqual(t, key1, key2) + assert.Equal(t, []cachetesting.StoreOp{ + { + // ONE read for the whole batch: both entity keys, both missing. + Kind: "GetMany", + Keys: []string{key1, key2}, + Hits: []bool{false, false}, + }, + { + // ONE request-end write carrying both entities. + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key1, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Solid"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: key2, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Wobbly"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) + + t.Run("a fully served request reads once and writes nothing", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(time.Minute)}, + }, + } + query := `{ products(first: 2) { upc reviews { body } } }` + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "reviews": reviews}) + expected := `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"2","reviews":[{"body":"Wobbly"}]}]}}` + + // Request 1 primes both entries. + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + primeOps := store.Ops() + require.Len(t, primeOps, 2) + require.Len(t, primeOps[0].Keys, 2) + key1, key2 := primeOps[0].Keys[0], primeOps[0].Keys[1] + + // Request 2's ops assert in isolation. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + // The reviews upstream is NOT hit again. + assert.Equal(t, int64(1), reviews.Requests()) + assert.Equal(t, []cachetesting.StoreOp{ + { + // The full-batch hit: one read, both keys hitting. A served hit + // owes no write, so the request ends with no write call at all. + Kind: "GetMany", + Keys: []string{key1, key2}, + Hits: []bool{true, true}, + }, + }, store.Ops()) + }) + + t.Run("a failed read falls back to the origin and still writes back", func(t *testing.T) { + store := cachetesting.NewFakeStore() + observer := &cachetesting.RecordingObserver{} + controller := cachetesting.NewRealishCache(store, observer) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(time.Minute)}, + }, + } + query := `{ products(first: 2) { upc reviews { body } } }` + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "reviews": reviews}) + expected := `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"2","reviews":[{"body":"Wobbly"}]}]}}` + + // Request 1 primes both entries, so only the injected failure can send + // request 2 back to the origin. + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + primeOps := store.Ops() + require.Len(t, primeOps, 2) + require.Len(t, primeOps[0].Keys, 2) + key1, key2 := primeOps[0].Keys[0], primeOps[0].Keys[1] + + store.ResetOps() + readErr := errors.New("store read down") + store.FailGetMany(1, readErr) + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + // The response is correct AND the reviews upstream served it: every key + // of the failed read is a miss. + assert.Equal(t, int64(2), reviews.Requests()) + + assert.Equal(t, []cachetesting.StoreOp{ + { + // The failed call, with the keys it carried. + Kind: "GetMany", + Keys: []string{key1, key2}, + Failed: true, + }, + { + // The refetch still writes back: a failed read never blocks writes. + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key1, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Solid"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: key2, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Wobbly"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + + // ONE event for the failed call, naming the fetch's datasource. The + // committed fixture names its datasources by subgraph id, and "2" is + // the reviews subgraph. + assert.Equal(t, []cache.StoreError{ + {Op: "GetMany", Subgraph: "2", KeyCount: 2, Err: readErr}, + }, observer.StoreErrors()) + }) + + t.Run("a failed write is dropped without touching the response", func(t *testing.T) { + store := cachetesting.NewFakeStore() + observer := &cachetesting.RecordingObserver{} + controller := cachetesting.NewRealishCache(store, observer) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(time.Minute)}, + }, + } + query := `{ products(first: 2) { upc reviews { body } } }` + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "reviews": reviews}) + expected := `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"2","reviews":[{"body":"Wobbly"}]}]}}` + + writeErr := errors.New("store write down") + store.FailSetMany(1, writeErr) + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 2) + key1, key2 := ops[0].Keys[0], ops[0].Keys[1] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key1, key2}, + Hits: []bool{false, false}, + }, + { + // The flush was rejected, so nothing was stored. + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key1, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Solid"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: key2, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Wobbly"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + Failed: true, + }, + }, NormalizeStoreOpsClock(ops)) + _, stored := store.Value(key1) + assert.False(t, stored) + + // The request-end flush spans every fetch, so it names no subgraph. + assert.Equal(t, []cache.StoreError{ + {Op: "SetMany", Subgraph: "", KeyCount: 2, Err: writeErr}, + }, observer.StoreErrors()) + + // The dropped writes leave the entries unprimed: the next request is a + // plain miss that fetches again and writes again (the injection budget + // is spent, so this flush lands). + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + assert.Equal(t, int64(2), reviews.Requests()) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key1, key2}, + Hits: []bool{false, false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key1, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Solid"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: key2, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Wobbly"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) +} diff --git a/execution/cachingtesting/subgraphs/deals.graphql b/execution/cachingtesting/subgraphs/deals.graphql new file mode 100644 index 0000000000..e11bd6aaf1 --- /dev/null +++ b/execution/cachingtesting/subgraphs/deals.graphql @@ -0,0 +1,10 @@ +extend type Query { + deal(id: ID!): Deal +} +type Deal { + id: ID! + product: Product! +} +extend type Product @key(fields: "sku") { + sku: String! @external +} diff --git a/execution/cachingtesting/subgraphs/inventory.graphql b/execution/cachingtesting/subgraphs/inventory.graphql new file mode 100644 index 0000000000..56018ddb47 --- /dev/null +++ b/execution/cachingtesting/subgraphs/inventory.graphql @@ -0,0 +1,10 @@ +extend type Product @key(fields: "upc") { + upc: String! @external + stock: Int! + stockHistory(days: Int!): [Int!]! + warehouse: Warehouse! +} +type Warehouse { + id: ID! + location: String! +} diff --git a/execution/cachingtesting/subgraphs/products.graphql b/execution/cachingtesting/subgraphs/products.graphql new file mode 100644 index 0000000000..ca6d0a9cb8 --- /dev/null +++ b/execution/cachingtesting/subgraphs/products.graphql @@ -0,0 +1,16 @@ +extend type Query { + products(first: Int = 5): [Product!]! + promotions: [Product!]! + product(upc: String!): Product + productBySku(sku: String!): Product +} +type Product @key(fields: "upc") @key(fields: "sku") { + upc: String! + sku: String! + name: String! + price: Int! +} +extend type User @key(fields: "id") { + id: ID! @external + favoriteProduct: Product +} diff --git a/execution/cachingtesting/subgraphs/reviews.graphql b/execution/cachingtesting/subgraphs/reviews.graphql new file mode 100644 index 0000000000..f22cf22503 --- /dev/null +++ b/execution/cachingtesting/subgraphs/reviews.graphql @@ -0,0 +1,18 @@ +extend type Query { + latestReviews(first: Int = 5): [Review!]! + featuredReview: Review +} +type Review { + id: ID! + body: String! + author: User! + product: Product! +} +extend type User @key(fields: "id") { + id: ID! @external + reviews: [Review!]! +} +extend type Product @key(fields: "upc") { + upc: String! @external + reviews: [Review!]! +} diff --git a/execution/cachingtesting/subgraphs/users.graphql b/execution/cachingtesting/subgraphs/users.graphql new file mode 100644 index 0000000000..3472426401 --- /dev/null +++ b/execution/cachingtesting/subgraphs/users.graphql @@ -0,0 +1,8 @@ +extend type Query { + me: User + user(id: ID!): User +} +type User @key(fields: "id") { + id: ID! + username: String! +} diff --git a/execution/cachingtesting/tags_e2e_test.go b/execution/cachingtesting/tags_e2e_test.go new file mode 100644 index 0000000000..bd18fac002 --- /dev/null +++ b/execution/cachingtesting/tags_e2e_test.go @@ -0,0 +1,219 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// TestDefaultTagsEndToEnd drives the default tag vocabulary through the REAL +// ExecutionEngine over REAL HTTP upstreams. Keys are identity and tags are +// addressing, so the rows below all probe the same property from different +// sides: entries whose KEYS must differ still have to be reachable by ONE +// entity tag. The committed fixture names its datasources by subgraph id — "1" +// is inventory, "2" is reviews. +func TestDefaultTagsEndToEnd(t *testing.T) { + t.Run("a batch write tags every entity of the batch on its own @key subset", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "reviews": {DefaultTTL: ptr(time.Minute)}, + }, + } + products := Respond(`{"data":{"products":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"}]}}`) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"body":"Solid"}]},{"__typename":"Product","reviews":[{"body":"Wobbly"}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"products": products, "reviews": reviews}) + + body := Execute(t, executionEngine, `{ products(first: 2) { upc reviews { body } } }`, controller) + assert.Equal(t, `{"data":{"products":[{"upc":"1","reviews":[{"body":"Solid"}]},{"upc":"2","reviews":[{"body":"Wobbly"}]}]}}`, body) + + ops := store.Ops() + require.Len(t, ops, 2) + require.Len(t, ops[0].Keys, 2) + key1, key2 := ops[0].Keys[0], ops[0].Keys[1] + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{key1, key2}, + Hits: []bool{false, false}, // cold store: both entities miss + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: key1, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Solid"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + // One batch, one subgraph, one type: the two items' + // tag sets differ in the entity digest ALONE. + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:d3cc039c7a9789e7", // xxhash64 of `{"upc":"1"}` + }, + }, + { + Key: key2, + Value: `{"data":{"__typename":"Product","reviews":[{"body":"Wobbly"}]},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:2", + "type:2:Product", + "entity:2:Product:4f93140518d68e67", // xxhash64 of `{"upc":"2"}` + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) + + t.Run("argument variants are two entries under ONE entity tag", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": {DefaultTTL: ptr(time.Minute)}, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1","username":"jens"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + // One rule per argument value (the engine renames $days to $a in the + // rendered body). + inventory := Rules( + Rule(`"a":3`, `{"data":{"_entities":[{"__typename":"Product","stockHistory":[1,2,3]}]}}`), + Rule(`"a":1`, `{"data":{"_entities":[{"__typename":"Product","stockHistory":[7]}]}}`), + ) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + query := `query($days: Int!) { me { favoriteProduct { upc stockHistory(days: $days) } } }` + + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[1,2,3]}}}}`, + ExecuteWithVariables(t, executionEngine, query, `{"days":3}`, controller)) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stockHistory":[7]}}}}`, + ExecuteWithVariables(t, executionEngine, query, `{"days":1}`, controller)) + + wantTags := []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // xxhash64 of `{"upc":"1"}` — the args digest is not in it + } + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:1ea890ef1fe73466"}, + Hits: []bool{false}, // request 1: the days:3 entry does not exist yet + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:1ea890ef1fe73466", + Value: `{"data":{"stockHistory_f123752fc2272dfc":[1,2,3],"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: wantTags, + }, + }, + }, + { + Kind: "GetMany", + Keys: []string{"v1:1:e58401b99256d16d"}, + Hits: []bool{false}, // request 2: days:1 looks under its OWN key and misses + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + // A SECOND entry under a different key, carrying the + // IDENTICAL tag set: one purge of the product clears + // every argument variant of it. + Key: "v1:1:e58401b99256d16d", + Value: `{"data":{"stockHistory_b487e21691ea4c86":[7],"__typename":"Product"},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: wantTags, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) + + t.Run("private entries of two requesters carry no identity material in their tags", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(time.Minute), + Scope: ptr(cacheconfig.CacheScopePrivate), + }, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + query := `{ me { favoriteProduct { upc stock } } }` + expected := `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}` + + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-a")))) + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-b")))) + + ops := NormalizeStoreOpsClock(store.Ops()) + require.Len(t, ops, 4) + keyA, keyB := ops[1].Items[0].Key, ops[3].Items[0].Key + // The requester identity moved the KEYS apart — and away from the key a + // public inventory fetch would derive. + assert.NotEqual(t, keyA, keyB) + assert.NotEqual(t, "v1:1:4f796e3bbd360fce", keyA) + assert.NotEqual(t, "v1:1:4f796e3bbd360fce", keyB) + + // ... while both partitions are addressed by the very tags the public + // entry of this entity would carry. + wantTags := []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // xxhash64 of `{"upc":"1"}` — no partition, no header, no identity + } + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{keyA}, + Hits: []bool{false}, // user-a's partition is cold + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: keyA, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"private"}}`, + TTL: time.Minute, + Tags: wantTags, + }, + }, + }, + { + Kind: "GetMany", + Keys: []string{keyB}, + Hits: []bool{false}, // user-b derives another key, so it misses too + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: keyB, + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"private"}}`, + TTL: time.Minute, + Tags: wantTags, + }, + }, + }, + }, ops) + }) +} diff --git a/execution/cachingtesting/type_declaration_e2e_test.go b/execution/cachingtesting/type_declaration_e2e_test.go new file mode 100644 index 0000000000..82aa77ec80 --- /dev/null +++ b/execution/cachingtesting/type_declaration_e2e_test.go @@ -0,0 +1,297 @@ +package cachingtesting + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/execution/engine" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache/cachetesting" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// TestTypeDeclarationEndToEnd drives the narrowest static tier — the per-type +// declaration composition carries out of a subgraph's @cache directives — +// through the REAL ExecutionEngine over REAL HTTP upstreams: what it does to a +// written entry's lifetime, how it isolates one type of a subgraph from its +// siblings, and where the response header still overrules it. +func TestTypeDeclarationEndToEnd(t *testing.T) { + t.Run("a declared type is written under its own lifetime, not the subgraph default", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(5 * time.Minute), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 90 * time.Second}, + }, + }, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := Respond(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + // Both the envelope's cc.ttl and the store item's TTL carry the declared + // 90s instead of the subgraph's 5m. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":90,"created":-1,"scope":"public"}}`, + TTL: 90 * time.Second, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) + + t.Run("a type declared uncacheable touches the store not once while its sibling stays cached", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(time.Minute), + NegativeCacheTTL: ptr(5 * time.Second), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 0}, + }, + }, + }, + } + // One sequential chain reaching the products subgraph TWICE under two + // entity types: users.me -> products(User) -> reviews(Product) -> + // products(Product). + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + productsUser := Rule(`favoriteProduct`, `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + productsProduct := Rule(``, `{"data":{"_entities":[{"__typename":"Product","name":"Table"}]}}`) + products := Rules(productsUser, productsProduct) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","product":{"__typename":"Product","upc":"2"}}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "reviews": reviews}) + query := `{ me { favoriteProduct { upc reviews { product { name } } } } }` + expected := `{"data":{"me":{"favoriteProduct":{"upc":"1","reviews":[{"product":{"name":"Table"}}]}}}}` + + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + + // Only the User fetch reaches the store: the Product fetch of the SAME + // subgraph carries no cache configuration at all, negative sentinel + // included, so it neither looks up nor writes. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:0:ae7bd989bf833fe9"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:0:ae7bd989bf833fe9", + Value: `{"data":{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:0", + "type:0:User", + "entity:0:User:19ce389448be3351", // id "u1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + + // A second request serves the User fetch from L2 and fetches the + // uncacheable Product again. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller)) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:0:ae7bd989bf833fe9"}, + Hits: []bool{true}, + }, + }, store.Ops()) + assert.Equal(t, int64(1), productsUser.Count.Load()) + assert.Equal(t, int64(2), productsProduct.Count.Load()) + }) + + t.Run("a PRIVATE declaration partitions one type while its sibling shares publicly", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(time.Minute), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second, Scope: cacheconfig.CacheScopePrivate}, + }, + }, + }, + } + // The same sequential chain, reaching the products subgraph as User and + // then as Product. + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + productsUser := Rule(`favoriteProduct`, `{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + productsProduct := Rule(``, `{"data":{"_entities":[{"__typename":"Product","name":"Table"}]}}`) + products := Rules(productsUser, productsProduct) + reviews := Respond(`{"data":{"_entities":[{"__typename":"Product","reviews":[{"__typename":"Review","product":{"__typename":"Product","upc":"2"}}]}]}}`) + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "reviews": reviews}) + query := `{ me { favoriteProduct { upc reviews { product { name } } } } }` + expected := `{"data":{"me":{"favoriteProduct":{"upc":"1","reviews":[{"product":{"name":"Table"}}]}}}}` + + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-a")))) + + ops := store.Ops() + require.Len(t, ops, 3) + require.Len(t, ops[1].Keys, 1) + privateProductKey := ops[1].Keys[0] + // The declaration moved the Product entry out of the public keyspace the + // undeclared chain writes it into. + assert.NotEqual(t, "v1:0:f9ab765f03bb381a", privateProductKey) + assert.Equal(t, []cachetesting.StoreOp{ + // The User fetch: undeclared, so it keeps the subgraph's public key. + { + Kind: "GetMany", + Keys: []string{"v1:0:ae7bd989bf833fe9"}, + Hits: []bool{false}, + }, + // The Product fetch: partitioned by the hook's identity. + { + Kind: "GetMany", + Keys: []string{privateProductKey}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:0:ae7bd989bf833fe9", + Value: `{"data":{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:0", + "type:0:User", + "entity:0:User:19ce389448be3351", // id "u1" + }, + }, + { + Key: privateProductKey, + Value: `{"data":{"__typename":"Product","name":"Table"},"cc":{"ttl":30,"created":-1,"scope":"private"}}`, + TTL: 30 * time.Second, + // The partition lives in the key alone, so a purge of the + // product clears every requester's copy. + Tags: []string{ + "subgraph:0", + "type:0:Product", + "entity:0:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + + // A second requester hits the shared User entry and misses the Product + // one, which belongs to user-a alone. + store.ResetOps() + assert.Equal(t, expected, Execute(t, executionEngine, query, controller, + engine.WithPrivatePartitionProvider(requesterIdentity("user-b")))) + ops = store.Ops() + require.Len(t, ops, 3) + require.Len(t, ops[1].Keys, 1) + assert.NotEqual(t, privateProductKey, ops[1].Keys[0]) + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:0:ae7bd989bf833fe9"}, + Hits: []bool{true}, + }, + { + Kind: "GetMany", + Keys: []string{ops[1].Keys[0]}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: ops[1].Keys[0], + Value: `{"data":{"__typename":"Product","name":"Table"},"cc":{"ttl":30,"created":-1,"scope":"private"}}`, + TTL: 30 * time.Second, + Tags: []string{ + "subgraph:0", + "type:0:Product", + "entity:0:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(ops)) + }) + + t.Run("a response max-age still beats the declaration", func(t *testing.T) { + store := cachetesting.NewFakeStore() + controller := cachetesting.NewRealishCache(store, nil) + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "inventory": { + DefaultTTL: ptr(5 * time.Minute), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 90 * time.Second}, + }, + }, + }, + } + users := Respond(`{"data":{"me":{"__typename":"User","id":"u1"}}}`) + products := Respond(`{"data":{"_entities":[{"__typename":"User","favoriteProduct":{"__typename":"Product","upc":"1"}}]}}`) + inventory := RespondCacheControl(`{"data":{"_entities":[{"__typename":"Product","stock":5}]}}`, "max-age=60") + executionEngine := NewEngine(t, caching, Subgraphs{"users": users, "products": products, "inventory": inventory}) + + body := Execute(t, executionEngine, `{ me { favoriteProduct { upc stock } } }`, controller) + assert.Equal(t, `{"data":{"me":{"favoriteProduct":{"upc":"1","stock":5}}}}`, body) + + // The declaration only replaces the STATIC tier; the runtime truth on the + // wire wins over it exactly as it wins over a subgraph DefaultTTL. + assert.Equal(t, []cachetesting.StoreOp{ + { + Kind: "GetMany", + Keys: []string{"v1:1:4f796e3bbd360fce"}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []cachetesting.StoreOpItem{ + { + Key: "v1:1:4f796e3bbd360fce", + Value: `{"data":{"__typename":"Product","stock":5},"cc":{"ttl":60,"created":-1,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:1", + "type:1:Product", + "entity:1:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, NormalizeStoreOpsClock(store.Ops())) + }) +} diff --git a/execution/engine/engine_caching_config_test.go b/execution/engine/engine_caching_config_test.go new file mode 100644 index 0000000000..6f3748ffa0 --- /dev/null +++ b/execution/engine/engine_caching_config_test.go @@ -0,0 +1,104 @@ +package engine + +import ( + "context" + "net/http" + "testing" + "time" + + "github.com/jensneuse/abstractlogger" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/datasource/graphql_datasource" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +func newCachingTestConfiguration(t *testing.T) Configuration { + t.Helper() + + schema := heroWithArgumentSchema(t) + engineConf := NewConfiguration(schema) + engineConf.SetDataSources([]plan.DataSource{ + mustGraphqlDataSourceConfiguration(t, + "heroes-ds", + mustFactory(t, http.DefaultClient), + &plan.DataSourceMetadata{ + RootNodes: []plan.TypeField{ + {TypeName: "Query", FieldNames: []string{"hero", "heroDefault", "heroDefaultRequired", "heroes"}}, + }, + }, + mustConfiguration(t, graphql_datasource.ConfigurationInput{ + Fetch: &graphql_datasource.FetchConfiguration{ + URL: "http://localhost:8080/graphql", + Method: "POST", + }, + SchemaConfiguration: mustSchemaConfig(t, nil, ` + type Query { + hero(name: String): String + heroDefault(name: String = "Any"): String + heroDefaultRequired(name: String! = "AnyRequired"): String + heroes(names: [String!]!): [String!] + }`), + }), + ), + }) + return engineConf +} + +// TestSetCachingWiring pins the engine entry point: SetCaching (its subgraph +// overrides keyed by datasource ID) reaches the planner's caching +// configuration, force-enables FetchInfo, and produces the postprocess +// EnableCaching option; without SetCaching none of that is constructed. +func TestSetCachingWiring(t *testing.T) { + t.Run("without SetCaching nothing is wired", func(t *testing.T) { + engineConf := newCachingTestConfiguration(t) + engine, err := NewExecutionEngine(context.Background(), abstractlogger.Noop{}, engineConf, resolve.ResolverOptions{MaxConcurrency: 1}) + require.NoError(t, err) + assert.Nil(t, engine.config.plannerConfig.Caching) + assert.Nil(t, engine.postProcessorOptions) + }) + + t.Run("SetCaching wires the planner configuration, FetchInfo, and the postprocess option", func(t *testing.T) { + engineConf := newCachingTestConfiguration(t) + engineConf.plannerConfig.DisableIncludeInfo = true // must be force-overridden by caching + ttl := time.Minute + engineConf.SetCaching(cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{DefaultTTL: 30 * time.Second}, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "heroes-ds": { + DefaultTTL: &ttl, + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "hero", TTL: time.Minute}, + }, + }, + }, + }) + engine, err := NewExecutionEngine(context.Background(), abstractlogger.Noop{}, engineConf, resolve.ResolverOptions{MaxConcurrency: 1}) + require.NoError(t, err) + + caching := engine.config.plannerConfig.Caching + require.NotNil(t, caching) + assert.Equal(t, cacheconfig.EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "hero", TTL: time.Minute}, + }, + }, caching.Resolve("heroes-ds")) + + assert.False(t, engine.config.plannerConfig.DisableIncludeInfo) + assert.Len(t, engine.postProcessorOptions, 1) + }) + + t.Run("SetCaching for an unknown datasource id fails", func(t *testing.T) { + engineConf := newCachingTestConfiguration(t) + engineConf.SetCaching(cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{"no-such-ds": {}}, + }) + _, err := NewExecutionEngine(context.Background(), abstractlogger.Noop{}, engineConf, resolve.ResolverOptions{MaxConcurrency: 1}) + assert.EqualError(t, err, "caching configured for unknown datasource id: no-such-ds") + }) +} diff --git a/execution/engine/engine_config.go b/execution/engine/engine_config.go index 67a38039b7..f3046f2402 100644 --- a/execution/engine/engine_config.go +++ b/execution/engine/engine_config.go @@ -11,6 +11,7 @@ import ( "github.com/wundergraph/graphql-go-tools/v2/pkg/ast" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/datasource/graphql_datasource" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" ) @@ -22,6 +23,11 @@ type Configuration struct { schema *graphql.Schema plannerConfig plan.Configuration websocketBeforeStartHook WebsocketBeforeStartHook + + // caching holds the declarative caching configuration cascade (see + // SetCaching); nil means caching was never configured. NewExecutionEngine + // hands it to the planner and to the postprocess EnableCaching option. + caching *cacheconfig.CachingConfiguration } func NewConfiguration(schema *graphql.Schema) Configuration { @@ -59,10 +65,28 @@ func (e *Configuration) SetFieldConfigurations(fieldConfigs plan.FieldConfigurat e.plannerConfig.Fields = fieldConfigs } +// SetCaching configures caching: global defaults plus per-subgraph overrides +// keyed by DATASOURCE ID (the same ID the datasource was created with; +// configuration is matched to fetches via FetchInfo.DataSourceID at plan +// time). It is the ONLY public entry point for caching: NewExecutionEngine +// wires the planner's provides-data walk and the postprocess caching passes +// from it. Not calling it keeps caching fully disabled (the planner no-op +// gate). +func (e *Configuration) SetCaching(caching cacheconfig.CachingConfiguration) { + e.caching = &caching +} + func (e *Configuration) DataSources() []plan.DataSource { return e.plannerConfig.DataSources } +// PlannerConfig returns the built planner configuration. It exists for test +// harnesses that drive the real v2 planner directly from a composed router +// config; production code goes through NewExecutionEngine. +func (e *Configuration) PlannerConfig() plan.Configuration { + return e.plannerConfig +} + func (e *Configuration) FieldConfigurations() plan.FieldConfigurations { return e.plannerConfig.Fields } diff --git a/execution/engine/execution_engine.go b/execution/engine/execution_engine.go index ed64b4858f..dcd3bc559f 100644 --- a/execution/engine/execution_engine.go +++ b/execution/engine/execution_engine.go @@ -30,12 +30,15 @@ import ( type internalExecutionContext struct { resolveContext *resolve.Context postProcessor *postprocess.Processor + // cacheResponseInfo, when set, receives this execution's client cache + // answer once resolution has completed (see WithCacheResponseInfo). + cacheResponseInfo *resolve.CacheResponseInfo } -func newInternalExecutionContext() *internalExecutionContext { +func newInternalExecutionContext(postProcessorOptions ...postprocess.ProcessorOption) *internalExecutionContext { return &internalExecutionContext{ resolveContext: resolve.NewContext(context.Background()), - postProcessor: postprocess.NewProcessor(), + postProcessor: postprocess.NewProcessor(postProcessorOptions...), } } @@ -60,6 +63,9 @@ type ExecutionEngine struct { executionPlanCache *lru.Cache apolloCompatibilityFlags apollocompatibility.Flags validationOptions []astvalidation.Option + // postProcessorOptions carry the caching wiring (postprocess.EnableCaching) + // into every per-execution postprocess.Processor; empty when caching is off. + postProcessorOptions []postprocess.ProcessorOption } type WebsocketBeforeStartHook interface { @@ -101,6 +107,56 @@ func WithRequestTraceOptions(options resolve.TraceOptions) ExecutionOptions { } } +// WithCacheController attaches the runtime cache controller for this +// execution — the counterpart of Configuration.SetCaching (which wires the +// PLAN side): the controller serves and populates the request's L1/L2 caches. +// Without it a cache-configured plan simply fetches everything (the runtime +// no-op). +func WithCacheController(controller resolve.CacheController) ExecutionOptions { + return func(ctx *internalExecutionContext) { + ctx.resolveContext.SetCacheController(controller) + } +} + +// WithCacheResponseInfo captures this execution's client cache answer — the +// freshness and privacy the response may be kept under, plus the invalidation +// tags of the entries it was built from — into dst once resolution completes. +// It is where an embedder turns caching into response headers; without a cache +// controller, or with client emission switched off, dst stays the zero value +// (emit nothing). +func WithCacheResponseInfo(dst *resolve.CacheResponseInfo) ExecutionOptions { + return func(ctx *internalExecutionContext) { + ctx.cacheResponseInfo = dst + } +} + +// WithPrivatePartitionProvider supplies the requester identity that private +// cache entries are partitioned by. Without it, private entries can only be +// partitioned where the caching configuration keys a subgraph by its forwarded +// headers — and a private fetch with neither identity source skips the store. +func WithPrivatePartitionProvider(provider resolve.PrivatePartitionProvider) ExecutionOptions { + return func(ctx *internalExecutionContext) { + ctx.resolveContext.SetPrivatePartitionProvider(provider) + } +} + +// WithSubgraphHeadersBuilder defines the headers (and their hash) the engine +// sends per subgraph. The hash also feeds the cache: it varies public entries +// by header and identifies the requester of private ones. +func WithSubgraphHeadersBuilder(builder resolve.SubgraphHeadersBuilder) ExecutionOptions { + return func(ctx *internalExecutionContext) { + ctx.resolveContext.SubgraphHeadersBuilder = builder + } +} + +// WithIncludeQueryPlanInResponse includes the fetch tree's QueryPlan in the +// response extensions. +func WithIncludeQueryPlanInResponse() ExecutionOptions { + return func(ctx *internalExecutionContext) { + ctx.resolveContext.ExecutionOptions.IncludeQueryPlanInResponse = true + } +} + func NewExecutionEngine(ctx context.Context, logger abstractlogger.Logger, engineConfig Configuration, resolverOptions resolve.ResolverOptions) (*ExecutionEngine, error) { executionPlanCache, err := lru.New(1024) if err != nil { @@ -128,6 +184,21 @@ func NewExecutionEngine(ctx context.Context, logger abstractlogger.Logger, engin dsIDs[ds.Id()] = struct{}{} } + var postProcessorOptions []postprocess.ProcessorOption + if engineConfig.caching != nil { + for id := range engineConfig.caching.Subgraphs { + if _, ok := dsIDs[id]; !ok { + return nil, fmt.Errorf("caching configured for unknown datasource id: %s", id) + } + } + engineConfig.plannerConfig.Caching = engineConfig.caching + // Caching requires FetchInfo: the configuration is matched to fetches + // via FetchInfo.DataSourceID, so a DisableIncludeInfo + caching + // combination must never degrade to silent uncached behavior. + engineConfig.plannerConfig.DisableIncludeInfo = false + postProcessorOptions = append(postProcessorOptions, postprocess.EnableCaching(engineConfig.caching)) + } + var validationOpts []astvalidation.Option if engineConfig.plannerConfig.RelaxSubgraphOperationFieldSelectionMergingNullability { validationOpts = append(validationOpts, astvalidation.WithRelaxFieldSelectionMergingNullability()) @@ -141,7 +212,8 @@ func NewExecutionEngine(ctx context.Context, logger abstractlogger.Logger, engin apolloCompatibilityFlags: apollocompatibility.Flags{ ReplaceInvalidVarError: resolverOptions.ResolvableOptions.ApolloCompatibilityReplaceInvalidVarError, }, - validationOptions: validationOpts, + validationOptions: validationOpts, + postProcessorOptions: postProcessorOptions, }, nil } @@ -213,7 +285,7 @@ func (e *ExecutionEngine) Execute(ctx context.Context, operation *graphql.Reques } } - execContext := newInternalExecutionContext() + execContext := newInternalExecutionContext(e.postProcessorOptions...) execContext.setContext(ctx) execContext.setVariables(operation.Variables) execContext.setRequest(operation.InternalRequest()) @@ -223,6 +295,14 @@ func (e *ExecutionEngine) Execute(ctx context.Context, operation *graphql.Reques options[i](execContext) } + if execContext.cacheResponseInfo != nil { + // Deferred so it runs after resolution — including the resolver's own + // deferred cache-request end — whichever plan kind executes below. + defer func() { + *execContext.cacheResponseInfo = execContext.resolveContext.CacheResponseInfo() + }() + } + if execContext.resolveContext.TracingOptions.Enable { traceCtx := resolve.SetTraceStart(execContext.resolveContext.Context(), execContext.resolveContext.TracingOptions.EnablePredictableDebugTimings) execContext.setContext(traceCtx) diff --git a/execution/engine/testdata/complex_nesting_query_with_art.json b/execution/engine/testdata/complex_nesting_query_with_art.json index d0b79acab3..97ab440ce4 100644 --- a/execution/engine/testdata/complex_nesting_query_with_art.json +++ b/execution/engine/testdata/complex_nesting_query_with_art.json @@ -166,69 +166,9 @@ } } }, - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "duration_load_nanoseconds": 1, - "duration_load_pretty": "1ns", "single_flight_used": true, "single_flight_shared_response": false, - "load_skipped": false, - "load_stats": { - "get_conn": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "host_port": "" - }, - "got_conn": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "reused": false, - "was_idle": false, - "idle_time_nanoseconds": 0, - "idle_time_pretty": "" - }, - "got_first_response_byte": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - }, - "dns_start": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "", - "host": "" - }, - "dns_done": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "connect_start": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "network": "", - "addr": "" - }, - "connect_done": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "network": "", - "addr": "" - }, - "tls_handshake_start": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "tls_handshake_done": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "wrote_headers": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - }, - "wrote_request": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - } - } + "load_skipped": false } } }, @@ -306,69 +246,9 @@ } } }, - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "duration_load_nanoseconds": 1, - "duration_load_pretty": "1ns", "single_flight_used": true, "single_flight_shared_response": false, - "load_skipped": false, - "load_stats": { - "get_conn": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "host_port": "" - }, - "got_conn": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "reused": false, - "was_idle": false, - "idle_time_nanoseconds": 0, - "idle_time_pretty": "" - }, - "got_first_response_byte": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - }, - "dns_start": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "", - "host": "" - }, - "dns_done": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "connect_start": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "network": "", - "addr": "" - }, - "connect_done": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "network": "", - "addr": "" - }, - "tls_handshake_start": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "tls_handshake_done": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "wrote_headers": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - }, - "wrote_request": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - } - } + "load_skipped": false } } }, @@ -492,69 +372,9 @@ } } }, - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "duration_load_nanoseconds": 1, - "duration_load_pretty": "1ns", "single_flight_used": true, "single_flight_shared_response": false, - "load_skipped": false, - "load_stats": { - "get_conn": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "host_port": "" - }, - "got_conn": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "reused": false, - "was_idle": false, - "idle_time_nanoseconds": 0, - "idle_time_pretty": "" - }, - "got_first_response_byte": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - }, - "dns_start": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "", - "host": "" - }, - "dns_done": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "connect_start": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "network": "", - "addr": "" - }, - "connect_done": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns", - "network": "", - "addr": "" - }, - "tls_handshake_start": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "tls_handshake_done": { - "duration_since_start_nanoseconds": 0, - "duration_since_start_pretty": "" - }, - "wrote_headers": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - }, - "wrote_request": { - "duration_since_start_nanoseconds": 1, - "duration_since_start_pretty": "1ns" - } - } + "load_skipped": false } } } diff --git a/execution/federationtesting/gateway/httphandler/http.go b/execution/federationtesting/gateway/httphandler/http.go index 9483e322b0..949a94ac34 100644 --- a/execution/federationtesting/gateway/httphandler/http.go +++ b/execution/federationtesting/gateway/httphandler/http.go @@ -31,12 +31,14 @@ func (g *GraphQLHTTPRequestHandler) handleHTTP(w http.ResponseWriter, r *http.Re if g.enableART { tracingOpts := resolve.TraceOptions{ - Enable: true, - ExcludePlannerStats: false, - ExcludeRawInputData: false, - ExcludeInput: false, - ExcludeOutput: false, - ExcludeLoadStats: false, + Enable: true, + ExcludePlannerStats: false, + ExcludeRawInputData: false, + ExcludeInput: false, + ExcludeOutput: false, + // Load stats are connection-timing noise that only bloats the ART + // golden files — the tests never assert on them. + ExcludeLoadStats: true, EnablePredictableDebugTimings: true, Debug: true, IncludeTraceOutputInResponseExtensions: true, diff --git a/v2/pkg/engine/cache/cache_control.go b/v2/pkg/engine/cache/cache_control.go new file mode 100644 index 0000000000..f4d34b3261 --- /dev/null +++ b/v2/pkg/engine/cache/cache_control.go @@ -0,0 +1,180 @@ +package cache + +import ( + "net/http" + "strconv" + "strings" + "time" +) + +// The runtime tier of cache control: a subgraph's `Cache-Control` RESPONSE +// header decides an entry's lifetime, its storability, and whether the result +// may be shared at all. Static configuration is the fallback that applies only +// when the header is silent. + +// responseCacheControl is what one subgraph response's `Cache-Control` header +// says, reduced to the directives the cache acts on. +type responseCacheControl struct { + // MaxAge is the lifetime the origin declared; meaningful only with HasMaxAge. + MaxAge time.Duration + // HasMaxAge marks a well-formed max-age directive. A max-age of ZERO is + // well-formed and means "do not keep this"; a MALFORMED one leaves this + // false, so the static tier decides instead. + HasMaxAge bool + // NoStore forbids keeping the result in any layer. It is also set by + // `no-cache`: honoring `no-cache` means revalidating before every serve, and + // this cache cannot revalidate, so the conservative reading is not to store. + NoStore bool + // Private marks a result that belongs to one requester only. + Private bool +} + +// parseResponseCacheControl reads the recognized directives — `max-age`, +// `no-store`, `no-cache`, `private` — out of every `Cache-Control` line of a +// subgraph response; everything else, `s-maxage` included, is skipped. The +// parse never fails: a malformed directive is dropped so the static tier +// decides. Names are case-insensitive with whitespace ignored (RFC 9111 §5.2), +// values may be quoted, the FIRST well-formed max-age wins, and the +// storability directives are sticky. +func parseResponseCacheControl(header http.Header) responseCacheControl { + var cc responseCacheControl + for _, line := range header.Values("Cache-Control") { + for rest := line; rest != ""; { + var directive string + directive, rest, _ = strings.Cut(rest, ",") + name, value, hasValue := strings.Cut(directive, "=") + switch strings.ToLower(strings.TrimSpace(name)) { + case "no-store", "no-cache": + cc.NoStore = true + case "private": + cc.Private = true + case "max-age": + if !hasValue || cc.HasMaxAge { + continue + } + seconds, err := strconv.Atoi(strings.Trim(strings.TrimSpace(value), `"`)) + if err != nil || seconds < 0 { + continue + } + cc.MaxAge = time.Duration(seconds) * time.Second + cc.HasMaxAge = true + } + } + } + return cc +} + +// The reasons private data never reached the store, as passed to +// resolve.CacheObserver.OnUncacheablePrivate. Each names its own remedy. +const ( + // UncacheablePrivateResponseHeader: a statically-public fetch was answered + // with `Cache-Control: private` — declare the scope statically to cache it + // partitioned. + UncacheablePrivateResponseHeader = "response-private" + // UncacheablePrivateNoIdentity: a statically-private fetch ran without a + // requester identity — supply a PrivatePartitionProvider, or key the + // subgraph by its forwarded headers. + UncacheablePrivateNoIdentity = "no-identity" +) + +// cachingInput is the STATIC side of the storability ladder: the layers the +// fetch is configured for and the TTLs configuration contributes. StaticTTL is +// the seam for narrower static tiers (a per-type declaration): today it always +// carries the effective subgraph — or, for root fields, coordinate — value. +type cachingInput struct { + L1 bool + L2 bool + // Private marks a STATICALLY private fetch: its store keys already carry the + // requester's partition segment, so a `private` response header only + // CONFIRMS what the configuration declared and changes nothing. + Private bool + StaticTTL time.Duration + NegativeTTL time.Duration + MaxTTL time.Duration +} + +// cachingDecision is the ONE storability answer for one fetch RESULT: which +// layers may be written and under which lifetimes. A zero TTL means "no store +// write" for that kind of entry, so call sites gate on the TTLs alone. +type cachingDecision struct { + // L1 permits request-lifetime writes. Only `no-store` clears it — L1 is + // request-scoped, so a merely-zero TTL does not affect it. + L1 bool + // TTL is the store lifetime of a fetched VALUE; 0 = do not store. + TTL time.Duration + // NegativeTTL is the store lifetime of the empty-entity SENTINEL; 0 = do not + // store. It never derives from max-age: an origin declaring how long a value + // stays fresh says nothing about how long an entity stays nonexistent. + NegativeTTL time.Duration + // UncacheablePrivate marks a statically-public fetch the origin answered with + // `private`: the store writes are dropped and one observability hint is owed. + UncacheablePrivate bool + // Private marks a result that belongs to ONE requester, whichever side said + // so — the static declaration or the response header. It is what the client + // cache answer reads; the key derivation reads Scope, which only the STATIC + // declaration moves. A result that may not be stored at all reports false: + // no-store already forbids every form of sharing. + Private bool + // Scope is the privacy scope the permitted writes record, so a later read + // through the other scope's key derivation can discard them. Empty when the + // result may not be stored at all. + Scope string +} + +// resolveCaching runs the two-tier ladder for one fetch RESULT: +// +// no-store / no-cache -> nothing is written, in EITHER layer +// header max-age -> the entry TTL (the runtime truth) +// else -> the static TTL (configuration cascade) +// resolved TTL <= 0 -> no store write (L1 is unaffected) +// MaxTTL, when set -> clamps whichever tier won +// +// The empty-entity sentinel takes the same storability gates but always the +// configured NegativeTTL as its lifetime. A runtime-only `private` — one the +// static configuration did not declare — keeps L1 and drops both store writes; +// statically-private fetches write into the requester's partition as usual. +// ONE Cache-Control header governs a whole batch response, so the resolved TTL +// applies to every entity entry written from it. +func resolveCaching(cc responseCacheControl, in cachingInput) cachingDecision { + if cc.NoStore { + return cachingDecision{} + } + decision := cachingDecision{ + L1: in.L1, + // A fetch that does not participate in the store never writes one, and a + // private answer to a statically-public fetch must not either. + UncacheablePrivate: cc.Private && in.L2 && !in.Private, + Private: cc.Private || in.Private, + Scope: entryScope(in.Private), + } + if !in.L2 || decision.UncacheablePrivate { + return decision + } + ttl := in.StaticTTL + if cc.HasMaxAge { + ttl = cc.MaxAge + } + decision.TTL = clampTTL(ttl, in.MaxTTL) + decision.NegativeTTL = clampTTL(in.NegativeTTL, in.MaxTTL) + return decision +} + +// entryScope names the scope a fetch's entries are written under. +func entryScope(private bool) string { + if private { + return cacheScopePrivate + } + return cacheScopePublic +} + +// clampTTL caps a resolved TTL at maxTTL, which is unset at 0, and normalizes +// every non-positive result to 0 — the single "do not store" value. +func clampTTL(ttl, maxTTL time.Duration) time.Duration { + if ttl <= 0 { + return 0 + } + if maxTTL > 0 && ttl > maxTTL { + return maxTTL + } + return ttl +} diff --git a/v2/pkg/engine/cache/cache_control_test.go b/v2/pkg/engine/cache/cache_control_test.go new file mode 100644 index 0000000000..aa5ef92350 --- /dev/null +++ b/v2/pkg/engine/cache/cache_control_test.go @@ -0,0 +1,285 @@ +package cache + +import ( + "net/http" + "testing" + "time" + + "github.com/stretchr/testify/assert" +) + +// TestParseResponseCacheControl pins the response-header parser: which +// directives are recognized, how tolerant the syntax handling is, and that a +// malformed value degrades to "silent" instead of to an error. +func TestParseResponseCacheControl(t *testing.T) { + rows := []struct { + name string + // header is the full response header the parser reads. + header http.Header + want responseCacheControl + }{ + { + name: "a nil header says nothing", + header: nil, + want: responseCacheControl{}, + }, + { + name: "a header without Cache-Control says nothing", + header: http.Header{"Content-Type": []string{"application/json"}}, + want: responseCacheControl{}, + }, + { + name: "max-age carries the lifetime", + header: http.Header{"Cache-Control": []string{"max-age=60"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "directive names are case-insensitive", + header: http.Header{"Cache-Control": []string{"MAX-AGE=60"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "whitespace around the name and the value is ignored", + header: http.Header{"Cache-Control": []string{" max-age = 60 "}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "a quoted value is unwrapped", + header: http.Header{"Cache-Control": []string{`max-age="60"`}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "max-age zero is well-formed and means do not keep this", + header: http.Header{"Cache-Control": []string{"max-age=0"}}, + want: responseCacheControl{MaxAge: 0, HasMaxAge: true}, + }, + { + name: "a non-numeric max-age is dropped", + header: http.Header{"Cache-Control": []string{"max-age=soon"}}, + want: responseCacheControl{}, + }, + { + name: "a fractional max-age is dropped", + header: http.Header{"Cache-Control": []string{"max-age=1.5"}}, + want: responseCacheControl{}, + }, + { + name: "a negative max-age is dropped", + header: http.Header{"Cache-Control": []string{"max-age=-5"}}, + want: responseCacheControl{}, + }, + { + name: "an empty max-age value is dropped", + header: http.Header{"Cache-Control": []string{"max-age="}}, + want: responseCacheControl{}, + }, + { + name: "a valueless max-age is dropped", + header: http.Header{"Cache-Control": []string{"max-age"}}, + want: responseCacheControl{}, + }, + { + name: "s-maxage is deliberately ignored and never read as max-age", + header: http.Header{"Cache-Control": []string{"s-maxage=60"}}, + want: responseCacheControl{}, + }, + { + name: "s-maxage alongside max-age leaves max-age in charge", + header: http.Header{"Cache-Control": []string{"s-maxage=600, max-age=30"}}, + want: responseCacheControl{MaxAge: 30 * time.Second, HasMaxAge: true}, + }, + { + name: "no-store forbids storing", + header: http.Header{"Cache-Control": []string{"no-store"}}, + want: responseCacheControl{NoStore: true}, + }, + { + name: "no-cache is read as no-store: this cache cannot revalidate", + header: http.Header{"Cache-Control": []string{"no-cache"}}, + want: responseCacheControl{NoStore: true}, + }, + { + name: "no-store wins over a max-age on the same line", + header: http.Header{"Cache-Control": []string{"max-age=60, no-store"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true, NoStore: true}, + }, + { + name: "private marks a requester-specific result", + header: http.Header{"Cache-Control": []string{"private, max-age=60"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true, Private: true}, + }, + { + name: "public is accepted and changes nothing", + header: http.Header{"Cache-Control": []string{"public, max-age=60"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "unknown directives are skipped", + header: http.Header{"Cache-Control": []string{"stale-while-revalidate=30, immutable, max-age=60"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "the first well-formed max-age wins over a later duplicate", + header: http.Header{"Cache-Control": []string{"max-age=60, max-age=120"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "a leading malformed max-age does not block a later well-formed one", + header: http.Header{"Cache-Control": []string{"max-age=soon, max-age=120"}}, + want: responseCacheControl{MaxAge: 2 * time.Minute, HasMaxAge: true}, + }, + { + name: "empty directives from stray commas are skipped", + header: http.Header{"Cache-Control": []string{",, max-age=60 ,,"}}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + }, + { + name: "directives spread over several header lines all count", + header: http.Header{"Cache-Control": []string{ + "max-age=60", + "private", + }}, + want: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true, Private: true}, + }, + { + name: "every recognized directive at once", + header: http.Header{"Cache-Control": []string{"no-store, no-cache, private, public, max-age=10"}}, + want: responseCacheControl{MaxAge: 10 * time.Second, HasMaxAge: true, NoStore: true, Private: true}, + }, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + assert.Equal(t, row.want, parseResponseCacheControl(row.header)) + }) + } +} + +// TestResolveCaching pins the two-tier storability ladder: header over static, +// the MaxTTL clamp over both, the no-store kill of BOTH layers, and the +// runtime-private store veto that leaves the request-lifetime layer alone. +func TestResolveCaching(t *testing.T) { + rows := []struct { + name string + cc responseCacheControl + in cachingInput + want cachingDecision + }{ + { + name: "no header falls through to the static tier", + cc: responseCacheControl{}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute}, + want: cachingDecision{L1: true, TTL: time.Minute, Scope: cacheScopePublic}, + }, + { + name: "header max-age beats the static tier", + cc: responseCacheControl{MaxAge: 2 * time.Minute, HasMaxAge: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute}, + want: cachingDecision{L1: true, TTL: 2 * time.Minute, Scope: cacheScopePublic}, + }, + { + name: "header max-age of zero stops the store write but keeps L1", + cc: responseCacheControl{MaxAge: 0, HasMaxAge: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute}, + want: cachingDecision{L1: true, TTL: 0, Scope: cacheScopePublic}, + }, + { + name: "a static TTL of zero stops the store write but keeps L1", + cc: responseCacheControl{}, + in: cachingInput{L1: true, L2: true, StaticTTL: 0}, + want: cachingDecision{L1: true, TTL: 0, Scope: cacheScopePublic}, + }, + { + name: "header max-age enables a store write the static tier alone would not", + cc: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: 0, NegativeTTL: 5 * time.Second}, + want: cachingDecision{L1: true, TTL: time.Minute, NegativeTTL: 5 * time.Second, Scope: cacheScopePublic}, + }, + { + name: "no-store clears both layers, TTLs and all", + cc: responseCacheControl{NoStore: true, MaxAge: time.Minute, HasMaxAge: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute, NegativeTTL: 5 * time.Second}, + want: cachingDecision{}, + }, + { + name: "MaxTTL clamps the header tier", + cc: responseCacheControl{MaxAge: 10 * time.Minute, HasMaxAge: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute, MaxTTL: time.Minute}, + want: cachingDecision{L1: true, TTL: time.Minute, Scope: cacheScopePublic}, + }, + { + name: "MaxTTL clamps the static tier", + cc: responseCacheControl{}, + in: cachingInput{L1: true, L2: true, StaticTTL: 10 * time.Minute, MaxTTL: time.Minute}, + want: cachingDecision{L1: true, TTL: time.Minute, Scope: cacheScopePublic}, + }, + { + name: "MaxTTL above the winning tier changes nothing", + cc: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: 10 * time.Minute, MaxTTL: time.Hour}, + want: cachingDecision{L1: true, TTL: time.Minute, Scope: cacheScopePublic}, + }, + { + name: "MaxTTL clamps the negative sentinel too", + cc: responseCacheControl{}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute, NegativeTTL: time.Hour, MaxTTL: 30 * time.Second}, + want: cachingDecision{L1: true, TTL: 30 * time.Second, NegativeTTL: 30 * time.Second, Scope: cacheScopePublic}, + }, + { + name: "the sentinel lifetime never comes from max-age", + cc: responseCacheControl{MaxAge: time.Hour, HasMaxAge: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute, NegativeTTL: 5 * time.Second}, + want: cachingDecision{L1: true, TTL: time.Hour, NegativeTTL: 5 * time.Second, Scope: cacheScopePublic}, + }, + { + name: "an L1-only fetch derives no store TTLs and owes no private hint", + cc: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true, Private: true}, + in: cachingInput{L1: true, L2: false, StaticTTL: time.Minute, NegativeTTL: 5 * time.Second}, + want: cachingDecision{L1: true, Private: true, Scope: cacheScopePublic}, + }, + { + name: "a runtime-private result keeps L1, writes nothing, and owes one hint", + cc: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true, Private: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute, NegativeTTL: 5 * time.Second}, + want: cachingDecision{L1: true, UncacheablePrivate: true, Private: true, Scope: cacheScopePublic}, + }, + { + name: "no-store on a private result suppresses the hint along with the layers", + cc: responseCacheControl{NoStore: true, Private: true}, + in: cachingInput{L1: true, L2: true, StaticTTL: time.Minute, NegativeTTL: 5 * time.Second}, + want: cachingDecision{}, + }, + { + // The declared scope already partitions the keys, so the header only + // confirms it: the entries are written, and no hint is owed. + name: "a private header on a statically-private fetch changes nothing", + cc: responseCacheControl{MaxAge: time.Minute, HasMaxAge: true, Private: true}, + in: cachingInput{L1: true, L2: true, Private: true, StaticTTL: 5 * time.Minute, NegativeTTL: 5 * time.Second}, + want: cachingDecision{L1: true, TTL: time.Minute, NegativeTTL: 5 * time.Second, Private: true, Scope: cacheScopePrivate}, + }, + { + name: "a statically-private fetch records the private scope without any header", + cc: responseCacheControl{}, + in: cachingInput{L1: true, L2: true, Private: true, StaticTTL: time.Minute}, + want: cachingDecision{L1: true, TTL: time.Minute, Private: true, Scope: cacheScopePrivate}, + }, + { + // Storability outranks identity: no-store is about keeping the result + // at all, not about whose result it is. + name: "no-store kills a statically-private fetch's writes too", + cc: responseCacheControl{NoStore: true}, + in: cachingInput{L1: true, L2: true, Private: true, StaticTTL: time.Minute, NegativeTTL: 5 * time.Second}, + want: cachingDecision{}, + }, + { + name: "a root-field fetch carries no L1 and resolves its coordinate TTL", + cc: responseCacheControl{}, + in: cachingInput{L1: false, L2: true, StaticTTL: 5 * time.Minute}, + want: cachingDecision{L1: false, TTL: 5 * time.Minute, Scope: cacheScopePublic}, + }, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + assert.Equal(t, row.want, resolveCaching(row.cc, row.in)) + }) + } +} diff --git a/v2/pkg/engine/cache/cache_key_args_test.go b/v2/pkg/engine/cache/cache_key_args_test.go new file mode 100644 index 0000000000..fd7213e05b --- /dev/null +++ b/v2/pkg/engine/cache/cache_key_args_test.go @@ -0,0 +1,299 @@ +package cache + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// argsTemplateFor builds the key template for an "upc"-keyed Product entity +// fetch whose selection is provides, exactly as PrepareFetch does — the +// argument digest included. The selection tree is folded first, like the +// configurator folds every ProvidesData tree it attaches. +func argsTemplateFor(t *testing.T, ctx *resolve.Context, provides *resolve.Object) cacheKeyTemplate { + t.Helper() + resolve.ComputeHasAliases(provides) + template, ok := newCacheKeyTemplate(ctx, &resolve.FetchCacheConfig{ + SubgraphName: "products", + KeySpec: resolve.CacheKeySpec{Scope: resolve.CacheScopeEntity, TypeName: "Product", Representation: productRepresentation(t, "upc")}, + ProvidesData: provides, + }, 0, l2Access{enabled: true}) + require.True(t, ok) + return template +} + +// TestCacheKeyArgsSegment pins the argument segment of the entity key preimage: +// when (and only when) the fetch selects parameterized fields, the argument +// VALUES of the request join the identity of both layers' keys, so argument +// variants become independent entries instead of replacing each other. +func TestCacheKeyArgsSegment(t *testing.T) { + item := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)) + + t.Run("a selection without parameterized fields renders the unchanged preimage", func(t *testing.T) { + keys, ok := argsTemplateFor(t, variableContext(t, `{"days":3}`), &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("stock"), + Value: &resolve.Scalar{Path: []string{"stock"}}, + }, + }, + }).render(item) + require.True(t, ok) + // No empty segment: the preimage is byte-identical to the one a build + // without the argument segment renders. + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + L2: renderCacheKey("v1:products", []byte(`{"__typename":"Product","representation":{"upc":"1"}}`)), + }, keys) + }) + + t.Run("a parameterized field adds the digest to the L1 and the L2 key", func(t *testing.T) { + ctx := variableContext(t, `{"days":3}`) + keys, ok := argsTemplateFor(t, ctx, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("stockHistory"), + CacheArgs: []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}}, + Value: &resolve.Array{Path: []string{"stockHistory"}, Item: &resolve.Scalar{}}, + }, + }, + }).render(item) + require.True(t, ok) + // The digest hashes ONE entry: the field's normalized path, whose last + // segment carries the value-derived argument suffix. + digest := hashHex([]byte("stockHistory" + computeArgSuffix(ctx, []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}}))) + preimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + digest + `"}` + assert.Equal(t, itemKeys{ + L1: "products:" + preimage, + L2: renderCacheKey("v1:products", []byte(preimage)), + }, keys) + // The parameterized selection never shares the arg-less selection's entry. + assert.NotEqual(t, `products:{"__typename":"Product","representation":{"upc":"1"}}`, keys.L1) + }) + + t.Run("a changed argument value is a new entry in both layers", func(t *testing.T) { + // One selection, two requests: only the variable value differs. + provides := &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("stockHistory"), + CacheArgs: []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}}, + Value: &resolve.Array{Path: []string{"stockHistory"}, Item: &resolve.Scalar{}}, + }, + }, + } + ctxThree := variableContext(t, `{"days":3}`) + ctxOne := variableContext(t, `{"days":1}`) + + three, ok := argsTemplateFor(t, ctxThree, provides).render(item) + require.True(t, ok) + one, ok := argsTemplateFor(t, ctxOne, provides).render(item) + require.True(t, ok) + + threePreimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + + hashHex([]byte("stockHistory"+computeArgSuffix(ctxThree, []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}}))) + `"}` + onePreimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + + hashHex([]byte("stockHistory"+computeArgSuffix(ctxOne, []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}}))) + `"}` + assert.Equal(t, itemKeys{ + L1: "products:" + threePreimage, + L2: renderCacheKey("v1:products", []byte(threePreimage)), + }, three) + assert.Equal(t, itemKeys{ + L1: "products:" + onePreimage, + L2: renderCacheKey("v1:products", []byte(onePreimage)), + }, one) + // Both layers split: the in-request L1 must partition by arguments for + // the same reason the store does. + assert.NotEqual(t, three.L1, one.L1) + assert.NotEqual(t, three.L2, one.L2) + }) + + t.Run("the same values under other aliases and variable names key identically", func(t *testing.T) { + // Operation A: the field is aliased and bound to $days. + aliased, ok := argsTemplateFor(t, variableContext(t, `{"days":3}`), &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("history"), + OriginalName: []byte("stockHistory"), + CacheArgs: []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}}, + Value: &resolve.Array{Path: []string{"history"}, Item: &resolve.Scalar{}}, + }, + }, + }).render(item) + require.True(t, ok) + + // Operation B: no alias, and the SAME value arrives under $a. + ctxPlain := variableContext(t, `{"a":3}`) + plain, ok := argsTemplateFor(t, ctxPlain, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("stockHistory"), + CacheArgs: []resolve.CacheFieldArg{{Name: "days", VariableName: "a"}}, + Value: &resolve.Array{Path: []string{"stockHistory"}, Item: &resolve.Scalar{}}, + }, + }, + }).render(item) + require.True(t, ok) + + preimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + + hashHex([]byte("stockHistory"+computeArgSuffix(ctxPlain, []resolve.CacheFieldArg{{Name: "days", VariableName: "a"}}))) + `"}` + assert.Equal(t, itemKeys{ + L1: "products:" + preimage, + L2: renderCacheKey("v1:products", []byte(preimage)), + }, aliased) + assert.Equal(t, aliased, plain) + }) + + t.Run("a nested parameterized field carries its path into the digest", func(t *testing.T) { + ctx := variableContext(t, `{"days":3}`) + args := []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}} + + // The same schema field, selected one level down under warehouse. + nested, ok := argsTemplateFor(t, ctx, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("warehouse"), + Value: &resolve.Object{ + Path: []string{"warehouse"}, + Fields: []*resolve.Field{ + { + Name: []byte("history"), + OriginalName: []byte("stockHistory"), + CacheArgs: args, + Value: &resolve.Array{Path: []string{"history"}, Item: &resolve.Scalar{}}, + }, + }, + }, + }, + }, + }).render(item) + require.True(t, ok) + + top, ok := argsTemplateFor(t, ctx, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("stockHistory"), + CacheArgs: args, + Value: &resolve.Array{Path: []string{"stockHistory"}, Item: &resolve.Scalar{}}, + }, + }, + }).render(item) + require.True(t, ok) + + nestedPreimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + + hashHex([]byte("warehouse.stockHistory"+computeArgSuffix(ctx, args))) + `"}` + topPreimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + + hashHex([]byte("stockHistory"+computeArgSuffix(ctx, args))) + `"}` + assert.Equal(t, itemKeys{ + L1: "products:" + nestedPreimage, + L2: renderCacheKey("v1:products", []byte(nestedPreimage)), + }, nested) + assert.Equal(t, itemKeys{ + L1: "products:" + topPreimage, + L2: renderCacheKey("v1:products", []byte(topPreimage)), + }, top) + assert.NotEqual(t, nested, top) + }) + + t.Run("two variants of one field in a single selection sort into one digest", func(t *testing.T) { + ctx := variableContext(t, `{"a":3,"b":1}`) + daysA := []resolve.CacheFieldArg{{Name: "days", VariableName: "a"}} + daysB := []resolve.CacheFieldArg{{Name: "days", VariableName: "b"}} + + // euro/usd-style multi-variant: both aliases of the SAME field live in + // ONE entry, under their argument-suffixed stored names. + keys, ok := argsTemplateFor(t, ctx, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("recent"), + OriginalName: []byte("stockHistory"), + CacheArgs: daysA, + Value: &resolve.Array{Path: []string{"recent"}, Item: &resolve.Scalar{}}, + }, + { + Name: []byte("yesterday"), + OriginalName: []byte("stockHistory"), + CacheArgs: daysB, + Value: &resolve.Array{Path: []string{"yesterday"}, Item: &resolve.Scalar{}}, + }, + }, + }).render(item) + require.True(t, ok) + + // The digest input is SORTED, so selection order cannot move it: the + // entries are the two suffixed names, comma-joined in sorted order. + entries := []string{ + "stockHistory" + computeArgSuffix(ctx, daysA), + "stockHistory" + computeArgSuffix(ctx, daysB), + } + if entries[0] > entries[1] { + entries[0], entries[1] = entries[1], entries[0] + } + preimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + + hashHex([]byte(entries[0]+","+entries[1])) + `"}` + assert.Equal(t, itemKeys{ + L1: "products:" + preimage, + L2: renderCacheKey("v1:products", []byte(preimage)), + }, keys) + + // A differently-aliased operation selecting the same two variants in the + // opposite order lands on the SAME entry. + swapped, ok := argsTemplateFor(t, ctx, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("old"), + OriginalName: []byte("stockHistory"), + CacheArgs: daysB, + Value: &resolve.Array{Path: []string{"old"}, Item: &resolve.Scalar{}}, + }, + { + Name: []byte("fresh"), + OriginalName: []byte("stockHistory"), + CacheArgs: daysA, + Value: &resolve.Array{Path: []string{"fresh"}, Item: &resolve.Scalar{}}, + }, + }, + }).render(item) + require.True(t, ok) + assert.Equal(t, keys, swapped) + }) + + t.Run("one digest per fetch serves every item of a batch", func(t *testing.T) { + ctx := variableContext(t, `{"days":3}`) + args := []resolve.CacheFieldArg{{Name: "days", VariableName: "days"}} + template := argsTemplateFor(t, ctx, &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("stockHistory"), + CacheArgs: args, + Value: &resolve.Array{Path: []string{"stockHistory"}, Item: &resolve.Scalar{}}, + }, + }, + }) + digest := hashHex([]byte("stockHistory" + computeArgSuffix(ctx, args))) + // The digest is derived ONCE, when the template is built — the per-item + // render only appends it. + assert.Equal(t, digest, template.args) + + first, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`))) + require.True(t, ok) + second, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"2"}`))) + require.True(t, ok) + + firstPreimage := `{"__typename":"Product","representation":{"upc":"1"},"args":"` + digest + `"}` + secondPreimage := `{"__typename":"Product","representation":{"upc":"2"},"args":"` + digest + `"}` + assert.Equal(t, itemKeys{ + L1: "products:" + firstPreimage, + L2: renderCacheKey("v1:products", []byte(firstPreimage)), + }, first) + assert.Equal(t, itemKeys{ + L1: "products:" + secondPreimage, + L2: renderCacheKey("v1:products", []byte(secondPreimage)), + }, second) + }) +} diff --git a/v2/pkg/engine/cache/cache_key_builder.go b/v2/pkg/engine/cache/cache_key_builder.go new file mode 100644 index 0000000000..b1a8bd9a08 --- /dev/null +++ b/v2/pkg/engine/cache/cache_key_builder.go @@ -0,0 +1,73 @@ +package cache + +import ( + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// The key freezer: it turns a finished fetch into the data-only +// resolve.CacheKeySpec the runtime renders keys from. It reads NO federation +// metadata and no schema — an entity fetch's identity is the merged +// representation node the fetch ALREADY sends, so the freezer only has to find +// that node on the fetch and hand it over. + +// buildEntitySpec builds the key spec for an entity fetch: scope, the fetched +// entity type, and the fetch's own merged representation node. Because the key +// renders from the very object the fetch puts on the wire, read key == write +// key == fetch identity, and @requires fields participate in the identity. +// Returns (zero, false) when the fetch resolves no entity or sends no +// representation. +func buildEntitySpec(fetch resolve.Fetch, info *resolve.FetchInfo) (resolve.CacheKeySpec, bool) { + if info == nil || len(info.RootFields) == 0 { + return resolve.CacheKeySpec{}, false + } + node, ok := representationNode(fetch) + if !ok { + return resolve.CacheKeySpec{}, false + } + return resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: info.RootFields[0].TypeName, + Representation: node, + }, true +} + +// buildRootFieldSpec builds the key spec for a root-field fetch: scope plus the +// fetch's first root-field coordinate. Root fields have their own key space +// (coordinate + canonical request variables) and never join the entity one. +func buildRootFieldSpec(info *resolve.FetchInfo) (resolve.CacheKeySpec, bool) { + if info == nil || len(info.RootFields) == 0 { + return resolve.CacheKeySpec{}, false + } + return resolve.CacheKeySpec{ + Scope: resolve.CacheScopeRootField, + TypeName: info.RootFields[0].TypeName, + FieldName: info.RootFields[0].FieldName, + }, true +} + +// representationNode returns the merged representation object the fetch sends, +// read from the ResolvableObjectVariable segment of the fetch's representation +// input template. The node is plan-owned and read-only at runtime, so the spec +// REFERENCES it (intentional identity) instead of copying it. +func representationNode(fetch resolve.Fetch) (*resolve.Object, bool) { + if fetch == nil { + return nil, false + } + template := fetch.RepresentationInputTemplate() + if template == nil { + return nil, false + } + for _, segment := range template.Segments { + if segment.SegmentType != resolve.VariableSegmentType || segment.VariableKind != resolve.ResolvableObjectVariableKind { + continue + } + renderer, ok := segment.Renderer.(*resolve.GraphQLVariableResolveRenderer) + if !ok { + continue + } + if node, ok := renderer.Node.(*resolve.Object); ok { + return node, true + } + } + return nil, false +} diff --git a/v2/pkg/engine/cache/cache_key_builder_test.go b/v2/pkg/engine/cache/cache_key_builder_test.go new file mode 100644 index 0000000000..a6d82239c1 --- /dev/null +++ b/v2/pkg/engine/cache/cache_key_builder_test.go @@ -0,0 +1,306 @@ +package cache + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/ast" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astparser" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/representationvariable" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +const keyBuilderDefinition = ` + scalar String + scalar Int + + type Product { + upc: String! + sku: String! + name: String! + price: Int! + brand: Brand! + } + + type Brand { + id: String! + name: String! + } +` + +func parseKeyBuilderDefinition(t *testing.T) *ast.Document { + t.Helper() + definition, report := astparser.ParseGraphqlDocumentString(keyBuilderDefinition) + require.False(t, report.HasErrors(), "parse definition: %v", report) + return &definition +} + +// productRepresentation builds the merged representation node a Product entity +// fetch sends, through the planner's own pipeline: one node per RequiredFields +// selection set, merged into one. The FIRST selection set is the chosen @key; +// every further one is a @requires set, which the planner marks by naming the +// field carrying the directive. +func productRepresentation(t *testing.T, selectionSets ...string) *resolve.Object { + t.Helper() + configs := make([]plan.FederationFieldConfiguration, 0, len(selectionSets)) + for i, selectionSet := range selectionSets { + config := plan.FederationFieldConfiguration{TypeName: "Product", SelectionSet: selectionSet} + if i > 0 { + config.FieldName = "shippingEstimate" + } + configs = append(configs, config) + } + return mergedRepresentation(t, plan.FederationMetaData{}, configs...) +} + +// mergedRepresentation is productRepresentation for arbitrary types and +// federation metadata, so rows can build the abstract-path (per-concrete-type +// conditioned fields) and @interfaceObject (static __typename) node shapes the +// planner really emits. +func mergedRepresentation(t *testing.T, federation plan.FederationMetaData, configs ...plan.FederationFieldConfiguration) *resolve.Object { + t.Helper() + definition := parseKeyBuilderDefinition(t) + nodes := make([]*resolve.Object, 0, len(configs)) + for _, config := range configs { + // Caching is what the cache-side fixtures exercise, so the nodes carry + // the @key marking the caching planner emits. + node, err := representationvariable.BuildRepresentationVariableNode(definition, config, federation, true) + require.NoError(t, err) + nodes = append(nodes, node) + } + return representationvariable.MergeRepresentationVariableNodes(nodes) +} + +// entityFetchWith wraps a representation node in an EntityFetch exactly as +// createConcreteSingleFetchTypes does: the ResolvableObjectVariable segment +// carrying the node sits in the fetch's item input template. +func entityFetchWith(node *resolve.Object) *resolve.EntityFetch { + return &resolve.EntityFetch{ + Info: productEntityInfo(), + Input: resolve.EntityInput{ + Item: resolve.InputTemplate{ + Segments: []resolve.TemplateSegment{resolve.NewResolvableObjectVariable(node).TemplateSegment()}, + }, + }, + } +} + +// batchEntityFetchWith is entityFetchWith for the batched arm. +func batchEntityFetchWith(node *resolve.Object) *resolve.BatchEntityFetch { + return &resolve.BatchEntityFetch{ + Info: productEntityInfo(), + Input: resolve.BatchInput{ + Items: []resolve.InputTemplate{ + {Segments: []resolve.TemplateSegment{resolve.NewResolvableObjectVariable(node).TemplateSegment()}}, + }, + }, + } +} + +func productEntityInfo() *resolve.FetchInfo { + return &resolve.FetchInfo{ + DataSourceID: "products", + DataSourceName: "products", + RootFields: []resolve.GraphCoordinate{{TypeName: "Product"}}, + } +} + +func TestCacheKeyBuilderEntitySpec(t *testing.T) { + t.Run("single @key: the spec IS the fetch's representation node", func(t *testing.T) { + node := productRepresentation(t, "upc") + fetch := entityFetchWith(node) + spec, ok := buildEntitySpec(fetch, fetch.Info) + require.True(t, ok) + assert.Equal(t, resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{Path: []string{"__typename"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("upc"), + Value: &resolve.String{Path: []string{"upc"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + CacheEntityKeyField: true, + }, + }, + }, + }, spec) + // Intentional identity: the node is plan-owned and read-only at + // runtime, so the spec references it instead of copying it. + assert.Same(t, node, spec.Representation) + }) + + t.Run("a multi-@key type still yields ONE spec: the key set THIS fetch sends", func(t *testing.T) { + // Product declares both @key(upc) and @key(sku); this fetch resolves it + // by sku, so sku alone is its identity — the other @key set is not + // enumerated any more. + node := productRepresentation(t, "sku") + fetch := entityFetchWith(node) + spec, ok := buildEntitySpec(fetch, fetch.Info) + require.True(t, ok) + assert.Equal(t, resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{Path: []string{"__typename"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("sku"), + Value: &resolve.String{Path: []string{"sku"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + CacheEntityKeyField: true, + }, + }, + }, + }, spec) + }) + + t.Run("@requires fields are part of the identity, and marked as not-@key", func(t *testing.T) { + // The planner merges the @key set with every @requires set into ONE + // representation node; the key renders from all of it, while + // CacheEntityKeyField keeps the @key subset the entity tag hashes + // distinguishable inside the merged node. + node := productRepresentation(t, "upc", "price brand { id }") + fetch := entityFetchWith(node) + spec, ok := buildEntitySpec(fetch, fetch.Info) + require.True(t, ok) + assert.Equal(t, resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{Path: []string{"__typename"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("upc"), + Value: &resolve.String{Path: []string{"upc"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + CacheEntityKeyField: true, + }, + { + Name: []byte("price"), + Value: &resolve.Integer{Path: []string{"price"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("brand"), + Value: &resolve.Object{ + Path: []string{"brand"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.String{Path: []string{"id"}}, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + }, + }, spec) + }) + + t.Run("batch entity fetch: the node comes from the per-item template", func(t *testing.T) { + node := productRepresentation(t, "upc") + fetch := batchEntityFetchWith(node) + spec, ok := buildEntitySpec(fetch, fetch.Info) + require.True(t, ok) + assert.Same(t, node, spec.Representation) + assert.Equal(t, resolve.CacheScopeEntity, spec.Scope) + assert.Equal(t, "Product", spec.TypeName) + }) + + t.Run("determinism: two builds of the same fetch produce equal specs", func(t *testing.T) { + fetch := entityFetchWith(productRepresentation(t, "upc", "price")) + first, ok := buildEntitySpec(fetch, fetch.Info) + require.True(t, ok) + second, ok := buildEntitySpec(fetch, fetch.Info) + require.True(t, ok) + assert.True(t, first.Equals(second)) + assert.Equal(t, first, second) + }) + + noSpecRows := []struct { + name string + fetch resolve.Fetch + info *resolve.FetchInfo + }{ + { + name: "a non-entity fetch sends no representation", + fetch: &resolve.SingleFetch{Info: productEntityInfo()}, + info: productEntityInfo(), + }, + { + name: "an entity fetch with an empty input template", + fetch: &resolve.EntityFetch{Info: productEntityInfo()}, + info: productEntityInfo(), + }, + { + name: "a batch entity fetch with no items", + fetch: &resolve.BatchEntityFetch{Info: productEntityInfo()}, + info: productEntityInfo(), + }, + { + name: "nil info", + fetch: entityFetchWith(&resolve.Object{}), + info: nil, + }, + { + name: "info without root fields", + fetch: entityFetchWith(&resolve.Object{}), + info: &resolve.FetchInfo{DataSourceID: "products"}, + }, + { + name: "nil fetch", + fetch: nil, + info: productEntityInfo(), + }, + } + for _, row := range noSpecRows { + t.Run(row.name+" means no spec", func(t *testing.T) { + spec, ok := buildEntitySpec(row.fetch, row.info) + assert.False(t, ok) + assert.Equal(t, resolve.CacheKeySpec{}, spec) + }) + } +} + +func TestCacheKeyBuilderRootFieldSpec(t *testing.T) { + t.Run("scope plus the first root-field coordinate", func(t *testing.T) { + spec, ok := buildRootFieldSpec(&resolve.FetchInfo{ + DataSourceID: "products", + RootFields: []resolve.GraphCoordinate{{TypeName: "Query", FieldName: "products"}}, + }) + require.True(t, ok) + assert.Equal(t, resolve.CacheKeySpec{ + Scope: resolve.CacheScopeRootField, + TypeName: "Query", + FieldName: "products", + }, spec) + }) + + t.Run("nil info and missing root fields mean no spec", func(t *testing.T) { + _, ok := buildRootFieldSpec(nil) + assert.False(t, ok) + _, ok = buildRootFieldSpec(&resolve.FetchInfo{DataSourceID: "products"}) + assert.False(t, ok) + }) +} diff --git a/v2/pkg/engine/cache/cache_key_partition_test.go b/v2/pkg/engine/cache/cache_key_partition_test.go new file mode 100644 index 0000000000..6b5ed049d9 --- /dev/null +++ b/v2/pkg/engine/cache/cache_key_partition_test.go @@ -0,0 +1,174 @@ +package cache + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// partitionTemplate builds the key template of a Product fetch under the given +// privacy/header configuration and store access, exactly as PrepareFetch does. +func partitionTemplate(t *testing.T, private, includeHeaders bool, headerHash uint64, access l2Access) cacheKeyTemplate { + t.Helper() + template, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{ + SubgraphName: "products", + Private: private, + IncludeSubgraphHeaders: includeHeaders, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: productRepresentation(t, "upc"), + }, + }, headerHash, access) + require.True(t, ok) + return template +} + +// TestCacheKeyPartitionMatrix walks scope x identity source x header inclusion +// and pins what each combination puts in the key: a partition segment in the L2 +// preimage, a header hash in the visible prefix, or — for every public fetch — +// neither. +func TestCacheKeyPartitionMatrix(t *testing.T) { + item := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)) + body := `{"__typename":"Product","representation":{"upc":"1"}}` + partition := sha256Hex("i:user-a") + + t.Run("public without header inclusion: the pre-privacy key, byte for byte", func(t *testing.T) { + keys, ok := partitionTemplate(t, false, false, 42, l2Access{enabled: true}).render(item) + require.True(t, ok) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + L2: "v1:products:f5d10aa05957718e", + }, keys) + // The literal above is the derivation spelled out, so a silent change to + // either the preimage or the digest fails this row. + assert.Equal(t, "v1:products:"+hashHex([]byte("v1:products:"+body)), keys.L2) + }) + + t.Run("public with header inclusion: the hash varies the visible prefix", func(t *testing.T) { + keys, ok := partitionTemplate(t, false, true, 42, l2Access{enabled: true}).render(item) + require.True(t, ok) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + L2: "v1:products:h" + hex64(42) + ":" + hashHex([]byte("v1:products:h"+hex64(42)+":"+body)), + }, keys) + }) + + t.Run("private with an identity: the segment joins the L2 preimage only", func(t *testing.T) { + keys, ok := partitionTemplate(t, true, false, 42, l2Access{enabled: true, partition: partition}).render(item) + require.True(t, ok) + assert.Equal(t, itemKeys{ + // The L1 key is the public one: the request-lifetime map is + // per-requester already. + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + L2: "v1:products:" + hashHex([]byte(`v1:products:{"__typename":"Product","representation":{"upc":"1"},"partition":"`+partition+`"}`)), + }, keys) + }) + + t.Run("private with header inclusion: partitioned ONCE, never prefix and segment both", func(t *testing.T) { + template := partitionTemplate(t, true, true, 42, l2Access{enabled: true, partition: partition}) + // The header hash is the IDENTITY here, so it reaches the key through the + // partition segment and leaves the visible prefix plain. + assert.Equal(t, "v1:products", template.prefix) + keys, ok := template.render(item) + require.True(t, ok) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + L2: "v1:products:" + hashHex([]byte(`v1:products:{"__typename":"Product","representation":{"upc":"1"},"partition":"`+partition+`"}`)), + }, keys) + }) + + t.Run("private without store access: L1 only, and the L1 key is unchanged", func(t *testing.T) { + keys, ok := partitionTemplate(t, true, true, 42, l2Access{}).render(item) + require.True(t, ok) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + }, keys) + }) + + t.Run("two identities are two entries, and neither is the public one", func(t *testing.T) { + userA, ok := partitionTemplate(t, true, false, 0, l2Access{enabled: true, partition: sha256Hex("i:user-a")}).render(item) + require.True(t, ok) + userB, ok := partitionTemplate(t, true, false, 0, l2Access{enabled: true, partition: sha256Hex("i:user-b")}).render(item) + require.True(t, ok) + public, ok := partitionTemplate(t, false, false, 0, l2Access{enabled: true}).render(item) + require.True(t, ok) + assert.NotEqual(t, userA.L2, userB.L2) + assert.NotEqual(t, userA.L2, public.L2) + assert.NotEqual(t, userB.L2, public.L2) + // The shared L1 key is exactly what makes the unpartitioned map safe to + // reason about: one request only ever holds ONE of these identities. + assert.Equal(t, userA.L1, userB.L1) + assert.Equal(t, userA.L1, public.L1) + }) +} + +// TestRootFieldCacheKeyPartition pins the root-field arm of the partition +// segment: the same identity trails the coordinate+variables preimage, and a +// public coordinate's key is untouched. +func TestRootFieldCacheKeyPartition(t *testing.T) { + ctx := resolve.NewContext(t.Context()) + ctx.Variables = astjson.MustParseBytes([]byte(`{"first":5}`)) + partition := sha256Hex("i:user-a") + + t.Run("a public coordinate carries no segment", func(t *testing.T) { + cfg := &resolve.FetchCacheConfig{ + SubgraphName: "products", + KeySpec: resolve.CacheKeySpec{Scope: resolve.CacheScopeRootField, TypeName: "Query", FieldName: "topProducts"}, + } + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:Query.topProducts:{"first":5}`)), + rootFieldCacheKey(cfg, 0, ctx, ""), + ) + }) + + t.Run("a private coordinate keys under its requester", func(t *testing.T) { + cfg := &resolve.FetchCacheConfig{ + SubgraphName: "products", + Private: true, + KeySpec: resolve.CacheKeySpec{Scope: resolve.CacheScopeRootField, TypeName: "Query", FieldName: "me"}, + } + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:Query.me:{"first":5},"partition":"`+partition+`"`)), + rootFieldCacheKey(cfg, 0, ctx, partition), + ) + }) + + t.Run("the header hash of a private coordinate stays out of the prefix", func(t *testing.T) { + cfg := &resolve.FetchCacheConfig{ + SubgraphName: "products", + Private: true, + IncludeSubgraphHeaders: true, + KeySpec: resolve.CacheKeySpec{Scope: resolve.CacheScopeRootField, TypeName: "Query", FieldName: "me"}, + } + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:Query.me:{"first":5},"partition":"`+partition+`"`)), + rootFieldCacheKey(cfg, 42, ctx, partition), + ) + }) +} + +// TestPartitionHashing pins how an identity becomes a key segment: sha256 (not +// the 64-bit key hash — a forgeable collision here is a cross-requester leak), +// and each source tagged so one can never be mistaken for the other. +func TestPartitionHashing(t *testing.T) { + t.Run("the segment is the hex sha256 of the tagged identity", func(t *testing.T) { + assert.Equal(t, + "5c10d62d060122fe2e5c2e88d47555725da6e8cc22b609099d3b7e6e07c28bf5", + sha256Hex("i:user-a"), + ) + assert.Len(t, sha256Hex("i:user-a"), 64) + }) + + t.Run("a provider identity spelling a header hash lands in a different partition", func(t *testing.T) { + // The forgery attempt: a provider hands back the exact text the header + // source would produce for header hash 1. + forged := "h:" + hex64(1) + assert.NotEqual(t, sha256Hex("i:"+forged), sha256Hex(forged)) + }) +} diff --git a/v2/pkg/engine/cache/cache_key_template.go b/v2/pkg/engine/cache/cache_key_template.go new file mode 100644 index 0000000000..7d16d6886b --- /dev/null +++ b/v2/pkg/engine/cache/cache_key_template.go @@ -0,0 +1,472 @@ +package cache + +import ( + "cmp" + "crypto/sha256" + "encoding/hex" + "slices" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" + "github.com/wundergraph/graphql-go-tools/v2/pkg/pool" +) + +// cacheFormatVersion leads every L2 key and its preimage: it segments the +// keyspace by STORAGE FORMAT, so changing the key layout or the value envelope +// makes older entries unreachable instead of misreadable. +const cacheFormatVersion = "v1" + +// cacheKeyTemplate is the SOLE source of read, write, and invalidate keys for +// ONE fetch: the same template renders the same byte-identical keys wherever it +// is used, so the read and write key spaces cannot silently diverge. +type cacheKeyTemplate struct { + // subgraph is the fetch's subgraph name: every subgraph owns its keyspace, + // in both layers. + subgraph string + // prefix is the visible L2 key prefix — format version, subgraph, and the + // subgraph header hash when the config varies by headers. It is EMPTY for a + // fetch that does not use L2, which is what keeps an L1-only fetch away + // from prefix material and hashing entirely. + prefix string + // representation is the fetch's merged representation node — the same node + // its input template renders on the wire. + representation *resolve.Object + // args is the digest of the request's argument values for the fetch's + // parameterized fields, EMPTY when the fetch selects none. It is derived + // once per fetch per request (the values come from the variables, the field + // set from the plan) and is the same for every item of a batch. + args string + // partition is the hashed requester identity of a statically-private fetch, + // EMPTY for a public one. It enters the L2 preimage ONLY: the L1 map is + // per-request and therefore per-requester, so partitioning it would only + // fragment it. + partition string +} + +// l2Access is one fetch's per-request store access: whether it may touch the +// store at all, and the partition segment its keys carry when it is private. +// A statically-private fetch whose request carries no identity resolves to a +// disabled access — it must not read from or write to a shared keyspace it +// cannot partition. +type l2Access struct { + enabled bool + partition string +} + +// itemKeys are the two keys one cached item is addressed by, derived from a +// single rendering: +// +// body = {"__typename":T,"representation":{...}[,"args":D] +// L1 = {subgraph}:} (raw preimage) +// L2 = v1:{subgraph}[:h]:<16-hex xxhash64 of ":[,"partition":"P"]}"> +// +// The L1 key is the preimage itself: the map hashes internally, nothing +// persists (no format version needed), and the map is per-requester (no header +// hash and no partition segment needed). L2 is empty when the fetch does not +// use the store. +type itemKeys struct { + L1 string + L2 string +} + +// newCacheKeyTemplate derives the fetch's key template from the config, the +// request's variables, its subgraph header hash, and its resolved store access. +// It runs ONCE per fetch — the argument digest walk is per fetch, never per +// item — and returns ok=false when the config carries no representation node +// (nothing to key on). +func newCacheKeyTemplate(ctx *resolve.Context, cfg *resolve.FetchCacheConfig, headerHash uint64, l2 l2Access) (cacheKeyTemplate, bool) { + if cfg == nil || cfg.KeySpec.Representation == nil { + return cacheKeyTemplate{}, false + } + template := cacheKeyTemplate{ + subgraph: cfg.SubgraphName, + representation: cfg.KeySpec.Representation, + args: argsDigest(ctx, cfg.ProvidesData), + } + if l2.enabled { + template.prefix = cacheKeyPrefix(cfg, headerHash) + template.partition = l2.partition + } + return template, true +} + +// render derives the item's keys from ONE canonical representation rendering: +// the L1 key is that preimage body closed as it stands, the L2 key the +// versioned, hashed derivation over the same body plus the partition segment. +// ok=false when a referenced field is absent or null in the item — the same +// condition under which the fetch input itself could not render, so an +// unrenderable key means a miss with no write, never an error. +func (t cacheKeyTemplate) render(item *astjson.Value) (itemKeys, bool) { + body, ok := t.renderRepresentation(item) + if !ok { + return itemKeys{}, false + } + keys := itemKeys{L1: preimageCore(t.subgraph, body)} + if t.prefix != "" { + // Extending the body in place is safe because the L1 key above has + // already copied it into its own string. + l2Preimage := append(appendPartition(body, t.partition), '}') + keys.L2 = renderCacheKey(t.prefix, l2Preimage) + } + return keys, true +} + +// preimageCore joins the subgraph segment and the rendered body into the L1 +// key, closing the preimage object. +func preimageCore(subgraph string, body []byte) string { + core := make([]byte, 0, len(subgraph)+len(body)+2) + core = append(core, subgraph...) + core = append(core, ':') + core = append(core, body...) + core = append(core, '}') + return string(core) +} + +// appendPartition adds the requester's partition segment to an L2 preimage; a +// public fetch (empty partition) appends NOTHING, so its keys stay byte-for-byte +// what they were before privacy existed. +func appendPartition(preimage []byte, partition string) []byte { + if partition == "" { + return preimage + } + preimage = append(preimage, `,"partition":"`...) + preimage = append(preimage, partition...) + return append(preimage, '"') +} + +// sha256Hex hashes a partition value into its key segment. Partition +// collisions are cross-requester data leaks, so the 64-bit key hash is not +// good enough here: an identity must not be forgeable into another's partition. +func sha256Hex(value string) string { + sum := sha256.Sum256([]byte(value)) + return hex.EncodeToString(sum[:]) +} + +// renderRepresentation writes the canonical rendering of the fetch's +// representation against the item, so the key material is EXACTLY what the +// fetch sends. The canonical JSON is written DIRECTLY to a byte buffer — the +// hot lookup path builds no intermediate astjson values (profiled: value +// building dominated the cache-side allocations). The returned body is left +// UNCLOSED (no trailing `}`): each layer closes it, and only L2 inserts a +// partition segment first. +func (t cacheKeyTemplate) renderRepresentation(item *astjson.Value) ([]byte, bool) { + typeName := t.itemTypeName(item) + if typeName == "" { + return nil, false + } + preimage := make([]byte, 0, 64) + preimage = append(preimage, `{"__typename":"`...) + preimage = append(preimage, typeName...) + preimage = append(preimage, `","representation":`...) + representationStart := len(preimage) + preimage, ok := appendRepresentationObject(preimage, t.representation, item, wholeRepresentation) + if !ok { + return nil, false + } + if len(preimage) == representationStart+2 { + // A representation without any field ("{}") would collide across all + // entities of the type; treat it as unrenderable. + return nil, false + } + if t.args != "" { + // A fetch selecting no parameterized field appends nothing — not an empty + // segment — so its preimage stays the plain representation core. + preimage = append(preimage, `,"args":"`...) + preimage = append(preimage, t.args...) + preimage = append(preimage, '"') + } + return preimage, true +} + +// itemTypeName is the type an item keys and tags under. The node's __typename +// wins when the planner baked it in as a StaticString (the @interfaceObject / +// entity-interface remap): that is the name the fetch sends on the wire, so +// keying under it keeps ONE entry per entity instead of one per implementer. +// Otherwise the item's own __typename decides. "" when neither is available, or +// when there is no representation node or no item at all. +func (t cacheKeyTemplate) itemTypeName(item *astjson.Value) string { + if t.representation == nil || item == nil { + return "" + } + if typeName := staticTypeName(t.representation); typeName != "" { + return typeName + } + return valueTypeName(item) +} + +// argsDigest folds the request's argument VALUES for every parameterized field +// of the fetch's selection into one 16-hex digest, "" when the selection has +// none — without it two requests differing only in an argument value would +// share one entry and replace each other's value on every write. The digest +// input is the SORTED set of normalized field PATHS from the ProvidesData +// root, the last segment carrying the field's argument suffix: the path keeps +// same-named fields at different positions apart, the schema names and the +// value-derived suffix make aliases, selection order, and variable names +// irrelevant. The digest belongs to the fetch, never to an item. +func argsDigest(ctx *resolve.Context, provides *resolve.Object) string { + if provides == nil || !provides.HasAliases { + // HasAliases marks every object holding an aliased or parameterized field + // below it, so a false here proves there are no arguments to fold in — + // the same gate the normalize and denormalize walks run on. + return "" + } + entries := appendParameterizedFields(ctx, provides, "", nil) + if len(entries) == 0 { + return "" + } + slices.Sort(entries) + h := pool.Hash64.Get() + for i, entry := range entries { + if i > 0 { + _, _ = h.WriteString(",") + } + _, _ = h.WriteString(entry) + } + sum := h.Sum64() + pool.Hash64.Put(h) + return hex64(sum) +} + +// appendParameterizedFields collects the normalized paths of every field +// carrying arguments below obj, at ANY depth. A leaf field without arguments +// costs nothing: its name is only built when it is an entry or a path prefix. +func appendParameterizedFields(ctx *resolve.Context, obj *resolve.Object, path string, entries []string) []string { + for _, field := range obj.Fields { + child := parameterizedSubtree(field.Value) + if len(field.CacheArgs) == 0 && child == nil { + continue + } + name := path + normalizedFieldName(ctx, field) + if len(field.CacheArgs) > 0 { + entries = append(entries, name) + } + if child != nil { + entries = appendParameterizedFields(ctx, child, name+".", entries) + } + } + return entries +} + +// parameterizedSubtree unwraps a field value to the object it selects, through +// any list nesting — but only when that object's subtree can carry arguments at +// all, so the walk descends into the annotated parts of the tree and nothing +// else. nil for a leaf or an argument-free subtree. +func parameterizedSubtree(node resolve.Node) *resolve.Object { + for { + switch typed := node.(type) { + case *resolve.Object: + if !typed.HasAliases { + return nil + } + return typed + case *resolve.Array: + if typed.Item == nil { + return nil + } + node = typed.Item + default: + return nil + } + } +} + +// staticTypeName returns the node's baked-in __typename when the planner made it +// a StaticString (the @interfaceObject / entity-interface remap), "" otherwise. +func staticTypeName(node *resolve.Object) string { + for _, field := range node.Fields { + if string(field.Name) != "__typename" { + continue + } + if static, ok := field.Value.(*resolve.StaticString); ok { + return static.Value + } + return "" + } + return "" +} + +// representationScope selects which fields of a representation node a render +// covers: the whole node — the fetch's identity, `@key` and `@requires` alike — +// or its `@key` fields alone, which is the entity a tag addresses. +type representationScope uint8 + +const ( + wholeRepresentation representationScope = iota + keyFieldsOnly +) + +// appendRepresentationObject writes one canonical representation object from +// the item: fields in node order (GraphQL names never need JSON escaping), +// objects recurse, and every field that APPLIES must render. A merged +// representation for an abstract-type fetch carries per-concrete-type +// conditioned fields, so a field whose OnTypeNames exclude the item's type is +// skipped — exactly the coverage walk's rule (an absent __typename keeps +// conditioned fields required, the conservative choice). Under keyFieldsOnly a +// field outside the entity's `@key` set is skipped the same way. +func appendRepresentationObject(buf []byte, node *resolve.Object, value *astjson.Value, scope representationScope) ([]byte, bool) { + typeName := valueTypeName(value) + buf = append(buf, '{') + rendered := 0 + for _, field := range node.Fields { + name := string(field.Name) + if name == "__typename" { + continue + } + if scope == keyFieldsOnly && !field.CacheEntityKeyField { + continue + } + if skipFieldForTypeName(field, typeName) { + continue + } + if rendered > 0 { + buf = append(buf, ',') + } + buf = append(buf, '"') + buf = append(buf, name...) + buf = append(buf, '"', ':') + var ok bool + buf, ok = appendRepresentationValue(buf, field.Value, value.Get(name), scope) + if !ok { + return buf, false + } + rendered++ + } + if rendered == 0 && len(node.Fields) > 0 { + // Only __typename and non-applicable conditioned fields: nothing + // key-worthy below this node. + return buf, false + } + buf = append(buf, '}') + return buf, true +} + +// appendRepresentationValue writes the canonical key value for one template +// node from the item: objects recurse over the template's fields, scalars pass +// through. Numbers are unified with STRINGS of the same literal (the number 1 +// and the string "1" render the same key material) — astjson preserves the +// original literal, so 1 and 1.0 remain DISTINCT keys: a conservative split +// (extra miss, never wrong data). Full numeric canonicalization is deliberately +// avoided: parsing to float64 would corrupt integers beyond 2^53. A null or +// absent value makes the key unrenderable. +func appendRepresentationValue(buf []byte, node resolve.Node, value *astjson.Value, scope representationScope) ([]byte, bool) { + if value == nil || value.Type() == astjson.TypeNull { + return buf, false + } + switch typed := node.(type) { + case *resolve.Object: + if value.Type() != astjson.TypeObject { + return buf, false + } + return appendRepresentationObject(buf, typed, value, scope) + default: + if value.Type() == astjson.TypeNumber { + buf = append(buf, '"') + buf = value.MarshalTo(buf) + buf = append(buf, '"') + return buf, true + } + return value.MarshalTo(buf), true + } +} + +// cacheKeyPrefix returns the visible L2 key prefix: the format version, the +// fetch's subgraph name — each subgraph owns its keyspace — and +// "h" when a PUBLIC fetch varies by its forwarded subgraph headers. +// On a private fetch that same hash is the requester IDENTITY instead and lives +// in the hashed partition segment, so the prefix stays plain: one fetch is +// partitioned by exactly one mechanism. +func cacheKeyPrefix(cfg *resolve.FetchCacheConfig, headerHash uint64) string { + prefix := cacheFormatVersion + ":" + cfg.SubgraphName + if cfg.IncludeSubgraphHeaders && !cfg.Private { + return prefix + ":h" + hex64(headerHash) + } + return prefix +} + +// renderCacheKey hashes the preimage ":" with the pooled +// xxhash64 and returns ":<16-hex sum>": the visible prefix is part of +// the hashed material, so keys of different prefixes can never collide on their +// digests alone. +func renderCacheKey(prefix string, payload []byte) string { + preimage := make([]byte, 0, len(prefix)+1+len(payload)) + preimage = append(preimage, prefix...) + preimage = append(preimage, ':') + preimage = append(preimage, payload...) + return prefix + ":" + hashHex(preimage) +} + +func hashHex(value []byte) string { + h := pool.Hash64.Get() + _, _ = h.Write(value) + sum := h.Sum64() + pool.Hash64.Put(h) + return hex64(sum) +} + +func hex64(sum uint64) string { + var buf [16]byte + const digits = "0123456789abcdef" + for i := 15; i >= 0; i-- { + buf[i] = digits[sum&0xf] + sum >>= 4 + } + return string(buf[:]) +} + +// rootFieldCacheKey renders the whole-response root-field L2 key in the same +// layout as entity keys — "v1:{subgraph}[:h]:" — over a +// preimage of the fetch's root-field coordinate and the request variables in +// canonical (name-sorted) form. The QUERY TEXT is deliberately +// excluded so alias-variant operations share the entry (coverage and +// normalization guard servability and shape). PRECONDITION: operations are +// normalized with variable extraction (the engine always does this), so inline +// argument literals are variables and cannot collide under one key. +func rootFieldCacheKey(cfg *resolve.FetchCacheConfig, headerHash uint64, ctx *resolve.Context, partition string) string { + prefix := cacheKeyPrefix(cfg, headerHash) + preimage := make([]byte, 0, 64) + preimage = append(preimage, cfg.KeySpec.TypeName...) + preimage = append(preimage, '.') + preimage = append(preimage, cfg.KeySpec.FieldName...) + preimage = append(preimage, ':') + preimage = append(preimage, canonicalVariables(ctx)...) + // Root fields carry the same partition segment as entities (their preimage + // is not a JSON object, so it simply trails the variables). + return renderCacheKey(prefix, appendPartition(preimage, partition)) +} + +// canonicalVariables renders the request variables with name-sorted top-level +// keys, so clients sending the same variables in different order share keys. +func canonicalVariables(ctx *resolve.Context) []byte { + if ctx == nil || ctx.Variables == nil { + return []byte("null") + } + obj, err := ctx.Variables.Object() + if err != nil { + return ctx.Variables.MarshalTo(nil) + } + type pair struct { + name string + value *astjson.Value + } + pairs := make([]pair, 0, obj.Len()) + obj.Visit(func(key []byte, v *astjson.Value) { + pairs = append(pairs, pair{name: string(key), value: v}) + }) + slices.SortFunc(pairs, func(a, b pair) int { + return cmp.Compare(a.name, b.name) + }) + out := make([]byte, 0, 64) + out = append(out, '{') + for i, p := range pairs { + if i > 0 { + out = append(out, ',') + } + out = append(out, '"') + out = append(out, p.name...) + out = append(out, '"', ':') + out = p.value.MarshalTo(out) + } + out = append(out, '}') + return out +} diff --git a/v2/pkg/engine/cache/cache_key_template_test.go b/v2/pkg/engine/cache/cache_key_template_test.go new file mode 100644 index 0000000000..a6d4eabeeb --- /dev/null +++ b/v2/pkg/engine/cache/cache_key_template_test.go @@ -0,0 +1,269 @@ +package cache + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// templateFor builds the key template for a representation node under the +// "products" subgraph with L2 enabled, exactly as PrepareFetch does. +func templateFor(t *testing.T, node *resolve.Object) cacheKeyTemplate { + t.Helper() + template, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{ + SubgraphName: "products", + KeySpec: resolve.CacheKeySpec{Scope: resolve.CacheScopeEntity, TypeName: "Product", Representation: node}, + }, 0, l2Access{enabled: true}) + require.True(t, ok) + return template +} + +// TestCacheKeyTemplateRender pins the canonical preimage of a rendered key and +// the render rules the representation model adds: @requires values participate +// in the identity, per-concrete-type conditioned fields are skipped rather than +// fatal, and a node with a static __typename keys under that static name. +func TestCacheKeyTemplateRender(t *testing.T) { + t.Run("the preimage is __typename plus the canonical representation", func(t *testing.T) { + template := templateFor(t, productRepresentation(t, "upc")) + keys, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","name":"Table"}`))) + require.True(t, ok) + // Only representation fields enter the key; other item fields do not. + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + L2: renderCacheKey("v1:products", []byte(`{"__typename":"Product","representation":{"upc":"1"}}`)), + }, keys) + }) + + t.Run("no template without a representation node", func(t *testing.T) { + _, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{SubgraphName: "products"}, 0, l2Access{enabled: true}) + assert.False(t, ok) + _, ok = newCacheKeyTemplate(nil, nil, 0, l2Access{enabled: true}) + assert.False(t, ok) + }) + + t.Run("@requires fields are key material: the same values render the same keys", func(t *testing.T) { + template := templateFor(t, productRepresentation(t, "upc", "price")) + first, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":100}`))) + require.True(t, ok) + second, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":100}`))) + require.True(t, ok) + assert.Equal(t, first, second) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1","price":"100"}}`, + L2: renderCacheKey("v1:products", []byte(`{"__typename":"Product","representation":{"upc":"1","price":"100"}}`)), + }, first) + }) + + t.Run("@requires fields are key material: a changed required value is a NEW key", func(t *testing.T) { + template := templateFor(t, productRepresentation(t, "upc", "price")) + cheap, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":100}`))) + require.True(t, ok) + pricey, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":120}`))) + require.True(t, ok) + assert.NotEqual(t, cheap, pricey) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1","price":"120"}}`, + L2: renderCacheKey("v1:products", []byte(`{"__typename":"Product","representation":{"upc":"1","price":"120"}}`)), + }, pricey) + }) + + t.Run("an absent @requires value makes the keys unrenderable", func(t *testing.T) { + template := templateFor(t, productRepresentation(t, "upc", "price")) + keys, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`))) + assert.False(t, ok) + assert.Equal(t, itemKeys{}, keys) + }) + + t.Run("a field conditioned on another concrete type is SKIPPED, not fatal", func(t *testing.T) { + // The merged node of an abstract-path batch fetch: one conditioned key + // field per concrete type. + node := mergedRepresentation(t, plan.FederationMetaData{}, + plan.FederationFieldConfiguration{TypeName: "Product", SelectionSet: "upc"}, + plan.FederationFieldConfiguration{TypeName: "Brand", SelectionSet: "id"}, + ) + template := templateFor(t, node) + + productKeys, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`))) + require.True(t, ok) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Product","representation":{"upc":"1"}}`, + L2: renderCacheKey("v1:products", []byte(`{"__typename":"Product","representation":{"upc":"1"}}`)), + }, productKeys) + + brandKeys, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Brand","id":"b1"}`))) + require.True(t, ok) + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Brand","representation":{"id":"b1"}}`, + L2: renderCacheKey("v1:products", []byte(`{"__typename":"Brand","representation":{"id":"b1"}}`)), + }, brandKeys) + assert.NotEqual(t, productKeys, brandKeys) + }) + + t.Run("an item matching no conditioned set is unrenderable", func(t *testing.T) { + node := mergedRepresentation(t, plan.FederationMetaData{}, + plan.FederationFieldConfiguration{TypeName: "Product", SelectionSet: "upc"}, + plan.FederationFieldConfiguration{TypeName: "Brand", SelectionSet: "id"}, + ) + keys, ok := templateFor(t, node).render(astjson.MustParseBytes([]byte(`{"__typename":"Warehouse","upc":"1","id":"b1"}`))) + assert.False(t, ok) + assert.Equal(t, itemKeys{}, keys) + }) + + t.Run("an item without __typename is unrenderable", func(t *testing.T) { + keys, ok := templateFor(t, productRepresentation(t, "upc")).render(astjson.MustParseBytes([]byte(`{"upc":"1"}`))) + assert.False(t, ok) + assert.Equal(t, itemKeys{}, keys) + }) + + t.Run("a static node __typename keys under that name whatever the item says", func(t *testing.T) { + // An @interfaceObject target: the planner bakes the interface name into + // the node as a StaticString, and that is what the fetch sends. + node := mergedRepresentation(t, plan.FederationMetaData{ + InterfaceObjects: []plan.EntityInterfaceConfiguration{ + {InterfaceTypeName: "Sellable", ConcreteTypeNames: []string{"Product"}}, + }, + }, plan.FederationFieldConfiguration{TypeName: "Product", SelectionSet: "upc"}) + template := templateFor(t, node) + + concrete, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`))) + require.True(t, ok) + iface, ok := template.render(astjson.MustParseBytes([]byte(`{"__typename":"Sellable","upc":"1"}`))) + require.True(t, ok) + // ONE entry for the entity, under the interface name the fetch sends. + assert.Equal(t, itemKeys{ + L1: `products:{"__typename":"Sellable","representation":{"upc":"1"}}`, + L2: renderCacheKey("v1:products", []byte(`{"__typename":"Sellable","representation":{"upc":"1"}}`)), + }, concrete) + assert.Equal(t, concrete, iface) + }) + + t.Run("nil item and nil representation render nothing", func(t *testing.T) { + keys, ok := templateFor(t, productRepresentation(t, "upc")).render(nil) + assert.False(t, ok) + assert.Equal(t, itemKeys{}, keys) + keys, ok = cacheKeyTemplate{subgraph: "products", prefix: "v1:products"}.render(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`))) + assert.False(t, ok) + assert.Equal(t, itemKeys{}, keys) + }) +} + +// TestCacheKeyLayout pins the key LAYOUT itself: the format version leads every +// store key, each subgraph owns its keyspace in both layers, the header hash +// varies the visible prefix and the hashed preimage together, and an L1-only +// fetch derives no store key at all. +func TestCacheKeyLayout(t *testing.T) { + item := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)) + representation := `{"__typename":"Product","representation":{"upc":"1"}}` + + t.Run("the visible store key is version, subgraph, and the preimage digest", func(t *testing.T) { + keys, ok := templateFor(t, productRepresentation(t, "upc")).render(item) + require.True(t, ok) + assert.Equal(t, "v1:products:"+hashHex([]byte("v1:products:"+representation)), keys.L2) + }) + + t.Run("the same entity in two subgraphs is two entries", func(t *testing.T) { + spec := resolve.CacheKeySpec{Scope: resolve.CacheScopeEntity, TypeName: "Product", Representation: productRepresentation(t, "upc")} + products, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{SubgraphName: "products", KeySpec: spec}, 0, l2Access{enabled: true}) + require.True(t, ok) + inventory, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{SubgraphName: "inventory", KeySpec: spec}, 0, l2Access{enabled: true}) + require.True(t, ok) + + productsKeys, ok := products.render(item) + require.True(t, ok) + inventoryKeys, ok := inventory.render(item) + require.True(t, ok) + assert.Equal(t, itemKeys{ + L1: "products:" + representation, + L2: "v1:products:" + hashHex([]byte("v1:products:"+representation)), + }, productsKeys) + assert.Equal(t, itemKeys{ + L1: "inventory:" + representation, + L2: "v1:inventory:" + hashHex([]byte("v1:inventory:"+representation)), + }, inventoryKeys) + }) + + t.Run("the header hash varies the prefix only when the config asks", func(t *testing.T) { + spec := resolve.CacheKeySpec{Scope: resolve.CacheScopeEntity, TypeName: "Product", Representation: productRepresentation(t, "upc")} + plain, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{SubgraphName: "products", KeySpec: spec}, 42, l2Access{enabled: true}) + require.True(t, ok) + varying, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{SubgraphName: "products", IncludeSubgraphHeaders: true, KeySpec: spec}, 42, l2Access{enabled: true}) + require.True(t, ok) + assert.Equal(t, "v1:products", plain.prefix) + assert.Equal(t, "v1:products:h"+hex64(42), varying.prefix) + + varyingKeys, ok := varying.render(item) + require.True(t, ok) + // The header hash rides in the visible prefix AND in the hashed + // preimage; the L1 key never carries it (the map is per-requester). + assert.Equal(t, itemKeys{ + L1: "products:" + representation, + L2: "v1:products:h" + hex64(42) + ":" + hashHex([]byte("v1:products:h"+hex64(42)+":"+representation)), + }, varyingKeys) + }) + + t.Run("an L1-only fetch derives no store key and no prefix", func(t *testing.T) { + spec := resolve.CacheKeySpec{Scope: resolve.CacheScopeEntity, TypeName: "Product", Representation: productRepresentation(t, "upc")} + template, ok := newCacheKeyTemplate(nil, &resolve.FetchCacheConfig{SubgraphName: "products", IncludeSubgraphHeaders: true, KeySpec: spec}, 42, l2Access{}) + require.True(t, ok) + assert.Equal(t, "", template.prefix) + + keys, ok := template.render(item) + require.True(t, ok) + assert.Equal(t, itemKeys{L1: "products:" + representation}, keys) + }) +} + +// TestRootFieldCacheKeyLayout pins that root-field keys follow the entity +// layout — version, subgraph, digest — over their coordinate + variables +// preimage. +func TestRootFieldCacheKeyLayout(t *testing.T) { + ctx := resolve.NewContext(t.Context()) + ctx.Variables = astjson.MustParseBytes([]byte(`{"first":5}`)) + cfg := &resolve.FetchCacheConfig{ + SubgraphName: "products", + KeySpec: resolve.CacheKeySpec{Scope: resolve.CacheScopeRootField, TypeName: "Query", FieldName: "topProducts"}, + } + + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:Query.topProducts:{"first":5}`)), + rootFieldCacheKey(cfg, 0, ctx, ""), + ) +} + +// TestControllerRequiresCoherence is the @requires coherence property at the +// controller level: a value derived from price 100 is cached under a key that +// INCLUDES price 100, so the same entity fetched with price 120 misses instead +// of serving a value computed from stale inputs. +func TestControllerRequiresCoherence(t *testing.T) { + store := newTestStore() + // The fetch sends @key(upc) plus the @requires field price. + cfg := entityConfigForRepresentation(t, time.Minute, productRepresentation(t, "upc", "price")) + + cheapItem := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":100}`)) + cheapKey := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, cheapItem, + `{"__typename":"Product","name":"Table","price":100}`) + store.ops = nil // the second request's ops assert in isolation + + // Same entity, changed required input: a different key, hence a MISS. + rc := NewController(store, nil).BeginRequest(nil) + priceyItem := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":120}`)) + decision, handle := prepare(t, rc, cfg, priceyItem) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.Items[0].FromCache) + assert.NotEqual(t, cheapKey, handle.Items[0].RenderedKey) + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + + // The unchanged inputs still hit their own entry. + decision, _ = prepare(t, NewController(store, nil).BeginRequest(nil), cfg, + astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":100}`))) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) +} diff --git a/v2/pkg/engine/cache/cache_response.go b/v2/pkg/engine/cache/cache_response.go new file mode 100644 index 0000000000..ea59e0d665 --- /dev/null +++ b/v2/pkg/engine/cache/cache_response.go @@ -0,0 +1,210 @@ +package cache + +import ( + "maps" + "slices" + "sync" + "time" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// The client cache answer: ONE per request, folded per fetch and read after +// resolution through resolve.Context.CacheResponseInfo. Each fetch contributes +// the freshness the response may still be served under — what is LEFT of a +// served entry's lifetime, or the lifetime a fresh write got — and ZERO when +// it was not cacheable; one zero makes the whole response no-store. Two +// exceptions: an L1-served part contributes nothing (its originating fetch +// folded already), and a fetch with NO cache configuration is a zero that +// cannot stand alone — an operation the cache never touched has no policy +// rather than no-store. + +// responseAggregate accumulates the client cache answer of one request. +// +// It guards itself with a mutex instead of riding the CacheTransaction lock the +// rest of the request state uses: the folds sit where a fetch's cacheability is +// DECIDED — the merge hooks' failure gates and the prepare give-ups included — +// and those points run outside any open transaction. The lock is uncontended in +// practice (one fold per fetch) and never held across arena work. +type responseAggregate struct { + // emitCacheControl gates the freshness/privacy fold, emitTags the tag union; + // an aggregate exists only while at least one of them is on. + emitCacheControl bool + emitTags bool + + mu sync.Mutex + hasPolicy bool + noStore bool + uncachedFetch bool + hasFreshness bool + freshness time.Duration + private bool + tags map[string]struct{} +} + +// fold folds ONE part into the answer: a non-positive freshness makes the whole +// response no-store, a positive one lowers the response's freshness to the +// minimum, and a private part marks the whole response private. +func (a *responseAggregate) fold(freshness time.Duration, private bool) { + if !a.emitCacheControl { + return + } + a.mu.Lock() + defer a.mu.Unlock() + a.hasPolicy = true + a.private = a.private || private + if freshness <= 0 { + a.noStore = true + return + } + if !a.hasFreshness || freshness < a.freshness { + a.hasFreshness = true + a.freshness = freshness + } +} + +// noteUncachedFetch records that one fetch of this response ran outside the +// cache. It is not a fold of its own: on its own it says nothing, and next to +// any cached part it makes the response no-store. +func (a *responseAggregate) noteUncachedFetch() { + if !a.emitCacheControl { + return + } + a.mu.Lock() + defer a.mu.Unlock() + a.uncachedFetch = true +} + +// foldTags adds one entry's invalidation tags to the response's union. The +// union is a set: entries written and served under the same tags — every +// variant of one entity, every fetch of one subgraph — collapse into one +// purgeable address. +func (a *responseAggregate) foldTags(tags []string) { + if !a.emitTags || len(tags) == 0 { + return + } + a.mu.Lock() + defer a.mu.Unlock() + if a.tags == nil { + a.tags = make(map[string]struct{}, len(tags)) + } + for _, tag := range tags { + a.tags[tag] = struct{}{} + } +} + +// info renders the accumulated answer. The tag union is SORTED here, at read +// time, so one response's header is byte-identical however its fetches +// interleaved. +func (a *responseAggregate) info() resolve.CacheResponseInfo { + a.mu.Lock() + defer a.mu.Unlock() + info := resolve.CacheResponseInfo{ + HasPolicy: a.hasPolicy, + Private: a.private, + // The uncached-fetch zero answers only once a cached part gave the + // response something to restrict; on its own there is nothing to say. + NoStore: a.hasPolicy && (a.noStore || a.uncachedFetch), + } + if !info.NoStore && a.hasFreshness { + info.MaxAge = a.freshness + } + if len(a.tags) > 0 { + info.Tags = slices.Sorted(maps.Keys(a.tags)) + } + return info +} + +// CacheResponseInfo implements resolve.CacheResponseInfoSource: the request's +// client cache answer, readable after resolution — including after EndRequest, +// which touches nothing this reads. +func (r *requestCache) CacheResponseInfo() resolve.CacheResponseInfo { + if r.aggregate == nil { + return resolve.CacheResponseInfo{} + } + return r.aggregate.info() +} + +// OnUncachedFetch records one fetch of this request that ran with no cache +// configuration. It is the hook that may open a request — the loader calls it +// before the load — and it costs nothing while no client answer is computed. +func (r *requestCache) OnUncachedFetch() { + if r.aggregate == nil { + return + } + r.aggregate.noteUncachedFetch() +} + +// foldServedItem folds ONE item served from a store entry: what is left of the +// entry's lifetime bounds the response, and its tags join the CDN union. An +// item served from the request-lifetime layer is skipped — see the package +// comment above on why that is not a zero contribution. An entry the clock has +// already caught up with contributes zero and makes the response no-store: +// freshness that is gone promises nothing. +func (r *requestCache) foldServedItem(cfg *resolve.FetchCacheConfig, item *resolve.ItemCacheState) { + if r.aggregate == nil || item.FromCache == nil || item.ServedFromLayer == servedFromL1 { + return + } + r.aggregate.fold(item.ServedFreshness, cfg.Private) + r.aggregate.foldTags(item.Tags) +} + +// foldFetchedResult folds ONE fresh subgraph result: the lifetime its entries +// were stored under. The tags of those entries join the union as they are +// queued, in deferSet — exactly the entries that were really written. +func (r *requestCache) foldFetchedResult(h *resolve.FetchCacheHandle, in resolve.MergeInput, decision cachingDecision) { + if r.aggregate == nil { + return + } + r.aggregate.fold(fetchedFreshness(h, in, decision), decision.Private) +} + +// foldUncacheableFetch folds a cache-CONFIGURED fetch whose data reached the +// response without landing in any entry: the controller declined it outright +// (no handle — no derivable key, or a private coordinate without a requester +// identity), or its result failed and blocked every write. +func (r *requestCache) foldUncacheableFetch(cfg *resolve.FetchCacheConfig) { + if r.aggregate == nil { + return + } + r.aggregate.fold(0, cfg.Private) +} + +// servedFreshness is what is left of a served entry's lifetime, computed from +// the entry's OWN record (created + ttl - now) rather than from the store's +// remaining-TTL report, which backends may not keep. Zero — and unread — when +// no client answer is being computed. +func (r *requestCache) servedFreshness(envelope storedEnvelope) time.Duration { + if r.aggregate == nil { + return 0 + } + return time.Until(envelope.Created.Add(envelope.TTL)) +} + +// fetchedFreshness is the freshness one fresh result contributes: the lifetime +// its entries were written under, or ZERO when the result did not become +// entries at all — a failed or empty response, a storability decision that +// permits no write, or a fetch whose items did not all render a store key +// (an L1-only fetch, an unidentified private one, an unrenderable item). +func fetchedFreshness(h *resolve.FetchCacheHandle, in resolve.MergeInput, decision cachingDecision) time.Duration { + ttl := decision.TTL + if in.ResponseData == nil || in.ResponseData.Type() == astjson.TypeNull { + // A response with no data becomes an entry in exactly one case: a fetch + // that legitimately resolved no entity writes the negative sentinel. + ttl = 0 + if in.EmptyEntity && in.ResponseData != nil { + ttl = decision.NegativeTTL + } + } + if ttl <= 0 { + return 0 + } + for i := range h.Items { + if h.Items[i].RenderedKey == "" { + return 0 + } + } + return ttl +} diff --git a/v2/pkg/engine/cache/cache_response_test.go b/v2/pkg/engine/cache/cache_response_test.go new file mode 100644 index 0000000000..192de81860 --- /dev/null +++ b/v2/pkg/engine/cache/cache_response_test.go @@ -0,0 +1,452 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// clientAnswerRequest begins ONE request of a controller carrying the given +// global knobs, and returns both sides of the client cache answer: the Context +// the integrator reads it from and the cache surface that folds it. +func clientAnswerRequest(t *testing.T, store Store, global cacheconfig.GlobalCacheConfig) (*resolve.Context, resolve.RequestCache) { + t.Helper() + ctx := resolve.NewContext(t.Context()) + return ctx, NewController(store, nil, WithGlobalConfig(global)).BeginRequest(ctx) +} + +// fetchPart runs one miss -> fresh-result cycle for an item on an already begun +// request, with the Cache-Control the subgraph answered with ("" = none). It +// does NOT end the request: a response is folded from several parts. +func fetchPart(t *testing.T, rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, item *astjson.Value, responseData, cacheControlValue string) { + t.Helper() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(responseData)), + ResponseHeaders: cacheControlHeader(cacheControlValue), + Arena: beginner(), + })) +} + +// servePart runs one full-hit cycle for an item: the lookup that covers it and +// the splice hook that folds what is left of the entry's freshness. +func servePart(t *testing.T, rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, item *astjson.Value) { + t.Helper() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + Arena: beginner(), + })) +} + +// TestClientCacheAnswerFreshness pins the freshness fold: which part +// contributes what, which part makes the whole response unstorable, and the +// difference between "nothing to say" and "do not store this". +func TestClientCacheAnswerFreshness(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("a fresh result contributes the lifetime its entry was written under", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + }, ctx.CacheResponseInfo()) + }) + + t.Run("the header-driven lifetime is what a fresh part contributes", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + // The origin's max-age beats the configured 5m for the entry AND for the + // answer: one resolved lifetime feeds both. + fetchPart(t, rc, entityConfig(t, 5*time.Minute), productItem(t, "1"), fresh, "max-age=30") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: 30 * time.Second, + }, ctx.CacheResponseInfo()) + }) + + t.Run("the shortest-lived part decides the answer", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, entityConfig(t, 5*time.Minute), productItem(t, "1"), fresh, "") + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "2"), fresh, "") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a served entry contributes what is LEFT of its lifetime, and counts down", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + + // The request that writes the entry answers with its full lifetime. + writing, writingCache := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, writingCache, cfg, productItem(t, "1"), fresh, "") + writingCache.EndRequest() + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + }, writing.CacheResponseInfo()) + + time.Sleep(20 * time.Second) + served, servedCache := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + servePart(t, servedCache, cfg, productItem(t, "1")) + servedCache.EndRequest() + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: 40 * time.Second, + }, served.CacheResponseInfo()) + + // Two seconds later the SAME entry answers two seconds less: the + // answer counts down with the entry instead of restarting at its + // written lifetime. + time.Sleep(2 * time.Second) + later, laterCache := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + servePart(t, laterCache, cfg, productItem(t, "1")) + laterCache.EndRequest() + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: 38 * time.Second, + }, later.CacheResponseInfo()) + }) + }) + + t.Run("a served entry bounds a fresher part of the same response", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + warm := entityConfig(t, time.Minute) + _, warming := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, warming, warm, productItem(t, "1"), fresh, "") + warming.EndRequest() + + time.Sleep(45 * time.Second) + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + servePart(t, rc, warm, productItem(t, "1")) + fetchPart(t, rc, entityConfig(t, 5*time.Minute), productItem(t, "2"), fresh, "") + rc.EndRequest() + + // The 15s left on the served entry, not the 5m the fresh part was + // just written under. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: 15 * time.Second, + }, ctx.CacheResponseInfo()) + }) + }) + + t.Run("a part served from the request-lifetime layer adds no constraint of its own", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, cfg, productItem(t, "1"), fresh, "") + // The second fetch of the same entity rides the value the first one put + // in the request-lifetime layer. Counting that as uncacheable would make + // a fully cacheable response no-store. + servePart(t, rc, cfg, productItem(t, "1")) + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a part the origin marked no-store makes the whole response no-store", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "2"), fresh, "no-store") + rc.EndRequest() + + // The most restrictive part wins outright: the minute the first part is + // good for is not reported alongside it. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a part with a non-positive resolved lifetime makes the response no-store", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "max-age=0") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a part that reaches no store layer makes the response no-store", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + // TTL 0 leaves the fetch on the request-lifetime layer alone: nothing a + // later request — or a CDN — could serve from. + fetchPart(t, rc, entityConfig(t, 0), productItem(t, "1"), fresh, "") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a failed fetch makes the response no-store", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + item := productItem(t, "1") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + FetchFailed: true, + Arena: beginner(), + })) + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a fetch that ran outside the cache makes the response no-store", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + rc.OnUncachedFetch() + rc.EndRequest() + + // The cached part's minute is not advertised for a response that also + // carries data no policy covers. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("an uncached fetch counts however it is ordered against the cached one", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + // The uncached fetch runs FIRST here — the order the loader produces + // whenever a cached entity hangs off an uncached root field. + rc.OnUncachedFetch() + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("uncached fetches alone answer nothing", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + rc.OnUncachedFetch() + rc.OnUncachedFetch() + rc.EndRequest() + + // The zero contribution that cannot stand alone: with nothing cached to + // restrict, the answer stays empty and the integrator emits no header — + // a graph without caching never grows a no-store header. + assert.Equal(t, resolve.CacheResponseInfo{}, ctx.CacheResponseInfo()) + }) + + t.Run("a request whose fetches are none of the cache's business answers nothing", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + rc.EndRequest() + + // An EMPTY answer, not a no-store one: the integrator emits no header at + // all rather than forbidding a cache it never consulted. + assert.Equal(t, resolve.CacheResponseInfo{}, ctx.CacheResponseInfo()) + }) + + t.Run("a request without a cache controller answers nothing", func(t *testing.T) { + assert.Equal(t, resolve.CacheResponseInfo{}, resolve.NewContext(t.Context()).CacheResponseInfo()) + }) +} + +// TestClientCacheAnswerPrivacy pins the privacy fold: both sources mark the +// response private, whether or not anything was stored. +func TestClientCacheAnswerPrivacy(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("a statically-private part marks the response private", func(t *testing.T) { + store := newTestStore() + ctx := resolve.NewContext(t.Context()) + ctx.SetPrivatePartitionProvider(&partitionProvider{identities: map[string]string{"products": "user-a"}}) + rc := NewController(store, nil).BeginRequest(ctx) + fetchPart(t, rc, privateEntityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + rc.EndRequest() + + // The entry WAS stored — in the requester's partition — so the response + // stays fresh for a minute, for that requester alone. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + Private: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a private response header marks the response private and stores nothing", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "private, max-age=600") + rc.EndRequest() + + // A statically-public fetch answered private has nowhere to put the + // value: no entry, hence no freshness to promise. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + Private: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a statically-private part without a requester identity makes the response no-store", func(t *testing.T) { + store := newTestStore() + ctx := resolve.NewContext(t.Context()) + rc := NewController(store, nil).BeginRequest(ctx) + fetchPart(t, rc, privateEntityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + Private: true, + NoStore: true, + }, ctx.CacheResponseInfo()) + }) +} + +// TestClientCacheAnswerTags pins the CDN tag union: which entries contribute, +// how duplicates collapse, and that the order is the sorted one. +func TestClientCacheAnswerTags(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + rootResponse := `{"products":[{"name":"Table"}]}` + + t.Run("the union collects the written entries, sorted and deduplicated", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{EmitCdnTags: true}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "2"), fresh, "") + fetchPart(t, rc, rootFieldConfig(time.Minute), rootItem(), rootResponse, "") + rc.EndRequest() + + // The two entities share their subgraph and type tags — one address + // each — while their entity tags keep them separately purgeable, and + // the root-field entry adds the coordinate's Query type tag. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + Tags: []string{ + "entity:products:Product:4f93140518d68e67", // upc "2" + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + "subgraph:products", + "type:products:Product", + "type:products:Query", + }, + }, ctx.CacheResponseInfo()) + }) + + t.Run("a served entry's tags join the union: the CDN caches what the client sees", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + _, warming := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{EmitCdnTags: true}) + fetchPart(t, warming, cfg, productItem(t, "1"), fresh, "") + warming.EndRequest() + + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{EmitCdnTags: true}) + servePart(t, rc, cfg, productItem(t, "1")) + rc.EndRequest() + + // This response wrote nothing at all and is still fully purgeable. + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + Tags: []string{ + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + "subgraph:products", + "type:products:Product", + }, + }, ctx.CacheResponseInfo()) + }) + }) + + t.Run("no tags are accumulated while emission is off", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + rc.EndRequest() + + assert.Equal(t, resolve.CacheResponseInfo{ + HasPolicy: true, + MaxAge: time.Minute, + }, ctx.CacheResponseInfo()) + }) +} + +// TestClientCacheAnswerKnobs pins the two emission switches, including the one +// combination that must cost nothing at all. +func TestClientCacheAnswerKnobs(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("both knobs off allocate no aggregation state", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{EmitClientCacheControl: ptr(false)}) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + // The loader's per-fetch notification must stay free too: with nothing to + // accumulate into, it allocates and locks nothing. + rc.OnUncachedFetch() + rc.EndRequest() + + require.Nil(t, rc.(*requestCache).aggregate) + assert.Equal(t, resolve.CacheResponseInfo{}, ctx.CacheResponseInfo()) + }) + + t.Run("tags alone accumulate without a freshness answer", func(t *testing.T) { + store := newTestStore() + ctx, rc := clientAnswerRequest(t, store, cacheconfig.GlobalCacheConfig{ + EmitClientCacheControl: ptr(false), + EmitCdnTags: true, + }) + fetchPart(t, rc, entityConfig(t, time.Minute), productItem(t, "1"), fresh, "") + // An uncached fetch restricts a freshness answer that is not being + // computed here, so it leaves the tag union alone. + rc.OnUncachedFetch() + rc.EndRequest() + + // No policy and no freshness: the integrator emits the tag header alone. + assert.Equal(t, resolve.CacheResponseInfo{ + Tags: []string{ + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + "subgraph:products", + "type:products:Product", + }, + }, ctx.CacheResponseInfo()) + }) +} diff --git a/v2/pkg/engine/cache/cache_tags.go b/v2/pkg/engine/cache/cache_tags.go new file mode 100644 index 0000000000..537c1d0504 --- /dev/null +++ b/v2/pkg/engine/cache/cache_tags.go @@ -0,0 +1,55 @@ +package cache + +import ( + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// The default tag vocabulary every L2 entry is written under. Keys are identity +// — derived from what a fetch sends, never externally addressable — while tags +// are the addressing layer an invalidation endpoint and a tag-purging CDN both +// speak: +// +// subgraph:{subgraph} +// type:{subgraph}:{TypeName} // Query for a root-field entry +// entity:{subgraph}:{TypeName}:{key digest} // entity entries only +// +// Tags are always emitted in that order — coarsest first — so the vocabulary +// reads the same in every op log and every purge request. +const ( + subgraphTagPrefix = "subgraph:" + typeTagPrefix = "type:" + entityTagPrefix = "entity:" +) + +// entityTags renders one entity item's default tags. The entity tag's digest +// covers the item's `@key` fields ALONE — no `@requires` values, no argument +// digest, no partition segment — so every variant of one entity shares it and +// a single purge clears them all. The tags derive from the SAME pre-merge item +// as the entry's keys, so a tag can never describe a different entity than the +// key it is stored under; an item that renders no key subset still carries the +// two coarse tags, and nil means the item has no type to tag under at all. +func (t cacheKeyTemplate) entityTags(item *astjson.Value) []string { + typeName := t.itemTypeName(item) + if typeName == "" { + return nil + } + tags := make([]string, 0, 3) + tags = append(tags, subgraphTagPrefix+t.subgraph, typeTagPrefix+t.subgraph+":"+typeName) + if keySubset, ok := appendRepresentationObject(nil, t.representation, item, keyFieldsOnly); ok { + tags = append(tags, entityTagPrefix+t.subgraph+":"+typeName+":"+hashHex(keySubset)) + } + return tags +} + +// rootFieldTags renders a root-field entry's default tags. A root-field +// response is not one entity, so it carries no entity tag; its type is the +// coordinate's — Query — which makes "purge everything this subgraph answers at +// the root" a single tag. +func rootFieldTags(cfg *resolve.FetchCacheConfig) []string { + return []string{ + subgraphTagPrefix + cfg.SubgraphName, + typeTagPrefix + cfg.SubgraphName + ":" + cfg.KeySpec.TypeName, + } +} diff --git a/v2/pkg/engine/cache/cache_tags_test.go b/v2/pkg/engine/cache/cache_tags_test.go new file mode 100644 index 0000000000..92fcad8bfa --- /dev/null +++ b/v2/pkg/engine/cache/cache_tags_test.go @@ -0,0 +1,202 @@ +package cache + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// TestEntityTags pins the tags an entity entry is written under: the fixed +// three-tag vocabulary in its fixed order, and the property that makes the +// entity tag an ENTITY address rather than an entry address — its digest +// covers the item's @key fields alone, so every entry that describes one +// entity carries the same tag whatever else varies in its key. +func TestEntityTags(t *testing.T) { + t.Run("a @key representation yields subgraph, type, and entity tags in that order", func(t *testing.T) { + tags := templateFor(t, productRepresentation(t, "upc")). + entityTags(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","name":"Table"}`))) + // The entity digest is xxhash64 of the canonical @key rendering + // `{"upc":"1"}`; fields outside the representation never reach it. + assert.Equal(t, []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", + }, tags) + }) + + t.Run("two entities of one type differ only in the entity tag", func(t *testing.T) { + template := templateFor(t, productRepresentation(t, "upc")) + assert.Equal(t, []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:4f93140518d68e67", // `{"upc":"2"}` + }, template.entityTags(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"2"}`)))) + assert.Equal(t, []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:dae7809df4f7fdee", // `{"upc":"3"}` + }, template.entityTags(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"3"}`)))) + }) + + t.Run("@requires values change the KEY but not the entity tag", func(t *testing.T) { + // The fetch sends @key(upc) plus the @requires field price, so its two + // items are two independent entries — and one purge of the product must + // clear both. + template := templateFor(t, productRepresentation(t, "upc", "price")) + cheap := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":100}`)) + pricey := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":120}`)) + + cheapKeys, ok := template.render(cheap) + require.True(t, ok) + priceyKeys, ok := template.render(pricey) + require.True(t, ok) + assert.NotEqual(t, cheapKeys, priceyKeys) + + wantTags := []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // `{"upc":"1"}` — price is not in it + } + assert.Equal(t, wantTags, template.entityTags(cheap)) + assert.Equal(t, wantTags, template.entityTags(pricey)) + }) + + t.Run("argument variants of one entity share the entity tag", func(t *testing.T) { + // Two requests of the same entity differing only in an argument value: + // separate entries by design, one purge target. + representation := productRepresentation(t, "upc") + euro := cacheKeyTemplate{ + subgraph: "products", + prefix: "v1:products", + representation: representation, + args: "f123752fc2272dfc", + } + dollar := cacheKeyTemplate{ + subgraph: "products", + prefix: "v1:products", + representation: representation, + args: "b487e21691ea4c86", + } + item := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)) + + euroKeys, ok := euro.render(item) + require.True(t, ok) + dollarKeys, ok := dollar.render(item) + require.True(t, ok) + assert.NotEqual(t, euroKeys, dollarKeys) + + wantTags := []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // `{"upc":"1"}` — the args digest is not in it + } + assert.Equal(t, wantTags, euro.entityTags(item)) + assert.Equal(t, wantTags, dollar.entityTags(item)) + }) + + t.Run("private partitions of one entity share the entity tag", func(t *testing.T) { + // A tag must never carry identity material: purging an entity has to + // reach every requester's partition of it. + representation := productRepresentation(t, "upc") + public := cacheKeyTemplate{ + subgraph: "products", + prefix: "v1:products", + representation: representation, + } + userA := cacheKeyTemplate{ + subgraph: "products", + prefix: "v1:products", + representation: representation, + partition: sha256Hex("i:user-a"), + } + userB := cacheKeyTemplate{ + subgraph: "products", + prefix: "v1:products", + representation: representation, + partition: sha256Hex("i:user-b"), + } + item := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)) + + publicKeys, ok := public.render(item) + require.True(t, ok) + userAKeys, ok := userA.render(item) + require.True(t, ok) + userBKeys, ok := userB.render(item) + require.True(t, ok) + assert.NotEqual(t, publicKeys.L2, userAKeys.L2) + assert.NotEqual(t, userAKeys.L2, userBKeys.L2) + + wantTags := []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // `{"upc":"1"}` — no partition anywhere + } + assert.Equal(t, wantTags, public.entityTags(item)) + assert.Equal(t, wantTags, userA.entityTags(item)) + assert.Equal(t, wantTags, userB.entityTags(item)) + }) + + t.Run("a static node __typename tags under the name the fetch sends", func(t *testing.T) { + // An @interfaceObject target keys under the interface name, so its tags + // address the same name — one entity, one tag, whatever implementer the + // item claims to be. + node := mergedRepresentation(t, plan.FederationMetaData{ + InterfaceObjects: []plan.EntityInterfaceConfiguration{ + {InterfaceTypeName: "Sellable", ConcreteTypeNames: []string{"Product"}}, + }, + }, plan.FederationFieldConfiguration{TypeName: "Product", SelectionSet: "upc"}) + template := templateFor(t, node) + + wantTags := []string{ + "subgraph:products", + "type:products:Sellable", + "entity:products:Sellable:d3cc039c7a9789e7", // `{"upc":"1"}` + } + assert.Equal(t, wantTags, template.entityTags(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)))) + assert.Equal(t, wantTags, template.entityTags(astjson.MustParseBytes([]byte(`{"__typename":"Sellable","upc":"1"}`)))) + }) + + t.Run("a representation of @requires fields alone still carries the coarse tags", func(t *testing.T) { + // Nothing to address the entity by, but "purge this subgraph" and + // "purge this type" must keep working. + node := mergedRepresentation(t, plan.FederationMetaData{}, + plan.FederationFieldConfiguration{TypeName: "Product", FieldName: "shippingEstimate", SelectionSet: "price"}, + ) + assert.Equal(t, []string{ + "subgraph:products", + "type:products:Product", + }, templateFor(t, node).entityTags(astjson.MustParseBytes([]byte(`{"__typename":"Product","price":100}`)))) + }) + + t.Run("an item with no type to tag under yields no tags", func(t *testing.T) { + template := templateFor(t, productRepresentation(t, "upc")) + assert.Nil(t, template.entityTags(astjson.MustParseBytes([]byte(`{"upc":"1"}`)))) + assert.Nil(t, template.entityTags(nil)) + assert.Nil(t, cacheKeyTemplate{subgraph: "products"}.entityTags(astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)))) + }) + + t.Run("determinism: repeated derivation produces the identical ordered slice", func(t *testing.T) { + template := templateFor(t, productRepresentation(t, "upc", "price")) + item := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","price":100}`)) + assert.Equal(t, template.entityTags(item), template.entityTags(item)) + }) +} + +// TestRootFieldTags pins the root-field vocabulary: a whole-response entry is +// not one entity, so it carries the two coarse tags only, and its type is the +// coordinate's. +func TestRootFieldTags(t *testing.T) { + assert.Equal(t, []string{ + "subgraph:products", + "type:products:Query", + }, rootFieldTags(&resolve.FetchCacheConfig{ + SubgraphName: "products", + KeySpec: resolve.CacheKeySpec{Scope: resolve.CacheScopeRootField, TypeName: "Query", FieldName: "topProducts"}, + })) +} diff --git a/v2/pkg/engine/cache/cachetesting/fakes.go b/v2/pkg/engine/cache/cachetesting/fakes.go new file mode 100644 index 0000000000..7fad9b004b --- /dev/null +++ b/v2/pkg/engine/cache/cachetesting/fakes.go @@ -0,0 +1,755 @@ +// Package cachetesting provides the shared, cosmo-free test doubles for the +// caching implementation: a recording controller/request-cache pair, an +// in-memory L2 store with an ordered op log, a gate-channel datasource for +// deterministic ordering, and a registry that swaps real plan datasources for +// in-process fakes. Time and TTLs are never faked here — tests wrap +// time-dependent bodies in testing/synctest, which fakes the real time calls. +package cachetesting + +import ( + "cmp" + "context" + "maps" + "net/http" + "slices" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/datasource/httpclient" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// Call is one normalized cache-hook invocation recorded by FakeRequestCache, +// with every loader-supplied signal flattened for full-value assertions. +type Call struct { + Op string + FetchPath string + Items int + InputBytes string + HeaderHash uint64 + ResponseData string + MergePath []string + HasErrors bool + FetchFailed bool + EmptyEntity bool + StatusCode int + Decision resolve.Decision +} + +// ScriptedDecision is what FakeRequestCache returns for a fetch path. +type ScriptedDecision struct { + Decision resolve.Decision + Handle *resolve.FetchCacheHandle +} + +// StoreOp is one entry of FakeStore's ordered operation log: one op per store +// CALL, so a batched read logs a single entry carrying every key it asked for. +type StoreOp struct { + Kind string // "GetMany" or "SetMany" + // Keys are the keys a GetMany asked for, in call order. + Keys []string + // Hits is the per-key outcome of a GetMany, positionally aligned with Keys. + Hits []bool + // Items are the entries a SetMany wrote, in call order. + Items []StoreOpItem + // Failed marks a call the failure injection rejected: it touched no data. + Failed bool +} + +// StoreOpItem is one written entry inside a SetMany op. +type StoreOpItem struct { + Key string + Value string + TTL time.Duration + // Tags are the entry's invalidation tags, in write order. + Tags []string +} + +// FakeCacheController counts BeginRequest calls and hands out a fixed +// RequestCache, so lifecycle laziness (exactly one BeginRequest per request) +// is observable. +type FakeCacheController struct { + begins atomic.Int64 + rc resolve.RequestCache +} + +func NewFakeCacheController(rc resolve.RequestCache) *FakeCacheController { + return &FakeCacheController{rc: rc} +} + +func (f *FakeCacheController) BeginRequest(*resolve.Context) resolve.RequestCache { + f.begins.Add(1) + return f.rc +} + +// Begins returns how often BeginRequest ran. +func (f *FakeCacheController) Begins() int64 { + return f.begins.Load() +} + +// FakeRequestCache records every hook invocation as a normalized Call and +// returns scripted decisions keyed by the fetch's response path. It is safe +// for concurrent use (parallel fetches within one request). +type FakeRequestCache struct { + mu sync.Mutex + calls []Call + resultHandles []*resolve.FetchCacheHandle + script map[string]ScriptedDecision + errs map[string]error +} + +func NewFakeRequestCache(script map[string]ScriptedDecision) *FakeRequestCache { + return &FakeRequestCache{ + script: script, + errs: make(map[string]error), + } +} + +// SetError makes the given hook ("Skipped" or "Result") fail for a fetch path. +func (f *FakeRequestCache) SetError(fetchPath, op string, err error) { + f.mu.Lock() + defer f.mu.Unlock() + f.errs[fetchPath+op] = err +} + +func (f *FakeRequestCache) PrepareFetch(in resolve.PrepareFetchInput) (resolve.Decision, *resolve.FetchCacheHandle) { + path := pathOf(in.Item) + scripted := f.script[path] + f.record(Call{ + Op: "Prepare", + FetchPath: path, + Items: len(in.Items), + InputBytes: string(in.Input), + HeaderHash: in.HeaderHash, + Decision: scripted.Decision, + }) + return scripted.Decision, scripted.Handle +} + +// OnUncachedFetch records the loader's notification that a fetch ran with no +// cache configuration. It carries no fetch identity — the position in the call +// log is what an assertion reads. +func (f *FakeRequestCache) OnUncachedFetch() { + f.record(Call{Op: "Uncached"}) +} + +func (f *FakeRequestCache) OnFetchSkipped(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + path := pathOf(in.Item) + f.record(mergeCall("Skipped", path, in)) + return f.err(path, "Skipped") +} + +func (f *FakeRequestCache) OnFetchResult(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + path := pathOf(in.Item) + f.recordResultHandle(h) + f.record(mergeCall("Result", path, in)) + return f.err(path, "Result") +} + +func (f *FakeRequestCache) EndRequest() { + f.record(Call{Op: "End"}) +} + +// Calls returns a copy of the recorded calls in invocation order. +func (f *FakeRequestCache) Calls() []Call { + f.mu.Lock() + defer f.mu.Unlock() + return slices.Clone(f.calls) +} + +// ResultHandles returns the handles OnFetchResult received, in order, so tests +// can assert pointer identity with the handle PrepareFetch returned. +func (f *FakeRequestCache) ResultHandles() []*resolve.FetchCacheHandle { + f.mu.Lock() + defer f.mu.Unlock() + return slices.Clone(f.resultHandles) +} + +func (f *FakeRequestCache) record(call Call) { + f.mu.Lock() + defer f.mu.Unlock() + f.calls = append(f.calls, call) +} + +func (f *FakeRequestCache) recordResultHandle(h *resolve.FetchCacheHandle) { + f.mu.Lock() + defer f.mu.Unlock() + f.resultHandles = append(f.resultHandles, h) +} + +func (f *FakeRequestCache) err(path, op string) error { + f.mu.Lock() + defer f.mu.Unlock() + return f.errs[path+op] +} + +// RecordingController bundles a FakeCacheController with its FakeRequestCache +// for the common "one recording cache per test" case. +type RecordingController struct { + controller *FakeCacheController + request *FakeRequestCache +} + +func NewRecordingController(script map[string]ScriptedDecision) *RecordingController { + request := NewFakeRequestCache(script) + return &RecordingController{ + controller: NewFakeCacheController(request), + request: request, + } +} + +func (r *RecordingController) BeginRequest(ctx *resolve.Context) resolve.RequestCache { + return r.controller.BeginRequest(ctx) +} + +func (r *RecordingController) Calls() []Call { + return r.request.Calls() +} + +func (r *RecordingController) Begins() int64 { + return r.controller.Begins() +} + +func (r *RecordingController) ResultHandles() []*resolve.FetchCacheHandle { + return r.request.ResultHandles() +} + +// StoredEntry is one FakeStore value with its absolute expiry. +type StoredEntry struct { + Value []byte + ExpiresAt time.Time +} + +// FakeStore is the in-memory L2 store double implementing cache.Store: values +// with absolute ExpiresAt (real time.Now, faked by synctest in tests), an +// ordered StoreOp log with ONE entry per call, and per-op failure injection. +// A read past expiry is a miss; expired entries are not purged, so the log +// stays complete. +type FakeStore struct { + mu sync.Mutex + data map[string]StoredEntry + ops []StoreOp + + failGetMany int + failGetManyErr error + failSetMany int + failSetManyErr error +} + +func NewFakeStore() *FakeStore { + return &FakeStore{data: make(map[string]StoredEntry)} +} + +// Seed inserts a value WITHOUT logging an op, for arranging preconditions. +func (s *FakeStore) Seed(key string, v []byte, ttl time.Duration) { + s.mu.Lock() + defer s.mu.Unlock() + s.data[key] = StoredEntry{ + Value: slices.Clone(v), + ExpiresAt: time.Now().Add(ttl), + } +} + +// FailGetMany makes the next n reads fail with err WITHOUT touching the data; +// the calls still log, marked Failed. +func (s *FakeStore) FailGetMany(n int, err error) { + s.mu.Lock() + defer s.mu.Unlock() + s.failGetMany, s.failGetManyErr = n, err +} + +// FailSetMany makes the next n writes fail with err WITHOUT touching the data; +// the calls still log, marked Failed. +func (s *FakeStore) FailSetMany(n int, err error) { + s.mu.Lock() + defer s.mu.Unlock() + s.failSetMany, s.failSetManyErr = n, err +} + +// GetMany answers one Entry per key, in key order. +func (s *FakeStore) GetMany(_ context.Context, keys []string) ([]cache.Entry, error) { + s.mu.Lock() + defer s.mu.Unlock() + if s.failGetMany > 0 { + s.failGetMany-- + s.ops = append(s.ops, StoreOp{Kind: "GetMany", Keys: slices.Clone(keys), Failed: true}) + return nil, s.failGetManyErr + } + entries := make([]cache.Entry, len(keys)) + hits := make([]bool, len(keys)) + for i, key := range keys { + entry, ok := s.data[key] + if !ok || !time.Now().Before(entry.ExpiresAt) { + continue + } + entries[i] = cache.Entry{ + Value: slices.Clone(entry.Value), + RemainingTTL: time.Until(entry.ExpiresAt), + OK: true, + } + hits[i] = true + } + s.ops = append(s.ops, StoreOp{Kind: "GetMany", Keys: slices.Clone(keys), Hits: hits}) + return entries, nil +} + +// SetMany writes every item under its own TTL. +func (s *FakeStore) SetMany(_ context.Context, items []cache.Item) error { + s.mu.Lock() + defer s.mu.Unlock() + op := StoreOp{Kind: "SetMany", Items: make([]StoreOpItem, 0, len(items))} + for _, item := range items { + op.Items = append(op.Items, StoreOpItem{ + Key: item.Key, + Value: string(item.Value), + TTL: item.TTL, + Tags: slices.Clone(item.Tags), + }) + } + if s.failSetMany > 0 { + s.failSetMany-- + op.Failed = true + s.ops = append(s.ops, op) + return s.failSetManyErr + } + for _, item := range items { + s.data[item.Key] = StoredEntry{ + Value: slices.Clone(item.Value), + ExpiresAt: time.Now().Add(item.TTL), + } + } + s.ops = append(s.ops, op) + return nil +} + +// Value returns the stored value under key and whether it is present and +// unexpired, WITHOUT logging an op, so assertions can read the store directly. +func (s *FakeStore) Value(key string) ([]byte, bool) { + s.mu.Lock() + defer s.mu.Unlock() + entry, ok := s.data[key] + if !ok || !time.Now().Before(entry.ExpiresAt) { + return nil, false + } + return slices.Clone(entry.Value), true +} + +// Ops returns a copy of the ordered operation log. +func (s *FakeStore) Ops() []StoreOp { + s.mu.Lock() + defer s.mu.Unlock() + return slices.Clone(s.ops) +} + +// ResetOps clears the operation log (the DATA stays), so a multi-request test +// can assert each request's ops in isolation instead of re-listing the +// accumulated history. +func (s *FakeStore) ResetOps() { + s.mu.Lock() + defer s.mu.Unlock() + s.ops = nil +} + +// GatedDataSource is an in-process DataSource whose Load can be ordered +// deterministically with gate channels: it announces arrival on Arrived, then +// blocks until Release yields, then returns Resp/Err. Nil channels skip the +// respective step. Tests coordinate the channels with synctest.Wait — never +// with latency sleeps. +type GatedDataSource struct { + Name string + Resp []byte + Err error + Arrived chan<- string + Release <-chan struct{} + LoadCounter *atomic.Int64 + // RecordInput (optional) receives every Load's input bytes, so tests can + // assert the EXACT request the subgraph saw (e.g. partial-batch filtering). + RecordInput func(input []byte) +} + +// DataSourceGate is the per-fetch gate configuration FakeRegistry attaches to +// a swapped datasource. +type DataSourceGate struct { + Arrived chan<- string + Release <-chan struct{} +} + +func (g *GatedDataSource) Load(ctx context.Context, headers http.Header, input []byte) ([]byte, error) { + if g.LoadCounter != nil { + g.LoadCounter.Add(1) + } + if g.RecordInput != nil { + g.RecordInput(input) // the recorder copies (string conversion) only while under its cap + } + if g.Arrived != nil { + g.Arrived <- g.Name + } + if g.Release != nil { + <-g.Release + } + return g.Resp, g.Err +} + +func (g *GatedDataSource) LoadWithFiles(context.Context, http.Header, []byte, []*httpclient.FileUpload) ([]byte, error) { + panic("cache tests never upload files") +} + +// ShadowCompare is one recorded shadow probe: the stashed entry's key, its +// age (CacheTTL - RemainingTTL), and whether the cached bytes equal the fresh +// value the fetch produced for that item. +type ShadowCompare struct { + CacheKey string + IsFresh bool + CacheAge time.Duration +} + +// RecordingObserver is the CacheObserver double: it counts lifecycle calls, +// records the handles it sees, and materializes shadow compares (byte +// equality of stashed vs fresh, per item). +type RecordingObserver struct { + mu sync.Mutex + beginRequests int + endRequests int + observedHandles []*resolve.FetchCacheHandle + compares []ShadowCompare + storeErrors []cache.StoreError + // uncacheablePrivate records the private results that stayed out of the + // store, one entry per occurrence. + uncacheablePrivate []cache.UncacheablePrivate + // scopeMismatches counts entries discarded for carrying the other privacy + // scope, per subgraph and stored scope. + scopeMismatches map[cache.ScopeMismatch]int +} + +func (o *RecordingObserver) BeginRequest(ctx *resolve.Context) { + o.mu.Lock() + defer o.mu.Unlock() + o.beginRequests++ +} + +func (o *RecordingObserver) EndRequest(ctx *resolve.Context) { + o.mu.Lock() + defer o.mu.Unlock() + o.endRequests++ +} + +func (o *RecordingObserver) OnFetchObserved(h *resolve.FetchCacheHandle) { + o.mu.Lock() + defer o.mu.Unlock() + o.observedHandles = append(o.observedHandles, h) +} + +func (o *RecordingObserver) CompareShadow(h *resolve.FetchCacheHandle, fresh *astjson.Value, tx *resolve.CacheTransaction) { + if h == nil { + return + } + var batch []*astjson.Value + if h.BatchEntityKey && fresh != nil { + batch = fresh.GetArray() + } + compares := make([]ShadowCompare, 0, len(h.ShadowStash)) + for itemIndex, entry := range h.ShadowStash { + freshValue := fresh + if h.BatchEntityKey { + freshValue = nil + if itemIndex >= 0 && itemIndex < len(h.Items) { + if batchIndex := h.Items[itemIndex].BatchIndex; batchIndex >= 0 && batchIndex < len(batch) { + freshValue = batch[batchIndex] + } + } + } + compares = append(compares, ShadowCompare{ + CacheKey: entry.CacheKey, + IsFresh: string(marshalValue(entry.CachedValue)) == string(marshalValue(freshValue)), + CacheAge: entry.CacheTTL - entry.RemainingTTL, + }) + } + slices.SortFunc(compares, func(a, b ShadowCompare) int { + return cmp.Compare(a.CacheKey, b.CacheKey) + }) + o.mu.Lock() + defer o.mu.Unlock() + o.compares = append(o.compares, compares...) +} + +func marshalValue(v *astjson.Value) []byte { + if v == nil { + return nil + } + return v.MarshalTo(nil) +} + +// OnStoreError records one reported store failure. +func (o *RecordingObserver) OnStoreError(op string, subgraph string, keyCount int, err error) { + o.mu.Lock() + defer o.mu.Unlock() + o.storeErrors = append(o.storeErrors, cache.StoreError{ + Op: op, + Subgraph: subgraph, + KeyCount: keyCount, + Err: err, + }) +} + +// OnUncacheablePrivate records one private result the store never received. +func (o *RecordingObserver) OnUncacheablePrivate(subgraph string, reason string) { + o.mu.Lock() + defer o.mu.Unlock() + o.uncacheablePrivate = append(o.uncacheablePrivate, cache.UncacheablePrivate{ + Subgraph: subgraph, + Reason: reason, + }) +} + +// UncacheablePrivate returns the recorded private results the store never +// received, in occurrence order. +func (o *RecordingObserver) UncacheablePrivate() []cache.UncacheablePrivate { + o.mu.Lock() + defer o.mu.Unlock() + return slices.Clone(o.uncacheablePrivate) +} + +// OnScopeMismatch counts one entry discarded for carrying the other privacy +// scope. +func (o *RecordingObserver) OnScopeMismatch(subgraph string, storedScope string) { + o.mu.Lock() + defer o.mu.Unlock() + if o.scopeMismatches == nil { + o.scopeMismatches = make(map[cache.ScopeMismatch]int) + } + o.scopeMismatches[cache.ScopeMismatch{Subgraph: subgraph, StoredScope: storedScope}]++ +} + +// ScopeMismatches returns the discarded-entry counts per subgraph and stored +// scope. +func (o *RecordingObserver) ScopeMismatches() map[cache.ScopeMismatch]int { + o.mu.Lock() + defer o.mu.Unlock() + return maps.Clone(o.scopeMismatches) +} + +// StoreErrors returns the recorded store failures in occurrence order. +func (o *RecordingObserver) StoreErrors() []cache.StoreError { + o.mu.Lock() + defer o.mu.Unlock() + return slices.Clone(o.storeErrors) +} + +func (o *RecordingObserver) OnEntity(h *resolve.FetchCacheHandle, entity *astjson.Value) {} + +func (o *RecordingObserver) OnFieldValue(coordinate resolve.GraphCoordinate, value resolve.FieldValue) { +} + +// Counts returns (beginRequests, endRequests). +func (o *RecordingObserver) Counts() (int, int) { + o.mu.Lock() + defer o.mu.Unlock() + return o.beginRequests, o.endRequests +} + +// ObservedHandles returns the handles passed to OnFetchObserved, in order. +func (o *RecordingObserver) ObservedHandles() []*resolve.FetchCacheHandle { + o.mu.Lock() + defer o.mu.Unlock() + return slices.Clone(o.observedHandles) +} + +// Compares returns the recorded shadow probes, sorted by cache key per call. +func (o *RecordingObserver) Compares() []ShadowCompare { + o.mu.Lock() + defer o.mu.Unlock() + return slices.Clone(o.compares) +} + +// FakeRegistry hands out GatedDataSources with canned responses and tracks +// per-fetch load counts, so tests can assert "no network on a hit" without a +// socket. +type FakeRegistry struct { + mu sync.Mutex + responses map[string]string + release chan struct{} + loads map[string]*atomic.Int64 + gates map[string]DataSourceGate + inputs map[string][]string +} + +// NewFakeRegistry builds a registry over canned responses. Response keys are +// tried in order: "DataSourceName:ResponsePath", "DataSourceName", +// "ResponsePath", "*". +func NewFakeRegistry(responses map[string]string) *FakeRegistry { + release := make(chan struct{}) + close(release) // ungated by default: Load returns immediately + return &FakeRegistry{ + responses: responses, + release: release, + loads: make(map[string]*atomic.Int64), + } +} + +// SetGate attaches gate channels to the datasource identified by name + path; +// call it before SwapDataSources. +func (r *FakeRegistry) SetGate(name, path string, gate DataSourceGate) { + key := name + ":" + path + r.mu.Lock() + defer r.mu.Unlock() + if r.gates == nil { + r.gates = make(map[string]DataSourceGate) + } + r.gates[key] = gate +} + +// SwapDataSources walks a fetch tree and replaces every fetch's transport with +// a registry-backed GatedDataSource (via Fetch.SetDataSource — no switch over +// concrete fetch types). +func SwapDataSources(node *resolve.FetchTreeNode, reg *FakeRegistry) { + if node == nil || reg == nil { + return + } + if node.Item != nil && node.Item.Fetch != nil { + node.Item.Fetch.SetDataSource(reg.dataSourceFor(node.Item)) + } + for _, child := range node.ChildNodes { + SwapDataSources(child, reg) + } +} + +// LoadCount returns how often the datasource identified by name + path +// loaded, or -1 when no such datasource was ever swapped in (counters are +// created eagerly at swap time) — a typo'd name/path pair can then never +// satisfy a zero-loads assertion vacuously. +func (r *FakeRegistry) LoadCount(name, path string) int64 { + key := name + ":" + path + r.mu.Lock() + defer r.mu.Unlock() + counter := r.loads[key] + if counter == nil { + return -1 + } + return counter.Load() +} + +// Inputs returns the exact input bytes every Load of the datasource +// identified by name + path received, in order. An unknown pair returns nil — +// assert LoadCount alongside when "no inputs" is the expectation. +func (r *FakeRegistry) Inputs(name, path string) []string { + r.mu.Lock() + defer r.mu.Unlock() + return slices.Clone(r.inputs[name+":"+path]) +} + +// maxRecordedInputs bounds per-datasource input recording so long-running +// callers (benchmarks) do not accumulate unbounded copies; assertions read +// the first loads, which is what the e2e rows need. +const maxRecordedInputs = 16 + +func (r *FakeRegistry) recordInput(key string) func([]byte) { + return func(input []byte) { + r.mu.Lock() + defer r.mu.Unlock() + if len(r.inputs[key]) >= maxRecordedInputs { + return + } + if r.inputs == nil { + r.inputs = make(map[string][]string) + } + r.inputs[key] = append(r.inputs[key], string(input)) + } +} + +func (r *FakeRegistry) dataSourceFor(item *resolve.FetchItem) resolve.DataSource { + name := dataSourceName(item) + path := pathOf(item) + resp := r.responseFor(name, path) + gate := r.gateFor(name, path) + var release <-chan struct{} = r.release + if gate.Release != nil { + release = gate.Release + } + return &GatedDataSource{ + Name: name, + Resp: []byte(resp), + Arrived: gate.Arrived, + Release: release, + LoadCounter: r.loadCounter(name, path), + RecordInput: r.recordInput(name + ":" + path), + } +} + +func (r *FakeRegistry) gateFor(name, path string) DataSourceGate { + key := name + ":" + path + r.mu.Lock() + defer r.mu.Unlock() + return r.gates[key] +} + +func (r *FakeRegistry) loadCounter(name, path string) *atomic.Int64 { + key := name + ":" + path + r.mu.Lock() + defer r.mu.Unlock() + counter := r.loads[key] + if counter == nil { + counter = &atomic.Int64{} + r.loads[key] = counter + } + return counter +} + +func (r *FakeRegistry) responseFor(name, path string) string { + keys := []string{name + ":" + path, name, path, "*"} + for _, key := range keys { + if value, ok := r.responses[key]; ok { + return value + } + } + return "" +} + +// Compact normalizes a JSON string for full-value response assertions. +func Compact(tb testing.TB, s string) string { + tb.Helper() + v, err := astjson.ParseBytes([]byte(s)) + if err != nil { + tb.Fatalf("compact json: %v", err) + } + return string(v.MarshalTo(nil)) +} + +func pathOf(item *resolve.FetchItem) string { + if item == nil { + return "" + } + return item.ResponsePath +} + +func dataSourceName(item *resolve.FetchItem) string { + if item == nil || item.Fetch == nil || item.Fetch.FetchInfo() == nil { + return "" + } + return item.Fetch.FetchInfo().DataSourceName +} + +func mergeCall(op, path string, in resolve.MergeInput) Call { + return Call{ + Op: op, + FetchPath: path, + Items: len(in.Items), + ResponseData: string(valueBytes(in.ResponseData)), + MergePath: slices.Clone(in.MergePath), + HasErrors: in.HasErrors, + FetchFailed: in.FetchFailed, + EmptyEntity: in.EmptyEntity, + StatusCode: in.StatusCode, + } +} + +func valueBytes(v *astjson.Value) []byte { + if v == nil { + return nil + } + return v.MarshalTo(nil) +} diff --git a/v2/pkg/engine/cache/cachetesting/fakes_test.go b/v2/pkg/engine/cache/cachetesting/fakes_test.go new file mode 100644 index 0000000000..888ed47e74 --- /dev/null +++ b/v2/pkg/engine/cache/cachetesting/fakes_test.go @@ -0,0 +1,304 @@ +package cachetesting + +import ( + "errors" + "sync/atomic" + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// TestFakeStoreTTLExpiry proves TTL semantics against the real clock inside a +// synctest bubble: a value is served before its TTL and is a miss after the +// bubble's fake time passes it, with the full op log recorded — one entry per +// call, carrying every key and its hit outcome. +func TestFakeStoreTTLExpiry(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := NewFakeStore() + require.NoError(t, store.SetMany(t.Context(), []cache.Item{ + {Key: "product:1", Value: []byte(`{"name":"Table"}`), TTL: time.Second}, + {Key: "product:2", Value: []byte(`{"name":"Chair"}`), TTL: time.Minute}, + })) + + entries, err := store.GetMany(t.Context(), []string{"product:1", "product:2"}) + require.NoError(t, err) + assert.Equal(t, []cache.Entry{ + {Value: []byte(`{"name":"Table"}`), RemainingTTL: time.Second, OK: true}, + {Value: []byte(`{"name":"Chair"}`), RemainingTTL: time.Minute, OK: true}, + }, entries) + + time.Sleep(2 * time.Second) // advances fake time past product:1's TTL + + entries, err = store.GetMany(t.Context(), []string{"product:1", "product:2"}) + require.NoError(t, err) + assert.Equal(t, []cache.Entry{ + {}, + {Value: []byte(`{"name":"Chair"}`), RemainingTTL: 58 * time.Second, OK: true}, + }, entries) + + assert.Equal(t, []StoreOp{ + { + Kind: "SetMany", + Items: []StoreOpItem{ + {Key: "product:1", Value: `{"name":"Table"}`, TTL: time.Second}, + {Key: "product:2", Value: `{"name":"Chair"}`, TTL: time.Minute}, + }, + }, + { + Kind: "GetMany", + Keys: []string{"product:1", "product:2"}, + Hits: []bool{true, true}, + }, + { + Kind: "GetMany", + Keys: []string{"product:1", "product:2"}, + Hits: []bool{false, true}, + }, + }, store.Ops()) + }) +} + +// TestFakeStoreSeedDoesNotLog pins that Seed arranges state without polluting +// the op log. +func TestFakeStoreSeedDoesNotLog(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := NewFakeStore() + store.Seed("user:1", []byte(`{"username":"me"}`), time.Minute) + + entries, err := store.GetMany(t.Context(), []string{"user:1"}) + require.NoError(t, err) + assert.Equal(t, []cache.Entry{ + {Value: []byte(`{"username":"me"}`), RemainingTTL: time.Minute, OK: true}, + }, entries) + assert.Equal(t, []StoreOp{ + { + Kind: "GetMany", + Keys: []string{"user:1"}, + Hits: []bool{true}, + }, + }, store.Ops()) + }) +} + +// TestFakeStoreFailureInjection pins the injection knobs: exactly the next N +// calls fail, they touch no data, they still log (marked Failed), and the call +// after the budget behaves normally again. +func TestFakeStoreFailureInjection(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := NewFakeStore() + store.Seed("product:1", []byte(`{"name":"Table"}`), time.Minute) + readErr := errors.New("store read down") + writeErr := errors.New("store write down") + store.FailGetMany(1, readErr) + store.FailSetMany(1, writeErr) + + entries, err := store.GetMany(t.Context(), []string{"product:1"}) + assert.Equal(t, readErr, err) + assert.Nil(t, entries) + + assert.Equal(t, writeErr, store.SetMany(t.Context(), []cache.Item{ + {Key: "product:2", Value: []byte(`{"name":"Chair"}`), TTL: time.Minute}, + })) + _, stored := store.Value("product:2") + assert.False(t, stored) // the failed write touched no data + + // The budget is spent: both ops work again. + entries, err = store.GetMany(t.Context(), []string{"product:1"}) + require.NoError(t, err) + assert.Equal(t, []cache.Entry{ + {Value: []byte(`{"name":"Table"}`), RemainingTTL: time.Minute, OK: true}, + }, entries) + require.NoError(t, store.SetMany(t.Context(), []cache.Item{ + {Key: "product:2", Value: []byte(`{"name":"Chair"}`), TTL: time.Minute}, + })) + value, stored := store.Value("product:2") + require.True(t, stored) + assert.Equal(t, []byte(`{"name":"Chair"}`), value) + + assert.Equal(t, []StoreOp{ + { + Kind: "GetMany", + Keys: []string{"product:1"}, + Failed: true, + }, + { + Kind: "SetMany", + Items: []StoreOpItem{ + {Key: "product:2", Value: `{"name":"Chair"}`, TTL: time.Minute}, + }, + Failed: true, + }, + { + Kind: "GetMany", + Keys: []string{"product:1"}, + Hits: []bool{true}, + }, + { + Kind: "SetMany", + Items: []StoreOpItem{ + {Key: "product:2", Value: `{"name":"Chair"}`, TTL: time.Minute}, + }, + }, + }, store.Ops()) + }) +} + +// TestGatedDataSourceOrdering proves the gate semantics: Load announces +// arrival, blocks until released (observable via synctest.Wait, never via +// latency), and then returns the canned response. +func TestGatedDataSourceOrdering(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + arrived := make(chan string, 1) + release := make(chan struct{}) + counter := &atomic.Int64{} + ds := &GatedDataSource{ + Name: "products", + Resp: []byte(`{"data":{}}`), + Arrived: arrived, + Release: release, + LoadCounter: counter, + } + + var done atomic.Bool + var out []byte + var err error + go func() { + out, err = ds.Load(t.Context(), nil, []byte(`{}`)) + done.Store(true) + }() + + synctest.Wait() + assert.Equal(t, "products", <-arrived) + assert.Equal(t, int64(1), counter.Load()) + assert.False(t, done.Load()) // still gated + + close(release) + synctest.Wait() + assert.True(t, done.Load()) + require.NoError(t, err) + assert.Equal(t, []byte(`{"data":{}}`), out) + }) +} + +// TestFakeRequestCacheRecordsCalls pins the full normalized Call log across +// all four hooks, including scripted decisions and the merge-path carrier. +func TestFakeRequestCacheRecordsCalls(t *testing.T) { + handle := &resolve.FetchCacheHandle{Decision: resolve.DecisionSkipFullHit} + fake := NewFakeRequestCache(map[string]ScriptedDecision{ + "topProducts": {Decision: resolve.DecisionSkipFullHit, Handle: handle}, + }) + + item := &resolve.FetchItem{ResponsePath: "topProducts"} + items := []*astjson.Value{astjson.MustParseBytes([]byte(`{"upc":"1"}`))} + + decision, gotHandle := fake.PrepareFetch(resolve.PrepareFetchInput{ + Item: item, + Items: items, + Input: []byte(`{"query":"{topProducts{upc}}"}`), + HeaderHash: 42, + }) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.Same(t, handle, gotHandle) + + responseData := astjson.MustParseBytes([]byte(`{"topProducts":[{"upc":"1"}]}`)) + require.NoError(t, fake.OnFetchSkipped(handle, resolve.MergeInput{ + Item: item, + Items: items, + })) + require.NoError(t, fake.OnFetchResult(handle, resolve.MergeInput{ + Item: item, + Items: items, + ResponseData: responseData, + MergePath: []string{"nested"}, + HasErrors: true, + FetchFailed: true, + EmptyEntity: true, + StatusCode: 500, + })) + fake.EndRequest() + + assert.Equal(t, []Call{ + { + Op: "Prepare", + FetchPath: "topProducts", + Items: 1, + InputBytes: `{"query":"{topProducts{upc}}"}`, + HeaderHash: 42, + Decision: resolve.DecisionSkipFullHit, + }, + { + Op: "Skipped", + FetchPath: "topProducts", + Items: 1, + }, + { + Op: "Result", + FetchPath: "topProducts", + Items: 1, + ResponseData: `{"topProducts":[{"upc":"1"}]}`, + MergePath: []string{"nested"}, + HasErrors: true, + FetchFailed: true, + EmptyEntity: true, + StatusCode: 500, + }, + {Op: "End"}, + }, fake.Calls()) + + assert.Equal(t, []*resolve.FetchCacheHandle{handle}, fake.ResultHandles()) +} + +// TestFakeRegistrySwapDataSources pins the response-key fallback order and the +// per-fetch load counting of swapped datasources. +func TestFakeRegistrySwapDataSources(t *testing.T) { + reg := NewFakeRegistry(map[string]string{ + "products:topProducts": `{"data":{"topProducts":[]}}`, + "reviews": `{"data":{"_entities":[]}}`, + "*": `{"data":{}}`, + }) + + single := &resolve.SingleFetch{ + Info: &resolve.FetchInfo{DataSourceName: "products"}, + } + entity := &resolve.EntityFetch{ + Info: &resolve.FetchInfo{DataSourceName: "reviews"}, + } + other := &resolve.BatchEntityFetch{ + Info: &resolve.FetchInfo{DataSourceName: "inventory"}, + } + tree := &resolve.FetchTreeNode{ + Kind: resolve.FetchTreeNodeKindSequence, + ChildNodes: []*resolve.FetchTreeNode{ + {Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: single, ResponsePath: "topProducts"}}, + {Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: entity, ResponsePath: "topProducts.reviews"}}, + {Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: other, ResponsePath: "other"}}, + }, + } + SwapDataSources(tree, reg) + + load := func(ds resolve.DataSource) string { + t.Helper() + out, err := ds.Load(t.Context(), nil, nil) + require.NoError(t, err) + return string(out) + } + + assert.Equal(t, `{"data":{"topProducts":[]}}`, load(single.FetchConfiguration.DataSource)) // name:path key + assert.Equal(t, `{"data":{"_entities":[]}}`, load(entity.DataSource)) // name key + assert.Equal(t, `{"data":{}}`, load(other.DataSource)) // "*" fallback + + assert.Equal(t, int64(1), reg.LoadCount("products", "topProducts")) + assert.Equal(t, int64(1), reg.LoadCount("reviews", "topProducts.reviews")) + assert.Equal(t, int64(1), reg.LoadCount("inventory", "other")) + // A never-swapped name/path pair is -1, never 0: a typo cannot satisfy a + // zero-loads assertion vacuously. + assert.Equal(t, int64(-1), reg.LoadCount("products", "unknown")) +} diff --git a/v2/pkg/engine/cache/cachetesting/realish.go b/v2/pkg/engine/cache/cachetesting/realish.go new file mode 100644 index 0000000000..77c6d08003 --- /dev/null +++ b/v2/pkg/engine/cache/cachetesting/realish.go @@ -0,0 +1,14 @@ +package cachetesting + +import ( + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// NewRealishCache builds the REAL cache controller over the in-memory +// FakeStore, for end-to-end rows that exercise actual lookup/write behavior +// instead of scripted decisions. obs may be nil; options carry the runtime +// knobs (cache.WithGlobalConfig). +func NewRealishCache(store *FakeStore, obs resolve.CacheObserver, options ...cache.ControllerOption) resolve.CacheController { + return cache.NewController(store, obs, options...) +} diff --git a/v2/pkg/engine/cache/configure_caching.go b/v2/pkg/engine/cache/configure_caching.go new file mode 100644 index 0000000000..a967768e6b --- /dev/null +++ b/v2/pkg/engine/cache/configure_caching.go @@ -0,0 +1,53 @@ +// Package cache is the ONE common home for all cache logic: the plan-side +// postprocess passes (key building, fetch config assembly, L1 narrowing) and +// the runtime request-cache controller. The resolve package holds only the +// contract types and never imports this package; plan/postprocess hold only +// thin shims calling into it. +package cache + +import ( + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// Configurator orchestrates the caching postprocess passes over finished fetch +// trees. It is constructed once per postprocess.Processor and holds the SINGLE +// planner no-op gate: with no caching configuration, ConfigureCaching returns +// immediately and no fetch is ever touched. +type Configurator struct { + caching *cacheconfig.CachingConfiguration + configurator *fetchCacheConfigurator + l1 *optimizeL1Cache +} + +// NewConfigurator builds the caching pass pipeline from the caching +// configuration (nil = caching off); its per-subgraph overrides are keyed by +// datasource ID. Nothing else is needed: entity cache keys derive from the +// fetches' own representation nodes, so no federation metadata and no schema +// reach the caching passes. +func NewConfigurator(caching *cacheconfig.CachingConfiguration) *Configurator { + return &Configurator{ + caching: caching, + configurator: &fetchCacheConfigurator{caching: caching}, + l1: &optimizeL1Cache{}, + } +} + +// ConfigureCaching runs the caching passes over one response's fetch trees: +// fetchCacheConfigurator sets the per-fetch *resolve.FetchCacheConfig, then +// optimizeL1Cache narrows cfg.L1 across all trees. It must run AFTER +// createConcreteSingleFetchTypes (the concrete fetch types carry the config) +// and, in the defer pipeline, AFTER buildDeferTree. treeParents gives the +// narrowing pass the defer-group ancestry — per tree, the index of the tree +// whose group ENCLOSES it, -1 for a root; nil means only root-before-defers +// ordering is assumed. +func (c *Configurator) ConfigureCaching(response *resolve.GraphQLResponse, treeParents []int, trees ...*resolve.FetchTreeNode) { + if c.caching == nil { + // The single planner no-op gate: no caching configured, nothing runs. + return + } + for _, tree := range trees { + c.configurator.configureTree(response, tree) + } + c.l1.optimize(trees, treeParents) +} diff --git a/v2/pkg/engine/cache/configure_caching_test.go b/v2/pkg/engine/cache/configure_caching_test.go new file mode 100644 index 0000000000..651cb7011c --- /dev/null +++ b/v2/pkg/engine/cache/configure_caching_test.go @@ -0,0 +1,72 @@ +package cache + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// fetchTreeFixture builds a small flat fetch tree with one single fetch and +// one entity fetch, mirroring what the caching passes receive from postprocess. +func fetchTreeFixture() *resolve.FetchTreeNode { + return &resolve.FetchTreeNode{ + Kind: resolve.FetchTreeNodeKindSequence, + ChildNodes: []*resolve.FetchTreeNode{ + { + Kind: resolve.FetchTreeNodeKindSingle, + Item: &resolve.FetchItem{ + Fetch: &resolve.SingleFetch{ + FetchDependencies: resolve.FetchDependencies{FetchID: 1}, + Info: &resolve.FetchInfo{ + DataSourceID: "products", + DataSourceName: "products", + }, + }, + }, + }, + { + Kind: resolve.FetchTreeNodeKindSingle, + Item: &resolve.FetchItem{ + Fetch: &resolve.EntityFetch{ + FetchDependencies: resolve.FetchDependencies{FetchID: 2, DependsOnFetchIDs: []int{1}}, + Info: &resolve.FetchInfo{ + DataSourceID: "reviews", + DataSourceName: "reviews", + }, + }, + }, + }, + }, + } +} + +// TestConfigureCachingNoOpGate pins the single planner no-op gate: with no +// caching configuration, ConfigureCaching leaves the fetch tree +// byte-identical and stamps no config; a configuration that enables nothing +// leaves it untouched as well. +func TestConfigureCachingNoOpGate(t *testing.T) { + t.Run("no caching configuration", func(t *testing.T) { + c := NewConfigurator(nil) + tree := fetchTreeFixture() + response := &resolve.GraphQLResponse{Fetches: tree} + c.ConfigureCaching(response, nil, tree) + assert.Equal(t, fetchTreeFixture(), tree) + assert.Nil(t, tree.ChildNodes[0].Item.Fetch.CacheConfig()) + assert.Nil(t, tree.ChildNodes[1].Item.Fetch.CacheConfig()) + }) + + t.Run("a configuration enabling nothing stamps no config", func(t *testing.T) { + c := NewConfigurator(&cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{"products": {}}, + }) + tree := fetchTreeFixture() + response := &resolve.GraphQLResponse{Fetches: tree} + c.ConfigureCaching(response, nil, tree) + assert.Equal(t, fetchTreeFixture(), tree) + assert.Nil(t, tree.ChildNodes[0].Item.Fetch.CacheConfig()) + assert.Nil(t, tree.ChildNodes[1].Item.Fetch.CacheConfig()) + }) +} diff --git a/v2/pkg/engine/cache/controller.go b/v2/pkg/engine/cache/controller.go new file mode 100644 index 0000000000..43a4dea308 --- /dev/null +++ b/v2/pkg/engine/cache/controller.go @@ -0,0 +1,1058 @@ +package cache + +import ( + "context" + "fmt" + "time" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// Item is one entry to write: the key, the encoded value envelope, the TTL the +// entry is written with, and the tags the store indexes it under for +// invalidation. +type Item struct { + Key string + Value []byte + TTL time.Duration + // Tags are the entry's invalidation addresses, coarsest first: every write + // carries "subgraph:{subgraph}" and "type:{subgraph}:{TypeName}", an entity + // entry additionally "entity:{subgraph}:{TypeName}:{digest of its @key + // fields}", shared by every variant of that entity. The three forms are + // stable API for an invalidation endpoint and a tag-purging CDN; the slice + // is open for user-defined tags. Tags live on the Item alone and never + // inside the stored value: index maintenance and delete-by-tag are the + // store's business. + Tags []string +} + +// Entry is one store read result, positionally aligned with the key it was +// requested under. OK reports whether the key was present; RemainingTTL is the +// entry's remaining freshness, 0 when the store cannot report one. +type Entry struct { + Value []byte + RemainingTTL time.Duration + OK bool +} + +// Store is the batched L2 backend the controller talks to: ONE GetMany per +// fetch and ONE SetMany per request. GetMany must return exactly one Entry per +// requested key, in key order. Implementations must be safe for concurrent use +// (the controller calls them from parallel fetch hooks, under the request's +// DataBuffer.Lock) and never need to fail a request — the controller turns a +// GetMany error into misses and drops the writes of a failed SetMany. +type Store interface { + GetMany(ctx context.Context, keys []string) ([]Entry, error) + SetMany(ctx context.Context, items []Item) error +} + +// Controller is the long-lived cache lifecycle port (implements +// resolve.CacheController): one per integrator/cache instance, holding only +// immutable collaborators. All per-request mutable state lives on the +// requestCache BeginRequest hands out. +type Controller struct { + store Store + obs resolve.CacheObserver + // global carries the runtime knobs of the configuration cascade's global + // level — the two client-header emission switches. Unset means the + // defaults: the client cache answer is computed, the CDN tag union is not. + global cacheconfig.GlobalCacheConfig +} + +// ControllerOption configures the long-lived controller. +type ControllerOption func(*Controller) + +// WithGlobalConfig hands the controller the caching configuration's GLOBAL +// level, the same value the plan side is configured with. The controller reads +// its runtime knobs from it: whether to compute the client cache answer and +// whether to accumulate the CDN tag union. +func WithGlobalConfig(global cacheconfig.GlobalCacheConfig) ControllerOption { + return func(c *Controller) { + c.global = global + } +} + +// NewController builds a controller over an L2 store; obs may be nil (no +// observability). +func NewController(store Store, obs resolve.CacheObserver, options ...ControllerOption) *Controller { + controller := &Controller{store: store, obs: obs} + for _, option := range options { + option(controller) + } + return controller +} + +// BeginRequest hands out the request-lifetime working surface. Called lazily, +// once per request, under DataBuffer.Lock (the loader's cacheRequest). +func (c *Controller) BeginRequest(ctx *resolve.Context) resolve.RequestCache { + if c.obs != nil { + c.obs.BeginRequest(ctx) + } + request := &requestCache{ + store: c.store, + obs: c.obs, + ctx: ctx, + // states allocates lazily on the first cached fetch. + } + request.aggregate = c.newResponseAggregate(ctx) + if request.aggregate != nil { + ctx.SetCacheResponseInfoSource(request) + } + return request +} + +// newResponseAggregate builds the request's client-answer accumulator, or nil +// when nothing would read it: both emission knobs off — then no fold, no lock +// and no allocation happen all request long — a @defer plan, whose response +// headers ship with the initial frame while the deferred parts are still being +// fetched, or a caller with no Context to publish the answer through. +func (c *Controller) newResponseAggregate(ctx *resolve.Context) *responseAggregate { + emitCacheControl := c.global.EmitsClientCacheControl() + if !emitCacheControl && !c.global.EmitCdnTags { + return nil + } + if ctx == nil || ctx.HasDeferredResponse() { + return nil + } + return &responseAggregate{ + emitCacheControl: emitCacheControl, + emitTags: c.global.EmitCdnTags, + } +} + +// requestCache is the per-request working surface (implements +// resolve.RequestCache). +// +// Concurrency invariant (external lock, no internal mutex): PrepareFetch / +// OnFetchSkipped / OnFetchResult run from parallel per-fetch (and +// per-defer-group) goroutines, but each opens exactly ONE CacheTransaction via +// in.Arena.Begin(), which holds the request's single DataBuffer.Lock for the +// whole hook body. Every mutable field below (the deferred-write set and the +// per-handle config map; later the shared L1 map) is read and written only +// while that lock is held. EndRequest runs once, single-threaded, after the +// whole tree resolves and touches only `deferred` (bytes), so it needs no lock +// either. +type requestCache struct { + store Store + obs resolve.CacheObserver + ctx *resolve.Context + + // deferred is the request-end L2 write set: BYTES only, so the flush needs + // neither lock nor arena. + deferred []Item + // states threads each handle's controller-side state from PrepareFetch to + // the merge hooks (the handle itself is opaque to the loader). ONE lazily + // allocated map instead of one per field — profiled: per-handle side-map + // inserts were a measurable share of the hit path's allocations. + states map[*resolve.FetchCacheHandle]*handleState + // l1 is the request-lifetime entity store: NORMALIZED *astjson.Value + // (never bytes, never marshaled, never enveloped) under the RAW PREIMAGE + // keys the L2 keys derive from. + // EXTERNAL-LOCK INVARIANT: guarded by the caller's CacheTransaction (the + // DataBuffer lock) like everything else on requestCache — no internal + // mutex. Values are isolated by tx.StructuralCopy at BOTH boundaries + // (write and read), so merges can never corrupt a stored value. The map + // is allocated lazily on the first write. + // + // The L1 key carries NO partition segment: one request has exactly one + // requester, so every value in this map already belongs to them. + l1 map[string]*astjson.Value + // aggregate accumulates the request's client cache answer; nil when none is + // computed (see newResponseAggregate). It carries its OWN lock, because the + // folds run where a fetch's cacheability is decided rather than inside the + // hooks' transactions. + aggregate *responseAggregate + // partitionHooks caches the PrivatePartitionProvider's answer per subgraph. + // The hook is an integrator callback (JWT parse, tenant lookup), so it runs + // at most once per subgraph per request; "" records that this request has no + // hook identity there. Same external-lock invariant as the fields above. + partitionHooks map[string]string +} + +// handleState is the controller-side per-fetch state: built once when the +// fetch's lookup starts and read by every per-item step that follows, in the +// lookup and in the merge hooks alike. +type handleState struct { + // cfg is the handle's fetch config (the loader never carries it). + cfg *resolve.FetchCacheConfig + // observed marks the handle as already passed to the observer, so a + // pre-render FlushTraces and EndRequest's own pass observe it ONCE. + observed bool +} + +// useL2 reports whether this fetch participates in L2 through this controller. +func (r *requestCache) useL2(cfg *resolve.FetchCacheConfig) bool { + return cfg != nil && cfg.L2 && r.store != nil +} + +// resolveL2Access answers, for ONE fetch of this request, whether it may touch +// the store and under which partition segment: a public fetch simply may; a +// statically-private one needs a requester identity — the provider's when the +// request has one, else the forwarded subgraph header hash when the fetch keys +// by those headers. Both sources are TAGGED before hashing, so one source's +// literal text can never forge the other's partition. With NO identity the +// fetch skips L2 entirely — no read, no write, values and sentinel alike — +// and the no-identity hint is emitted exactly once per fetch. +func (r *requestCache) resolveL2Access(cfg *resolve.FetchCacheConfig, headerHash uint64) l2Access { + if !r.useL2(cfg) { + return l2Access{} + } + if !cfg.Private { + return l2Access{enabled: true} + } + if identity := r.hookIdentity(cfg.SubgraphName); identity != "" { + return l2Access{enabled: true, partition: sha256Hex("i:" + identity)} + } + if cfg.IncludeSubgraphHeaders { + return l2Access{enabled: true, partition: sha256Hex("h:" + hex64(headerHash))} + } + r.observeUncacheablePrivate(cfg.SubgraphName, UncacheablePrivateNoIdentity) + return l2Access{} +} + +// hookIdentity returns this request's provider identity at a subgraph, calling +// the provider at most once per subgraph and caching even its empty answer. An +// EMPTY identity counts as no identity: it would otherwise collapse every +// requester the provider cannot name into one shared partition. +func (r *requestCache) hookIdentity(subgraph string) string { + if identity, ok := r.partitionHooks[subgraph]; ok { + return identity + } + var identity string + if r.ctx != nil { + if value, ok := r.ctx.PrivatePartition(subgraph); ok { + identity = value + } + } + if r.partitionHooks == nil { + r.partitionHooks = make(map[string]string) + } + r.partitionHooks[subgraph] = identity + return identity +} + +// servableScope reports whether a stored entry may be served to this fetch: an +// entry whose recorded scope is not the one the fetch derives its keys under +// was written by a differently-configured deployment, and is discarded as a +// miss. A private entry reaching a public read is the dangerous direction (it +// would serve one requester's data to everyone); the public-entry-on-a-private +// -read direction is checked symmetrically, for the same price. +func (r *requestCache) servableScope(cfg *resolve.FetchCacheConfig, envelope storedEnvelope) bool { + if envelope.Scope == entryScope(cfg.Private) { + return true + } + if r.obs != nil { + r.obs.OnScopeMismatch(cfg.SubgraphName, envelope.Scope) + } + return false +} + +// observeUncacheablePrivate surfaces one fetch's private data that the store +// never received; a nil observer records nothing. +func (r *requestCache) observeUncacheablePrivate(subgraph, reason string) { + if r.obs == nil { + return + } + r.obs.OnUncacheablePrivate(subgraph, reason) +} + +// storeContext is the context every store call runs under: the request's own, +// so a store implementation inherits its cancellation and deadline. +func (r *requestCache) storeContext() context.Context { + if r.ctx != nil { + if ctx := r.ctx.Context(); ctx != nil { + return ctx + } + } + return context.Background() +} + +// storeGetMany runs the fetch's ONE store read and returns entries positionally +// aligned with keys. A store error — or an answer that does not align with the +// keys, which would serve values under the wrong keys — is reported to the +// observer and degrades to an all-miss, so the fetch falls back to the origin +// and the request never fails. +func (r *requestCache) storeGetMany(subgraph string, keys []string) []Entry { + entries, err := r.store.GetMany(r.storeContext(), keys) + if err == nil && len(entries) == len(keys) { + return entries + } + if err == nil { + err = fmt.Errorf("store returned %d entries for %d keys", len(entries), len(keys)) + } + r.observeStoreError("GetMany", subgraph, len(keys), err) + return make([]Entry, len(keys)) +} + +// observeStoreError surfaces one failed store round trip to the observer; a nil +// observer records nothing. +func (r *requestCache) observeStoreError(op, subgraph string, keyCount int, err error) { + if r.obs == nil { + return + } + r.obs.OnStoreError(op, subgraph, keyCount, err) +} + +// subgraphOf names the fetch's datasource for store-error reporting; "" when +// the fetch carries no info (fetch info is off). +func subgraphOf(item *resolve.FetchItem) string { + if item == nil || item.Fetch == nil || item.Fetch.FetchInfo() == nil { + return "" + } + return item.Fetch.FetchInfo().DataSourceName +} + +// registerHandle threads the fetch's state to the merge hooks (the handle +// itself is opaque to the loader) and stamps the handle's observability +// fields: the fetch's ART trace destination (nil when tracing is off) and the +// key-hashing knob. Observability never adds calls outside the controller — +// the observer reads the handle at EndRequest. +func (r *requestCache) registerHandle(h *resolve.FetchCacheHandle, state *handleState, in resolve.PrepareFetchInput) { + if r.states == nil { + r.states = make(map[*resolve.FetchCacheHandle]*handleState) + } + r.states[h] = state + h.HashAnalyticsKeys = state.cfg.HashAnalyticsKeys + if in.Item != nil && in.Item.Fetch != nil { + h.Trace = in.Item.Fetch.LoadTrace() + } +} + +// cachingDecisionFor resolves the storability of ONE fetch result from the +// subgraph's Cache-Control response header and the fetch's static +// configuration, and emits the runtime-private hint — at most once per result, +// because this runs once per merge hook. +func (r *requestCache) cachingDecisionFor(cfg *resolve.FetchCacheConfig, in resolve.MergeInput) cachingDecision { + decision := resolveCaching(parseResponseCacheControl(in.ResponseHeaders), cachingInput{ + L1: cfg.L1, + L2: r.useL2(cfg), + Private: cfg.Private, + StaticTTL: cfg.TTL, + NegativeTTL: cfg.NegativeCacheTTL, + MaxTTL: cfg.MaxTTL, + }) + if decision.UncacheablePrivate { + r.observeUncacheablePrivate(cfg.SubgraphName, UncacheablePrivateResponseHeader) + } + return decision +} + +// l1Put stores one L1 value; the caller passes a transaction-owned value +// (ParseBytes/StructuralCopy product — never a heap value smuggled into +// arena-noscan memory) and holds the transaction. +// +// PRIVATE VALUES LAND HERE UNPARTITIONED, deliberately: the map lives and dies +// with ONE request, and one request has ONE requester, so two identities can +// never meet in it — a second requester means a second request and therefore a +// second map. That is why privacy costs L2 entries but never in-request reuse, +// even for a request the partition provider cannot identify at all. +func (r *requestCache) l1Put(key string, value *astjson.Value) { + if r.l1 == nil { + r.l1 = make(map[string]*astjson.Value) + } + r.l1[key] = value +} + +// PrepareFetch runs the lookup and folds the fetches it declines into the +// client cache answer: a cache-configured fetch that ends up with NO handle +// touches no layer, so its data reaches the response uncached. +func (r *requestCache) PrepareFetch(in resolve.PrepareFetchInput) (resolve.Decision, *resolve.FetchCacheHandle) { + decision, handle := r.prepareFetch(in) + if handle == nil && in.Config != nil { + r.foldUncacheableFetch(in.Config) + } + return decision, handle +} + +// prepareFetch renders each item's key from its data, serves what L1 covers, +// resolves the remaining keys in ONE store read, runs the always-on coverage +// walk, and AND-reduces per-item hits into the decision. It opens exactly one +// CacheTransaction for all arena work. +func (r *requestCache) prepareFetch(in resolve.PrepareFetchInput) (resolve.Decision, *resolve.FetchCacheHandle) { + cfg := in.Config + if cfg == nil || (!cfg.L1 && !r.useL2(cfg)) { + return resolve.DecisionFetch, nil + } + if cfg.KeySpec.Scope == resolve.CacheScopeRootField { + if !r.useL2(cfg) { + // Root fields are L2 providers only; L1 never applies. + return resolve.DecisionFetch, nil + } + return r.prepareRootFieldFetch(in, cfg) + } + if cfg.KeySpec.Scope != resolve.CacheScopeEntity { + return resolve.DecisionFetch, nil + } + if in.BatchStats != nil { + return r.prepareBatchFetch(in, cfg) + } + if len(in.Items) == 0 { + return resolve.DecisionFetch, nil + } + + tx := in.Arena.Begin() + defer tx.Commit() + + template, ok := r.newFetchKeyTemplate(cfg, in) + if !ok { + return resolve.DecisionFetch, nil + } + state := &handleState{cfg: cfg} + items := r.prepareItems(tx, state, template, subgraphOf(in.Item), in.Items) + shadowStash := stashShadowReads(tx, cfg, items) + allCovered := allItemsCovered(items) + + decision := resolve.DecisionFetch + switch { + case shadowStash != nil: + // Shadow reads never serve: the loader treats FetchShadow exactly like + // Fetch (full network, full merge); the stash drives the compare. + decision = resolve.DecisionFetchShadow + case allCovered: + decision = resolve.DecisionSkipFullHit + } + handle := &resolve.FetchCacheHandle{ + Decision: decision, + WasHit: allCovered, + Shadow: shadowStash != nil, + ShadowStash: shadowStash, + Items: items, + } + r.registerHandle(handle, state, in) + return decision, handle +} + +// newFetchKeyTemplate resolves the fetch's store access and builds its key +// template from it. ok=false when the fetch has nothing left to key: no +// representation node, or neither layer once a private fetch without a +// requester identity has lost L2. It must run inside the fetch's transaction — +// the access resolution touches the request-shared provider cache. +func (r *requestCache) newFetchKeyTemplate(cfg *resolve.FetchCacheConfig, in resolve.PrepareFetchInput) (cacheKeyTemplate, bool) { + access := r.resolveL2Access(cfg, in.HeaderHash) + if !cfg.L1 && !access.enabled { + return cacheKeyTemplate{}, false + } + return newCacheKeyTemplate(r.ctx, cfg, in.HeaderHash, access) +} + +// stashShadowReads moves every would-be-served value of a shadow-configured +// fetch into the stash, keyed by item index; nil when the config is not in +// shadow mode or nothing was selected. +func stashShadowReads(tx *resolve.CacheTransaction, cfg *resolve.FetchCacheConfig, items []resolve.ItemCacheState) map[int]resolve.ShadowCacheEntry { + var shadowStash map[int]resolve.ShadowCacheEntry + for i := range items { + entry := shadowStashEntry(tx, cfg, &items[i]) + if entry == nil { + continue + } + if shadowStash == nil { + shadowStash = make(map[int]resolve.ShadowCacheEntry) + } + shadowStash[i] = *entry + } + return shadowStash +} + +// allItemsCovered is the full-hit condition: every item selected a cached +// value. It runs AFTER the shadow stash, which clears what it takes — a shadow +// fetch therefore never counts as covered. +func allItemsCovered(items []resolve.ItemCacheState) bool { + for i := range items { + if items[i].FromCache == nil { + return false + } + } + return true +} + +// shadowStashEntry moves a shadow-configured item's would-be-served value into +// a stash entry and CLEARS the serving fields, so nothing can be served while +// the compare still sees the exact selection (value, key, freshness, TTL). +// Returns nil when the config is not in shadow mode or nothing was selected. +func shadowStashEntry(tx *resolve.CacheTransaction, cfg *resolve.FetchCacheConfig, state *resolve.ItemCacheState) *resolve.ShadowCacheEntry { + if !cfg.ShadowMode || state.FromCache == nil { + return nil + } + cacheTTL := cfg.TTL + if state.NegativeHit { + cacheTTL = cfg.NegativeCacheTTL + } + entry := &resolve.ShadowCacheEntry{ + CachedValue: tx.StructuralCopy(state.FromCache), + CacheKey: state.RenderedKey, + RemainingTTL: state.RemainingTTL, + CacheTTL: cacheTTL, + } + state.FromCache = nil + state.RemainingTTL = 0 + state.NegativeHit = false + state.ServedFromLayer = "" + return entry +} + +// prepareRootFieldFetch is the root-field arm: ONE whole-response-scoped key +// per fetch (field coordinate + canonical request variables), one lookup, one +// coverage walk, with the served value shared across the fetch's merge +// targets. Root-field shadow is the historical ASYMMETRY: a hit force-refetches +// and overwrites L2, but never stashes and never compares. +func (r *requestCache) prepareRootFieldFetch(in resolve.PrepareFetchInput, cfg *resolve.FetchCacheConfig) (resolve.Decision, *resolve.FetchCacheHandle) { + if len(in.Items) == 0 { + return resolve.DecisionFetch, nil + } + + tx := in.Arena.Begin() + defer tx.Commit() + + access := r.resolveL2Access(cfg, in.HeaderHash) + if !access.enabled { + // Root fields live in L2 alone, so a private coordinate without a + // requester identity has no cache at all this request. + return resolve.DecisionFetch, nil + } + key := rootFieldCacheKey(cfg, in.HeaderHash, r.ctx, access.partition) + + state := &handleState{cfg: cfg} + entry := r.storeGetMany(subgraphOf(in.Item), []string{key})[0] + var fromCache *astjson.Value + var servedFreshness time.Duration + if entry.OK { + if envelope, ok := decodeEnvelope(tx, entry.Value); ok && r.servableScope(cfg, envelope) { + if cfg.ProvidesData != nil && covers(r.ctx, envelope.Data, cfg.ProvidesData) { + fromCache = envelope.Data + servedFreshness = r.servedFreshness(envelope) + } + } + } + if cfg.ShadowMode { + // The root-field shadow asymmetry: read, then force-refetch WITHOUT a + // stash or compare — the plain DecisionFetch below makes a compare + // structurally impossible, and the normal write path overwrites L2. + fromCache = nil + } + + // One key for the whole fetch means one tag set, shared by its items. + tags := rootFieldTags(cfg) + items := make([]resolve.ItemCacheState, 0, len(in.Items)) + for _, item := range in.Items { + state := resolve.ItemCacheState{ + Item: item, + RenderedKey: key, + Tags: tags, + FromCache: fromCache, + } + if fromCache != nil { + state.RemainingTTL = entry.RemainingTTL + state.ServedFreshness = servedFreshness + } + items = append(items, state) + } + + decision := resolve.DecisionFetch + if fromCache != nil { + decision = resolve.DecisionSkipFullHit + } + handle := &resolve.FetchCacheHandle{ + Decision: decision, + WasHit: fromCache != nil, + Items: items, + } + r.registerHandle(handle, state, in) + return decision, handle +} + +// prepareBatchFetch is the batch arm: one ItemCacheState per UNIQUE +// representation (BatchStats bucket), keyed and looked up individually, with +// the original batch position recorded for the splice and the +// partial realign. Full-batch semantics: ALL covered serves, ANY uncovered +// refetches everything. +func (r *requestCache) prepareBatchFetch(in resolve.PrepareFetchInput, cfg *resolve.FetchCacheConfig) (resolve.Decision, *resolve.FetchCacheHandle) { + if len(in.BatchStats) == 0 { + // The loader's empty-batch skip normally prevents this call entirely; + // an empty batch has nothing to serve or write. + return resolve.DecisionFetch, nil + } + tx := in.Arena.Begin() + defer tx.Commit() + + template, ok := r.newFetchKeyTemplate(cfg, in) + if !ok { + return resolve.DecisionFetch, nil + } + // One representative per unique representation; an empty bucket keys off a + // nil node and stays a miss. + representations := make([]*astjson.Value, len(in.BatchStats)) + for i, bucket := range in.BatchStats { + if len(bucket) > 0 { + representations[i] = bucket[0] + } + } + state := &handleState{cfg: cfg} + items := r.prepareItems(tx, state, template, subgraphOf(in.Item), representations) + for i := range items { + items[i].BatchIndex = i + } + shadowStash := stashShadowReads(tx, cfg, items) + allCovered := allItemsCovered(items) + + decision := resolve.DecisionFetch + var batchFetchKeep []bool + switch { + case shadowStash != nil: + decision = resolve.DecisionFetchShadow + case allCovered: + decision = resolve.DecisionSkipFullHit + default: + // Entity policies expose the knob as EnablePartialCacheLoad; + // root-field policies as PartialBatchLoad — either enables the batch + // partial path. Shadow wins over partial (read-never-serve). + if (cfg.EnablePartialCacheLoad || cfg.PartialBatchLoad) && !cfg.ShadowMode { + // SOME buckets covered: mark the missing ones and go partial. + // keep[i] mirrors the bucket order (which is the representations + // order); the LOADER assembles the reduced input from the + // already-rendered segments — no bytes are parsed back. + keep := make([]bool, len(items)) + anyCovered := false + for i := range items { + keep[i] = items[i].FromCache == nil + if !keep[i] { + anyCovered = true + } + } + if anyCovered { + decision = resolve.DecisionFetchPartial + batchFetchKeep = keep + } + } + } + handle := &resolve.FetchCacheHandle{ + Decision: decision, + WasHit: allCovered, + BatchEntityKey: true, + Shadow: shadowStash != nil, + ShadowStash: shadowStash, + BatchFetchKeep: batchFetchKeep, + Items: items, + } + r.registerHandle(handle, state, in) + return decision, handle +} + +// prepareItems resolves the fetch's items in one pass: render every key, serve +// what L1 already covers, and resolve the remaining keys with a SINGLE store +// read. The returned states align positionally with items; an item whose key +// does not render is a plain miss — the fetch input could not have rendered +// either. +func (r *requestCache) prepareItems(tx *resolve.CacheTransaction, state *handleState, template cacheKeyTemplate, subgraph string, items []*astjson.Value) []resolve.ItemCacheState { + cfg := state.cfg + states := make([]resolve.ItemCacheState, len(items)) + // keys carries the batch read; pending[n] is the state keys[n] answers. + var keys []string + var pending []int + for i, item := range items { + states[i].Item = item + rendered, ok := template.render(item) + if !ok { + continue + } + states[i].L1Key = rendered.L1 + states[i].RenderedKey = rendered.L2 + if rendered.L2 != "" { + // Tags address store entries, so an L1-only fetch derives none. They + // are taken here, from the same pre-merge item the keys rendered + // from, which is what keeps a written and a served entry's tags + // identical. + states[i].Tags = template.entityTags(item) + } + if r.serveFromL1(tx, cfg, &states[i]) { + continue + } + if rendered.L2 == "" { + // L1-only: a miss is a plain fetch; there is no L2 to read. + continue + } + keys = append(keys, rendered.L2) + pending = append(pending, i) + } + if len(keys) == 0 { + return states + } + entries := r.storeGetMany(subgraph, keys) + for n, i := range pending { + r.applyStoreEntry(tx, state, &states[i], entries[n]) + } + return states +} + +// The layers an item can be served from, as recorded on ItemCacheState for +// trace output — and read back by the client-answer fold, which counts a +// request-lifetime hit as no contribution at all. +const ( + servedFromL1 = "l1" + servedFromL2 = "l2" +) + +// serveFromL1 serves the item from the request-lifetime cache when a covering +// value (or the negative sentinel) sits under its RAW PREIMAGE key, which +// SHORT-CIRCUITS the store read: an L1 hit costs no hashing, no parsing, and no +// marshaling. Reports whether the item was served. +func (r *requestCache) serveFromL1(tx *resolve.CacheTransaction, cfg *resolve.FetchCacheConfig, state *resolve.ItemCacheState) bool { + if !cfg.L1 { + return false + } + stored := r.l1[state.L1Key] + if stored == nil { + return false + } + // A null is the L1 negative sentinel: the entity is KNOWN missing within + // this request, so it serves without a coverage walk. + negative := stored.Type() == astjson.TypeNull + if !negative && !covers(r.ctx, stored, cfg.ProvidesData) { + return false + } + state.FromCache = tx.StructuralCopy(stored) + state.NegativeHit = negative + state.ServedFromLayer = servedFromL1 + return true +} + +// applyStoreEntry accepts (or rejects) ONE store read for its item: the +// negative sentinel serves as a known-missing entity, a covering value serves +// as a hit and populates L1, and everything else — miss, undecodable bytes, a +// foreign privacy scope, uncovered value — leaves the item a miss. +func (r *requestCache) applyStoreEntry(tx *resolve.CacheTransaction, state *handleState, item *resolve.ItemCacheState, entry Entry) { + if !entry.OK { + return + } + cfg := state.cfg + envelope, ok := decodeEnvelope(tx, entry.Value) + if !ok { + // Undecodable stored bytes are treated as a miss; the write path + // refreshes the entry. + return + } + if !r.servableScope(cfg, envelope) { + // The scope guard runs BEFORE the sentinel branch: a private "this + // entity does not exist" is as requester-specific as a value. + return + } + cached := envelope.Data + switch { + case cached.Type() == astjson.TypeNull: + // A TOP-LEVEL null cached value is the negative sentinel: the entity is + // KNOWN to not exist, so the item is served as null without a coverage + // walk (there is nothing to cover). + item.FromCache = cached + item.NegativeHit = true + case covers(r.ctx, cached, cfg.ProvidesData): + // The served value stays in NORMALIZED (stored) form on the handle; + // OnFetchSkipped denormalizes it to the requesting aliases at splice + // time. + item.FromCache = cached + default: + return + } + item.RemainingTTL = entry.RemainingTTL + item.ServedFreshness = r.servedFreshness(envelope) + item.ServedFromLayer = servedFromL2 + // Only SERVED values may enter the shared L1. Under shadow the selection is + // a probe the stash clears before anything can serve it — leaking it into L1 + // would let a sibling L1 reader serve a value shadow mode never served. + if cfg.L1 && !cfg.ShadowMode { + r.l1Put(item.L1Key, tx.StructuralCopy(item.FromCache)) + } +} + +// OnFetchSkipped splices the cached values into the merge targets at the +// surfaced merge path, inside one CacheTransaction; the per-target denormalize +// walk guards against aliasing when one cached value serves multiple targets. +// A served hit owes NO writes: the read key is the write key, so the entry it +// came from is already the one a write would target. +func (r *requestCache) OnFetchSkipped(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + if h == nil { + return nil + } + state := r.states[h] + if state == nil { + return nil + } + cfg := state.cfg + tx := in.Arena.Begin() + defer tx.Commit() + + for i := range h.Items { + item := &h.Items[i] + r.foldServedItem(cfg, item) + if item.FromCache == nil || item.Item == nil { + continue + } + // A batch item splices into EVERY merge target of its unique + // representation (the BatchStats bucket at its original position). + targets := []*astjson.Value{item.Item} + if h.BatchEntityKey { + targets = nil + if item.BatchIndex >= 0 && item.BatchIndex < len(in.BatchStats) { + targets = in.BatchStats[item.BatchIndex] + } + } + if err := r.spliceCachedItem(tx, cfg.ProvidesData, item, targets, in.MergePath); err != nil { + return err + } + } + return nil +} + +// spliceCachedItem serves ONE covered item: splice the denormalized cached +// value into every merge target. Shared by OnFetchSkipped and the partial arm. +func (r *requestCache) spliceCachedItem(tx *resolve.CacheTransaction, provides *resolve.Object, item *resolve.ItemCacheState, targets []*astjson.Value, fetchMergePath []string) error { + if item.FromCache == nil { + return nil + } + if item.FromCache.Type() == astjson.TypeNull { + // A negative hit splices NOTHING and writes nothing: a real + // successful-but-empty entity fetch leaves the merge targets untouched + // (mergeResult early-returns), and the resolvable then renders the + // null bubble and its non-null error exactly as it would uncached. + // Replacing the target with null here would make the cached response + // DIFFER from the uncached one — caching must never change the + // response. + return nil + } + + for _, target := range targets { + if target == nil { + continue + } + // Denormalize the stored value to the requesting operation's + // aliases in selection order; the walk builds a fresh + // transaction-owned value per target, so it is also the + // aliasing-safe copy for the splice. + cached := denormalizeToSelection(tx, r.ctx, item.FromCache, provides) + if len(fetchMergePath) > 0 { + if _, err := tx.MergeValuesWithPath(target, cached, fetchMergePath...); err != nil { + return err + } + } else if _, err := tx.MergeValues(target, cached); err != nil { + return err + } + } + return nil +} + +// OnFetchResult applies the write gate and defers the L2 writes (bytes) to the +// request-end flush. The gate is !FetchFailed && !HasErrors && ResponseData != +// nil && Type() != Null — it can never reduce to !HasErrors alone, because +// transport/empty-body/parse failures reach this hook with HasErrors == false. +func (r *requestCache) OnFetchResult(h *resolve.FetchCacheHandle, in resolve.MergeInput) error { + if h == nil { + return nil + } + state := r.states[h] + if state == nil { + return nil + } + cfg := state.cfg + if h.Decision == resolve.DecisionFetchPartial { + // The partial arm owns splice + realign + writes and runs BEFORE the + // failure gate: on a failed partial fetch the covered splice must + // still happen (the cached data is valid; the loader already rendered + // the fetch errors), and only the fetched subset is skipped. + return r.onPartialBatchResult(h, in, state) + } + if in.FetchFailed || in.HasErrors { + // All failure signals block ALL writes — including negative ones: a + // transport/parse failure or errored response is a transient error, + // never a proof of nonexistence (FetchFailed wins over EmptyEntity). + // Nothing was stored, so the response may not be either. + r.foldUncacheableFetch(cfg) + return nil + } + decision := r.cachingDecisionFor(cfg, in) + r.foldFetchedResult(h, in, decision) + if in.EmptyEntity && in.ResponseData != nil && in.ResponseData.Type() == astjson.TypeNull { + r.writeNegativeSentinel(h, in, decision) + return nil + } + if in.ResponseData == nil || in.ResponseData.Type() == astjson.TypeNull { + return nil + } + tx := in.Arena.Begin() + defer tx.Commit() + + if h.Shadow && r.obs != nil { + // The staleness probe: compare the stashed cached values against the + // fresh response BEFORE any write, inside this hook's transaction + // (compare -> write-L1 -> write-L2 order; no second lock acquisition). + r.obs.CompareShadow(h, in.ResponseData, tx) + } + + if cfg.KeySpec.Scope == resolve.CacheScopeRootField { + // One whole-response value under the fetch's single key, written once + // (the items share it). + if decision.TTL <= 0 { + return nil + } + toStore := in.ResponseData + if cfg.ProvidesData != nil && cfg.ProvidesData.HasAliases { + toStore = normalizeToSchema(tx, r.ctx, toStore, cfg.ProvidesData) + } + r.deferSet(h.Items[0].RenderedKey, toStore, decision.TTL, decision.Scope, h.Items[0].Tags) + return nil + } + + // A batch response is the _entities array: each unique representation's + // value sits at its original batch position. + var batch []*astjson.Value + if h.BatchEntityKey { + batch = in.ResponseData.GetArray() + if batch == nil { + return nil + } + } + for itemIndex := range h.Items { + item := &h.Items[itemIndex] + itemToStore := in.ResponseData + if h.BatchEntityKey { + if item.BatchIndex < 0 || item.BatchIndex >= len(batch) { + continue + } + itemToStore = batch[item.BatchIndex] + } + if len(in.MergePath) > 0 { + // The response merges into the item at the merge path; the value to + // cache is the entity BELOW that path, never the wrapper. + entity := itemToStore.Get(in.MergePath...) + if entity == nil { + continue + } + itemToStore = entity + } + r.writeFetchedValue(tx, decision, state, item, itemToStore) + } + return nil +} + +// writeNegativeSentinel caches the ONE non-failure that still writes: a +// SUCCESSFUL fetch that legitimately returned no entity, so repeated lookups +// for a nonexistent entity skip the network. The sentinel passes the same +// storability gates as a value — an emptiness answer can be no-store or +// requester-dependent too — but never takes its lifetime from max-age. +func (r *requestCache) writeNegativeSentinel(h *resolve.FetchCacheHandle, in resolve.MergeInput, decision cachingDecision) { + if !decision.L1 && decision.NegativeTTL <= 0 { + return + } + tx := in.Arena.Begin() + defer tx.Commit() + for i := range h.Items { + item := &h.Items[i] + item.FromCache = tx.Null() + item.NegativeHit = true + if decision.L1 && item.L1Key != "" { + // Within the request the nonexistence is a fact — the L1 sentinel + // needs no TTL knob. + r.l1Put(item.L1Key, tx.Null()) + } + if decision.NegativeTTL > 0 && item.RenderedKey != "" { + // The sentinel describes no fields, so it stores no data. It carries + // the entity's full tag set all the same: purging an entity must + // clear its "does not exist" record too, or the purge would leave + // the entity invisible until the sentinel expires. + r.deferSet(item.RenderedKey, nil, decision.NegativeTTL, decision.Scope, item.Tags) + } + } +} + +// writeFetchedValue caches one FRESH per-item value: normalize to the stored +// form (schema names + argument suffixes; HasAliases is the fast-path gate), +// then feed each layer the fetch result's storability decision permits, under +// its own key from that one rendering. A layer whose key did not render is +// skipped — the read and the write use the same key, so there is nothing to +// write it under. Shared by OnFetchResult and the partial arm. +func (r *requestCache) writeFetchedValue(tx *resolve.CacheTransaction, decision cachingDecision, state *handleState, item *resolve.ItemCacheState, itemToStore *astjson.Value) { + if itemToStore == nil || itemToStore.Type() == astjson.TypeNull { + // A null element is a MISSING entity, not a value: storing it would + // fabricate a negative sentinel under the positive TTL (bypassing the + // NegativeCacheTTL knob). Negative caching rides the loader's + // whole-response EmptyEntity signal only. + return + } + provides := state.cfg.ProvidesData + toStore := itemToStore + if provides != nil && provides.HasAliases { + toStore = normalizeToSchema(tx, r.ctx, itemToStore, provides) + } + if decision.L1 && item.L1Key != "" { + // write-L1 before write-L2; POINTER store, zero marshaling. + r.l1Put(item.L1Key, tx.StructuralCopy(toStore)) + } + if decision.TTL > 0 && item.RenderedKey != "" { + r.deferSet(item.RenderedKey, toStore, decision.TTL, decision.Scope, item.Tags) + } +} + +// FlushTraces passes every not-yet-observed handle to the observer (trace +// assembly, counters) — single-threaded, no lock, no arena. The resolver calls +// it right before the response renders so extensions.trace carries the cache +// sections; EndRequest runs the same pass for whatever remains, so each handle +// is observed exactly once either way. +func (r *requestCache) FlushTraces() { + if r.obs == nil { + return + } + for h, state := range r.states { + if state.observed { + continue + } + state.observed = true + r.obs.OnFetchObserved(h) + } +} + +// EndRequest flushes the request's deferred L2 writes in ONE store call — +// bytes only, no lock, no arena, no transaction — and finalizes observability. +// It runs once, single-threaded, after the root tree and every defer group have +// resolved. +func (r *requestCache) EndRequest() { + // Finalize observability for handles not already flushed pre-render. + r.FlushTraces() + if len(r.deferred) > 0 { + if err := r.store.SetMany(r.storeContext(), r.deferred); err != nil { + // Dropped writes never reach the response: the values the request + // rendered came from the subgraphs, and the next request repopulates + // the entries. The flush spans every fetch of the request, so the + // event carries no single subgraph. + r.observeStoreError("SetMany", "", len(r.deferred), err) + } + } + r.deferred = nil + if r.obs != nil { + r.obs.EndRequest(r.ctx) + } +} + +// deferSet queues ONE L2 write for the request-end flush. The value is encoded +// into the storage envelope here — with the TTL it is written under, the write +// moment, and the scope it belongs to — so only plain bytes cross into the +// deferred set. A nil data queues the negative sentinel. The tags ride on the +// Item, never inside the envelope: a private entry carries the same tags as its +// public counterpart would, so one purge reaches every partition of an entity. +func (r *requestCache) deferSet(key string, data *astjson.Value, ttl time.Duration, scope string, tags []string) { + cc := cacheControl{ + TTL: ttl, + Created: time.Now(), + Scope: scope, + } + r.deferred = append(r.deferred, Item{ + Key: key, + Value: encodeEnvelope(data, cc), + TTL: ttl, + Tags: tags, + }) + if r.aggregate != nil { + // The queue is the single funnel every written entry passes, so the CDN + // union collects exactly the entries the response really produced. + r.aggregate.foldTags(tags) + } +} diff --git a/v2/pkg/engine/cache/controller_batch_test.go b/v2/pkg/engine/cache/controller_batch_test.go new file mode 100644 index 0000000000..1b6d672d70 --- /dev/null +++ b/v2/pkg/engine/cache/controller_batch_test.go @@ -0,0 +1,253 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// batchInput builds a PrepareFetchInput with one BatchStats bucket per item; +// each bucket's targets alias the representative (the common loader shape). +func batchInput(cfg *resolve.FetchCacheConfig, buckets ...[]*astjson.Value) resolve.PrepareFetchInput { + in := prepareInput(cfg) + in.BatchStats = buckets + return in +} + +// TestControllerBatchRows covers the I rows: per-item keying, full-batch +// serve/refetch semantics, batch splice targets, and the write gates on +// non-array and null elements. +func TestControllerBatchRows(t *testing.T) { + newRC := func(store Store) resolve.RequestCache { + return NewController(store, nil).BeginRequest(nil) + } + + primeBatch := func(t *testing.T, store *testStore, cfg *resolve.FetchCacheConfig, upcs []string, entities string) []string { + t.Helper() + rc := newRC(store) + buckets := make([][]*astjson.Value, 0, len(upcs)) + for _, upc := range upcs { + buckets = append(buckets, []*astjson.Value{productItem(t, upc)}) + } + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(entities)), + Arena: beginner(), + })) + rc.EndRequest() + keys := make([]string, 0, len(handle.Items)) + for _, item := range handle.Items { + require.NotEmpty(t, item.RenderedKey) + keys = append(keys, item.RenderedKey) + } + return keys + } + + t.Run("[I1] per-item keying: N entities produce ONE read of N distinct keys and ONE write of N items", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + keys := primeBatch(t, store, cfg, []string{"1", "2"}, + `[{"__typename":"Product","name":"Table","price":100},{"__typename":"Product","name":"Chair","price":50}]`) + require.Len(t, keys, 2) + assert.NotEqual(t, keys[0], keys[1]) + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{keys[0], keys[1]}, + Hits: []bool{false, false}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: keys[0], + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: keys[1], + Value: `{"data":{"__typename":"Product","name":"Chair","price":50},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("[I2] full-batch hit serves every merge target at the merge path", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + primeBatch(t, store, cfg, []string{"1", "2"}, + `[{"__typename":"Product","name":"Table","price":100},{"__typename":"Product","name":"Chair","price":50}]`) + + rc := newRC(store) + // Bucket 0 has TWO merge targets (a deduplicated representation). + target0a := productItem(t, "1") + target0b := productItem(t, "1") + target1 := productItem(t, "2") + buckets := [][]*astjson.Value{{target0a, target0b}, {target1}} + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.True(t, handle.BatchEntityKey) + assert.Equal(t, []int{0, 1}, []int{handle.Items[0].BatchIndex, handle.Items[1].BatchIndex}) + + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + BatchStats: buckets, + MergePath: []string{"details"}, + Arena: beginner(), + })) + assert.Equal(t, `{"__typename":"Product","upc":"1","details":{"name":"Table","price":100,"__typename":"Product"}}`, string(target0a.MarshalTo(nil))) + assert.Equal(t, `{"__typename":"Product","upc":"1","details":{"name":"Table","price":100,"__typename":"Product"}}`, string(target0b.MarshalTo(nil))) + assert.Equal(t, `{"__typename":"Product","upc":"2","details":{"name":"Chair","price":50,"__typename":"Product"}}`, string(target1.MarshalTo(nil))) + }) + + t.Run("[I3] mixed batch never partially serves: full refetch with lookups logged", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + keys := primeBatch(t, store, cfg, []string{"1"}, `[{"__typename":"Product","name":"Table","price":100}]`) + store.ops = nil // the mixed batch's ops assert in isolation + + rc := newRC(store) + buckets := [][]*astjson.Value{{productItem(t, "1")}, {productItem(t, "3")}} + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.Equal(t, resolve.DecisionFetch, decision) + assert.False(t, handle.WasHit) + // Item 0 is covered, item 1 not — but full-batch semantics refetch all. + assert.NotNil(t, handle.Items[0].FromCache) + assert.Nil(t, handle.Items[1].FromCache) + + // The full refetch writes EVERY entity afterwards. + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[{"__typename":"Product","name":"Table","price":100},{"__typename":"Product","name":"Desk","price":80}]`)), + Arena: beginner(), + })) + rc.EndRequest() + missKey := handle.Items[1].RenderedKey + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{keys[0], missKey}, + Hits: []bool{true, false}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: keys[0], + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: missKey, + Value: `{"data":{"__typename":"Product","name":"Desk","price":80},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:dae7809df4f7fdee", // upc "3" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("[I5] a non-array batch response writes nothing", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := newRC(store) + buckets := [][]*astjson.Value{{productItem(t, "1")}} + _, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.NotNil(t, handle) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`{"not":"an array"}`)), + Arena: beginner(), + })) + rc.EndRequest() + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + }, store.ops) + }) + + t.Run("[I6] a null batch element writes nothing: never a fake negative sentinel", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := newRC(store) + buckets := [][]*astjson.Value{{productItem(t, "1")}, {productItem(t, "2")}} + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[null,{"__typename":"Product","name":"Desk","price":80}]`)), + Arena: beginner(), + })) + rc.EndRequest() + missingKey := handle.Items[0].RenderedKey + foundKey := handle.Items[1].RenderedKey + // The null element writes NOTHING: caching it under cfg.TTL would read + // back as a negative hit and bypass the NegativeCacheTTL knob. + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{missingKey, foundKey}, + Hits: []bool{false, false}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: foundKey, + Value: `{"data":{"__typename":"Product","name":"Desk","price":80},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, store.ops) + // Nothing was PERSISTED for the missing entity: a fresh request (whose + // L1 starts empty, so the lookup can only hit L2) is a plain miss, + // never a negative hit. + rcB := newRC(store) + decisionB, handleB := prepare(t, rcB, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decisionB) + assert.False(t, handleB.Items[0].NegativeHit) + }) + }) +} diff --git a/v2/pkg/engine/cache/controller_cache_control_test.go b/v2/pkg/engine/cache/controller_cache_control_test.go new file mode 100644 index 0000000000..a3dd8bd5ae --- /dev/null +++ b/v2/pkg/engine/cache/controller_cache_control_test.go @@ -0,0 +1,541 @@ +package cache + +import ( + "net/http" + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// cacheControlHeader builds the response header a subgraph answered with; "" +// means the subgraph sent none. +func cacheControlHeader(value string) http.Header { + if value == "" { + return nil + } + return http.Header{"Cache-Control": []string{value}} +} + +// privateObserver records the uncacheable-private hints and the discarded +// scope mismatches, and nothing else. +type privateObserver struct { + noopObserver + + hints []UncacheablePrivate + scopeMismatches []ScopeMismatch +} + +func (o *privateObserver) OnUncacheablePrivate(subgraph string, reason string) { + o.hints = append(o.hints, UncacheablePrivate{Subgraph: subgraph, Reason: reason}) +} + +func (o *privateObserver) OnScopeMismatch(subgraph string, storedScope string) { + o.scopeMismatches = append(o.scopeMismatches, ScopeMismatch{Subgraph: subgraph, StoredScope: storedScope}) +} + +// fetchWithCacheControl runs one miss -> fetch-result -> flush cycle whose +// subgraph response carried the given Cache-Control value, and returns the +// handle so rows can read the key both layers were written under. +func fetchWithCacheControl(t *testing.T, rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, item *astjson.Value, responseData, cacheControlValue string) *resolve.FetchCacheHandle { + t.Helper() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(responseData)), + ResponseHeaders: cacheControlHeader(cacheControlValue), + Arena: beginner(), + })) + rc.EndRequest() + return handle +} + +// TestControllerCacheControlTTLRows drives the two-tier TTL ladder through the +// real write path: what the store entry is written with and what the envelope +// records. +func TestControllerCacheControlTTLRows(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("header max-age wins over the configured TTL", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "max-age=60") + + key := handle.Items[0].RenderedKey + // The envelope's cc.ttl and the store item's TTL both carry the + // resolved 60s, not the configured 5m. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("a silent header leaves the configured TTL in charge", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":300,"created":946684800,"scope":"public"}}`, + TTL: 5 * time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("a malformed max-age falls through to the configured TTL", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "max-age=whenever") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":300,"created":946684800,"scope":"public"}}`, + TTL: 5 * time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("max-age zero writes nothing to the store but still feeds L1", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "max-age=0") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + }, store.ops) + // L1 is request-lifetime and untouched by a merely-zero TTL, so a + // sibling fetch of the same entity still serves without a network hop. + decision, _ := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + }) + + t.Run("MaxTTL clamps the header tier", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + cfg.MaxTTL = 30 * time.Second + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "max-age=600") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":30,"created":946684800,"scope":"public"}}`, + TTL: 30 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("MaxTTL clamps the static tier", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 10*time.Minute) + cfg.MaxTTL = time.Minute + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("a root field takes its TTL from the header too", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := rootFieldConfig(5 * time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + item := rootItem() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"products":[{"name":"Table"}]}`)), + ResponseHeaders: cacheControlHeader("max-age=90"), + Arena: beginner(), + })) + rc.EndRequest() + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"products":[{"name":"Table"}]},"cc":{"ttl":90,"created":946684800,"scope":"public"}}`, + TTL: 90 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Query", // a root-field entry is not one entity: no entity tag + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("ONE header governs every entity entry written from a batch response", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + buckets := [][]*astjson.Value{ + {productItem(t, "1")}, + {productItem(t, "2")}, + } + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[{"__typename":"Product","name":"Table","price":100},{"__typename":"Product","name":"Chair","price":50}]`)), + ResponseHeaders: cacheControlHeader("max-age=45"), + Arena: beginner(), + })) + rc.EndRequest() + + // The batch is ONE HTTP response, so its single Cache-Control drives + // both entries' TTLs. + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{ + handle.Items[0].RenderedKey, + handle.Items[1].RenderedKey, + }, + Hits: []bool{false, false}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: handle.Items[0].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":45,"created":946684800,"scope":"public"}}`, + TTL: 45 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: handle.Items[1].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"Chair","price":50},"cc":{"ttl":45,"created":946684800,"scope":"public"}}`, + TTL: 45 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, store.ops) + }) + }) +} + +// TestControllerCacheControlStorabilityRows covers the directives that decide +// WHETHER a result is kept at all: no-store, no-cache, and runtime private. +func TestControllerCacheControlStorabilityRows(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("no-store writes to NEITHER layer", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "no-store") + + // The lookup happened; nothing was written back. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + assert.Equal(t, map[string]*astjson.Value(nil), rc.(*requestCache).l1) + // And the request-lifetime layer really is empty: a sibling fetch of the + // same entity misses and goes to the network. + decision, _ := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + }) + + t.Run("no-cache is treated exactly like no-store", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "no-cache") + + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + assert.Equal(t, map[string]*astjson.Value(nil), rc.(*requestCache).l1) + decision, _ := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + }) + + t.Run("a runtime-private result skips the store, keeps L1, and reports once", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, obs).BeginRequest(nil) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "private, max-age=60") + + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + // The value is per-requester and the request IS the requester, so L1 + // keeps it — and one hint names the subgraph that made it uncacheable. + assert.Equal(t, []UncacheablePrivate{ + {Subgraph: "products", Reason: UncacheablePrivateResponseHeader}, + }, obs.hints) + decision, _ := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + }) + + t.Run("a public result reports no private hint", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := entityConfig(t, 5*time.Minute) + rc := NewController(store, obs).BeginRequest(nil) + fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "public, max-age=60") + + assert.Equal(t, []UncacheablePrivate(nil), obs.hints) + }) +} + +// TestControllerCacheControlNegativeRows: the empty-entity sentinel runs the +// same storability pipeline as a value, but never takes its lifetime from +// max-age. +func TestControllerCacheControlNegativeRows(t *testing.T) { + sentinelFetch := func(t *testing.T, rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, cacheControlValue string) *resolve.FetchCacheHandle { + t.Helper() + item := productItem(t, "404") + _, handle := prepare(t, rc, cfg, item) + in := emptyEntityInput(item) + in.ResponseHeaders = cacheControlHeader(cacheControlValue) + require.NoError(t, rc.OnFetchResult(handle, in)) + rc.EndRequest() + return handle + } + + t.Run("max-age does NOT extend the sentinel: NegativeCacheTTL still decides", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + rc := NewController(store, nil).BeginRequest(nil) + handle := sentinelFetch(t, rc, cfg, "max-age=3600") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":null,"cc":{"ttl":5,"created":946684800,"scope":"public"}}`, + TTL: 5 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:0256cf786a3c1be7", // upc "404": the sentinel is tagged like a value + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("MaxTTL clamps the sentinel lifetime", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, time.Hour) + cfg.MaxTTL = time.Minute + rc := NewController(store, nil).BeginRequest(nil) + handle := sentinelFetch(t, rc, cfg, "") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":null,"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:0256cf786a3c1be7", // upc "404" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("no-store suppresses the sentinel in BOTH layers", func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + rc := NewController(store, nil).BeginRequest(nil) + handle := sentinelFetch(t, rc, cfg, "no-store") + + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + assert.Equal(t, map[string]*astjson.Value(nil), rc.(*requestCache).l1) + }) + + t.Run("a private sentinel skips the store but stays known-missing in L1", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := negativeConfig(t, 5*time.Second) + rc := NewController(store, obs).BeginRequest(nil) + handle := sentinelFetch(t, rc, cfg, "private") + + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + assert.Equal(t, []UncacheablePrivate{ + {Subgraph: "products", Reason: UncacheablePrivateResponseHeader}, + }, obs.hints) + // Nonexistence is a fact WITHIN the request, so the L1 sentinel serves a + // sibling lookup for the same entity. + _, second := prepare(t, rc, cfg, productItem(t, "404")) + require.NotNil(t, second) + assert.True(t, second.Items[0].NegativeHit) + }) +} + +// TestControllerCacheControlExpiryRows: the resolved TTL is what the entry +// actually lives by, verified by sleeping past it in a synctest bubble. +func TestControllerCacheControlExpiryRows(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("an entry written from max-age expires when that max-age elapses", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Hour) + fetchWithCacheControl(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), fresh, "max-age=2") + + // Still fresh one second in, despite the configured hour being far + // from over. + time.Sleep(time.Second) + decision, _ := prepare(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + + time.Sleep(2 * time.Second) + decision, _ = prepare(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + }) + }) + + t.Run("a clamped entry expires at MaxTTL, not at the header value", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Hour) + cfg.MaxTTL = 10 * time.Second + fetchWithCacheControl(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), fresh, "max-age=600") + + time.Sleep(9 * time.Second) + decision, _ := prepare(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + + // Past the clamp but far inside the header's 600s. + time.Sleep(2 * time.Second) + decision, _ = prepare(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + }) + }) +} diff --git a/v2/pkg/engine/cache/controller_l1_test.go b/v2/pkg/engine/cache/controller_l1_test.go new file mode 100644 index 0000000000..e342acecee --- /dev/null +++ b/v2/pkg/engine/cache/controller_l1_test.go @@ -0,0 +1,229 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// l1Fetch runs one miss->fetch->result cycle on rc, feeding the L1 (and L2 +// when enabled) from responseData. +func l1Fetch(t *testing.T, rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, item *astjson.Value, responseData *astjson.Value) *resolve.FetchCacheHandle { + t.Helper() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: responseData, + Arena: beginner(), + })) + return handle +} + +// TestControllerL1Rows covers the request-lifetime L1 store rows. +func TestControllerL1Rows(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("in-request reuse: fetch A populates L1, fetch B hits with zero store ops (shared preimage)", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) // L1 + L2 + rc := NewController(store, nil).BeginRequest(nil) + + handleA := l1Fetch(t, rc, cfg, productItem(t, "1"), astjson.MustParseBytes([]byte(fresh))) + + itemB := productItem(t, "1") + decision, handleB := prepare(t, rc, cfg, itemB) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + // SHARED PREIMAGE: both layers' keys come from one rendering per item. + assert.Equal(t, handleA.Items[0].L1Key, handleB.Items[0].L1Key) + assert.Equal(t, handleA.Items[0].RenderedKey, handleB.Items[0].RenderedKey) + require.NoError(t, rc.OnFetchSkipped(handleB, resolve.MergeInput{ + Items: []*astjson.Value{itemB}, + Arena: beginner(), + })) + assert.Equal(t, + `{"__typename":"Product","upc":"1","name":"Table","price":100}`, + string(itemB.MarshalTo(nil))) + rc.EndRequest() + // A's miss read and A's flush write are the ONLY store ops: B's L1 hit + // kept its key out of the batch read entirely (and a served hit owes no + // write). + key := handleA.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("[J] L1-only: full round-trip with ZERO store ops (zero marshaling path)", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 0) // TTL 0: L1 true, L2 false + rc := NewController(store, nil).BeginRequest(nil) + + l1Fetch(t, rc, cfg, productItem(t, "1"), astjson.MustParseBytes([]byte(fresh))) + itemB := productItem(t, "1") + decision, handleB := prepare(t, rc, cfg, itemB) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + // An L1-only fetch keys off the RAW PREIMAGE and derives no store key + // at all: no version segment, no hashing. + assert.Equal(t, `products:{"__typename":"Product","representation":{"upc":"1"}}`, handleB.Items[0].L1Key) + assert.Equal(t, "", handleB.Items[0].RenderedKey) + require.NoError(t, rc.OnFetchSkipped(handleB, resolve.MergeInput{ + Items: []*astjson.Value{itemB}, + Arena: beginner(), + })) + rc.EndRequest() + assert.Equal(t, + `{"__typename":"Product","upc":"1","name":"Table","price":100}`, + string(itemB.MarshalTo(nil))) + assert.Empty(t, store.ops) + }) + + t.Run("write isolation: mutating the response after the write leaves L1 unaffected", func(t *testing.T) { + cfg := entityConfig(t, 0) + rc := NewController(newTestStore(), nil).BeginRequest(nil) + responseData := astjson.MustParseBytes([]byte(fresh)) + l1Fetch(t, rc, cfg, productItem(t, "1"), responseData) + + // Corrupt the source AFTER the L1 write. + responseData.Set(nil, "name", astjson.MustParseBytes([]byte(`"CORRUPTED"`))) + + itemB := productItem(t, "1") + _, handleB := prepare(t, rc, cfg, itemB) + require.NotNil(t, handleB.Items[0].FromCache) + assert.Equal(t, fresh, string(handleB.Items[0].FromCache.MarshalTo(nil))) + }) + + t.Run("read isolation: mutating a served value leaves L1 unaffected", func(t *testing.T) { + cfg := entityConfig(t, 0) + rc := NewController(newTestStore(), nil).BeginRequest(nil) + l1Fetch(t, rc, cfg, productItem(t, "1"), astjson.MustParseBytes([]byte(fresh))) + + itemB := productItem(t, "1") + _, handleB := prepare(t, rc, cfg, itemB) + require.NotNil(t, handleB.Items[0].FromCache) + // Corrupt the SERVED copy. + handleB.Items[0].FromCache.Set(nil, "name", astjson.MustParseBytes([]byte(`"CORRUPTED"`))) + + itemC := productItem(t, "1") + _, handleC := prepare(t, rc, cfg, itemC) + require.NotNil(t, handleC.Items[0].FromCache) + assert.Equal(t, fresh, string(handleC.Items[0].FromCache.MarshalTo(nil))) + }) + + t.Run("an L2 hit populates L1: the second lookup emits no second store read", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + key := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), fresh) + store.ops = nil // request 2's ops assert in isolation + + rc := NewController(store, nil).BeginRequest(nil) + itemA := productItem(t, "1") + decisionA, _ := prepare(t, rc, cfg, itemA) + require.Equal(t, resolve.DecisionSkipFullHit, decisionA) + + itemB := productItem(t, "1") + decisionB, _ := prepare(t, rc, cfg, itemB) + assert.Equal(t, resolve.DecisionSkipFullHit, decisionB) + rc.EndRequest() + // Fetch A's single L2 read is request 2's ONLY store op — fetch B rode L1. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + }) + + t.Run("a DIFFERENT representation shape never rides the same L1 entry", func(t *testing.T) { + store := newTestStore() + // Both fetches resolve Product, but one sends {upc} and the other + // {sku}: two independent representations, hence two independent + // entries. The sku-keyed lookup must MISS what the upc-keyed fetch + // cached, even though it is the same entity. + upcCfg := entityConfig(t, 0) + skuCfg := entityConfigForRepresentation(t, 0, productRepresentation(t, "sku")) + rc := NewController(store, nil).BeginRequest(nil) + + l1Fetch(t, rc, upcCfg, + astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","sku":"S1"}`)), + astjson.MustParseBytes([]byte(fresh))) + + itemB := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1","sku":"S1"}`)) + decision, handleB := prepare(t, rc, skuCfg, itemB) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handleB.Items[0].FromCache) + assert.Empty(t, store.ops) + }) + + t.Run("negative L1: an EmptyEntity result serves the next lookup as a negative hit", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 0) + // The coverage tree must allow a null entity for the sentinel path. + cfg.ProvidesData = &resolve.Object{ + Nullable: true, + Fields: cfg.ProvidesData.Fields, + } + rc := NewController(store, nil).BeginRequest(nil) + itemA := productItem(t, "404") + decision, handleA := prepare(t, rc, cfg, itemA) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handleA, resolve.MergeInput{ + Items: []*astjson.Value{itemA}, + ResponseData: astjson.MustParseBytes([]byte(`null`)), + EmptyEntity: true, + Arena: beginner(), + })) + + itemB := productItem(t, "404") + decisionB, handleB := prepare(t, rc, cfg, itemB) + assert.Equal(t, resolve.DecisionSkipFullHit, decisionB) + assert.True(t, handleB.Items[0].NegativeHit) + assert.Empty(t, store.ops) + }) + + t.Run("[H4] shadow stashes an L1-selected value too: read-never-serve stays absolute", func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) // L1 + L2 + shadow + rc := NewController(store, nil).BeginRequest(nil) + l1Fetch(t, rc, cfg, productItem(t, "1"), astjson.MustParseBytes([]byte(fresh))) + + itemB := productItem(t, "1") + decision, handleB := prepare(t, rc, cfg, itemB) + assert.Equal(t, resolve.DecisionFetchShadow, decision) + assert.Nil(t, handleB.Items[0].FromCache) + require.Contains(t, handleB.ShadowStash, 0) + assert.Equal(t, fresh, string(handleB.ShadowStash[0].CachedValue.MarshalTo(nil))) + }) + + t.Run("no bleed across requests: a fresh request cache starts with an empty L1", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 0) + controller := NewController(store, nil) + l1Fetch(t, controller.BeginRequest(nil), cfg, productItem(t, "1"), astjson.MustParseBytes([]byte(fresh))) + + // A NEW request (e.g. the next subscription event after clone): miss. + decision, _ := prepare(t, controller.BeginRequest(nil), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + }) +} diff --git a/v2/pkg/engine/cache/controller_negative_test.go b/v2/pkg/engine/cache/controller_negative_test.go new file mode 100644 index 0000000000..05fa37fdbc --- /dev/null +++ b/v2/pkg/engine/cache/controller_negative_test.go @@ -0,0 +1,188 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// negativeConfig is the entity config with negative caching enabled. +func negativeConfig(t *testing.T, negativeTTL time.Duration) *resolve.FetchCacheConfig { + t.Helper() + cfg := entityConfig(t, time.Minute) + cfg.NegativeCacheTTL = negativeTTL + return cfg +} + +// emptyEntityInput is the loader's post-merge view of a SUCCESSFUL fetch that +// returned no entity: parsed response, null data, EmptyEntity set. +func emptyEntityInput(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`null`)), + EmptyEntity: true, + StatusCode: 200, + Arena: beginner(), + } +} + +// TestControllerNegativeRows covers the G rows. +func TestControllerNegativeRows(t *testing.T) { + newRC := func(store Store) resolve.RequestCache { + return NewController(store, nil).BeginRequest(nil) + } + + t.Run("[G1] empty entity writes the exact sentinel with NegativeCacheTTL", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + rc := newRC(store) + item := productItem(t, "404") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, emptyEntityInput(item))) + rc.EndRequest() + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + // The sentinel is a null DATA member; it records no field + // types, since it describes no fields. + { + Key: key, + Value: `{"data":null,"cc":{"ttl":5,"created":946684800,"scope":"public"}}`, + TTL: 5 * time.Second, + // A purge of the entity must clear its "does not + // exist" record too, so the sentinel carries the + // entity's full tag set. + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:0256cf786a3c1be7", // upc "404" + }, + }, + }, + }, + }, store.ops) + assert.True(t, handle.Items[0].NegativeHit) + require.NotNil(t, handle.Items[0].FromCache) + assert.Equal(t, astjson.TypeNull, handle.Items[0].FromCache.Type()) + }) + }) + + t.Run("[G2] NegativeCacheTTL == 0 disables the L2 path: zero store writes", func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 0) + cfg.L1 = false // isolate the L2 rule; the L1 sentinel has no TTL knob + rc := newRC(store) + item := productItem(t, "404") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, emptyEntityInput(item))) + rc.EndRequest() + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + }, store.ops) + assert.False(t, handle.Items[0].NegativeHit) + }) + + t.Run("[G3] a sentinel hit serves null with zero network and NegativeHit recorded", func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + // Prime the sentinel through the controller itself (read key == write key). + primeRC := newRC(store) + primeItem := productItem(t, "404") + _, primeHandle := prepare(t, primeRC, cfg, primeItem) + require.NoError(t, primeRC.OnFetchResult(primeHandle, emptyEntityInput(primeItem))) + primeRC.EndRequest() + + rc := newRC(store) + item := productItem(t, "404") + decision, handle := prepare(t, rc, cfg, item) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + require.Len(t, handle.Items, 1) + assert.True(t, handle.Items[0].NegativeHit) + require.NotNil(t, handle.Items[0].FromCache) + assert.Equal(t, astjson.TypeNull, handle.Items[0].FromCache.Type()) + + // The splice leaves the target UNTOUCHED (exactly like a real + // successful-but-empty fetch, whose mergeResult early-returns), so the + // resolvable renders the identical null bubble and error either way. + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + Arena: beginner(), + })) + assert.Equal(t, `{"__typename":"Product","upc":"404"}`, string(item.MarshalTo(nil))) + }) + + t.Run("[G4] the sentinel expires after NegativeCacheTTL and the network runs again", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + primeRC := newRC(store) + primeItem := productItem(t, "404") + _, primeHandle := prepare(t, primeRC, cfg, primeItem) + require.NoError(t, primeRC.OnFetchResult(primeHandle, emptyEntityInput(primeItem))) + primeRC.EndRequest() + + decision, _ := prepare(t, newRC(store), cfg, productItem(t, "404")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + + time.Sleep(5*time.Second + time.Second) + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "404")) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.False(t, handle.Items[0].NegativeHit) + }) + }) + + t.Run("[G5] EmptyEntity with a failure signal never writes", func(t *testing.T) { + failureRows := []struct { + name string + mutate func(in *resolve.MergeInput) + }{ + {"FetchFailed wins over EmptyEntity", func(in *resolve.MergeInput) { in.FetchFailed = true }}, + {"HasErrors wins over EmptyEntity", func(in *resolve.MergeInput) { in.HasErrors = true }}, + {"both signals", func(in *resolve.MergeInput) { in.FetchFailed = true; in.HasErrors = true }}, + } + for _, row := range failureRows { + t.Run(row.name, func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + rc := newRC(store) + item := productItem(t, "404") + _, handle := prepare(t, rc, cfg, item) + in := emptyEntityInput(item) + row.mutate(&in) + require.NoError(t, rc.OnFetchResult(handle, in)) + rc.EndRequest() + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + }, store.ops) + assert.False(t, handle.Items[0].NegativeHit) + }) + } + }) + + t.Run("[G6] a positive value with a null FIELD is not a sentinel", func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + // A positive cached value whose nullable field is null: served as a + // normal hit, NEVER routed through the negative path. + writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":null}`) + + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.False(t, handle.Items[0].NegativeHit) + require.NotNil(t, handle.Items[0].FromCache) + assert.Equal(t, astjson.TypeObject, handle.Items[0].FromCache.Type()) + }) +} diff --git a/v2/pkg/engine/cache/controller_privacy_test.go b/v2/pkg/engine/cache/controller_privacy_test.go new file mode 100644 index 0000000000..54c5e4fdf9 --- /dev/null +++ b/v2/pkg/engine/cache/controller_privacy_test.go @@ -0,0 +1,481 @@ +package cache + +import ( + "strconv" + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// partitionProvider is the integrator hook double: one identity per subgraph +// plus a call counter, so rows can pin that the hook runs at most once per +// subgraph per request. A subgraph without an entry answers ok=false. +type partitionProvider struct { + identities map[string]string + calls int +} + +func (p *partitionProvider) PrivatePartition(_ *resolve.Context, subgraphName string) (string, bool) { + p.calls++ + identity, ok := p.identities[subgraphName] + return identity, ok +} + +// flippingProvider hands out a NEW identity on every call, so rows can prove +// the request cache pins the first one. +type flippingProvider struct { + calls int +} + +func (p *flippingProvider) PrivatePartition(*resolve.Context, string) (string, bool) { + p.calls++ + return "identity-" + strconv.Itoa(p.calls), true +} + +// privateContext is a request context whose private cache entries are +// partitioned by the given provider (nil = no provider wired). +func privateContext(t *testing.T, provider resolve.PrivatePartitionProvider) *resolve.Context { + t.Helper() + ctx := resolve.NewContext(t.Context()) + if provider != nil { + ctx.SetPrivatePartitionProvider(provider) + } + return ctx +} + +// privateEntityConfig is the shared entity config declared PRIVATE. +func privateEntityConfig(t *testing.T, ttl time.Duration) *resolve.FetchCacheConfig { + t.Helper() + cfg := entityConfig(t, ttl) + cfg.Private = true + return cfg +} + +// prepareWithHeaderHash runs one PrepareFetch for an item whose subgraph +// request carries the given forwarded-header hash. +func prepareWithHeaderHash(rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, headerHash uint64, item *astjson.Value) (resolve.Decision, *resolve.FetchCacheHandle) { + in := prepareInput(cfg, item) + in.HeaderHash = headerHash + return rc.PrepareFetch(in) +} + +// TestControllerPrivatePartitionSources covers where the requester identity +// comes from and what happens when there is none. +func TestControllerPrivatePartitionSources(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("the provider identity keys the entry, and the envelope records the scope", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + ctx := privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-a"}}) + rc := NewController(store, nil).BeginRequest(ctx) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "") + + key := handle.Items[0].RenderedKey + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:{"__typename":"Product","representation":{"upc":"1"},"partition":"`+sha256Hex("i:user-a")+`"}`)), + key) + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"private"}}`, + TTL: time.Minute, + // A private entry's tags are what a public entry of + // the same entity would carry — no identity material + // anywhere — so one purge reaches every partition. + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("without a provider the forwarded-header hash is the identity", func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + cfg.IncludeSubgraphHeaders = true + rc := NewController(store, nil).BeginRequest(privateContext(t, nil)) + _, handle := prepareWithHeaderHash(rc, cfg, 42, productItem(t, "1")) + require.NotNil(t, handle) + + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:{"__typename":"Product","representation":{"upc":"1"},"partition":"`+sha256Hex("h:"+hex64(42))+`"}`)), + handle.Items[0].RenderedKey) + }) + + t.Run("the provider wins over the header hash", func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + cfg.IncludeSubgraphHeaders = true + ctx := privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-a"}}) + rc := NewController(store, nil).BeginRequest(ctx) + _, handle := prepareWithHeaderHash(rc, cfg, 42, productItem(t, "1")) + require.NotNil(t, handle) + + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:{"__typename":"Product","representation":{"upc":"1"},"partition":"`+sha256Hex("i:user-a")+`"}`)), + handle.Items[0].RenderedKey) + }) + + t.Run("an empty provider value is no identity at all", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := privateEntityConfig(t, time.Minute) + // The provider answers ok=true with an empty identity — every requester + // it cannot name would otherwise share one partition. + ctx := privateContext(t, &partitionProvider{identities: map[string]string{"products": ""}}) + rc := NewController(store, obs).BeginRequest(ctx) + fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "") + + assert.Equal(t, []testStoreOp(nil), store.ops) + assert.Equal(t, []UncacheablePrivate{ + {Subgraph: "products", Reason: UncacheablePrivateNoIdentity}, + }, obs.hints) + }) + + t.Run("the provider is consulted once per subgraph per request", func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + provider := &partitionProvider{identities: map[string]string{"products": "user-a"}} + rc := NewController(store, nil).BeginRequest(privateContext(t, provider)) + // Three fetches of the same subgraph: the hook is an integrator callback + // (JWT parse, tenant lookup) and must not run per fetch. + _, first := prepare(t, rc, cfg, productItem(t, "1")) + _, second := prepare(t, rc, cfg, productItem(t, "2")) + _, third := prepare(t, rc, cfg, productItem(t, "3")) + require.NotNil(t, first) + require.NotNil(t, second) + require.NotNil(t, third) + + assert.Equal(t, 1, provider.calls) + }) + + t.Run("one request keys under ONE identity even if the provider changes its mind", func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + // A provider that answers differently on every call is the structural + // worst case: the request must still hold exactly one partition, which is + // what makes the UNPARTITIONED L1 key of every private value safe. + flipping := &flippingProvider{} + rc := NewController(store, nil).BeginRequest(privateContext(t, flipping)) + _, first := prepare(t, rc, cfg, productItem(t, "1")) + _, second := prepare(t, rc, cfg, productItem(t, "2")) + require.NotNil(t, first) + require.NotNil(t, second) + + firstPartition := sha256Hex("i:identity-1") + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:{"__typename":"Product","representation":{"upc":"1"},"partition":"`+firstPartition+`"}`)), + first.Items[0].RenderedKey) + assert.Equal(t, + "v1:products:"+hashHex([]byte(`v1:products:{"__typename":"Product","representation":{"upc":"2"},"partition":"`+firstPartition+`"}`)), + second.Items[0].RenderedKey) + }) +} + +// TestControllerPrivateWithoutIdentity is the no-identity rule: the store is +// skipped ENTIRELY — reads, value writes, and the negative sentinel — while the +// request-lifetime layer keeps working. +func TestControllerPrivateWithoutIdentity(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("no store op at all, and the fetch still serves its sibling from L1", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := privateEntityConfig(t, time.Minute) + rc := NewController(store, obs).BeginRequest(privateContext(t, nil)) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "") + + // No key was derived, so nothing could be read or written. + assert.Equal(t, "", handle.Items[0].RenderedKey) + assert.Equal(t, []testStoreOp(nil), store.ops) + // L1 keyed the item all the same: a sibling fetch of the same entity + // serves without a network hop. + decision, sibling := prepare(t, rc, cfg, productItem(t, "1")) + require.NotNil(t, sibling) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.Equal(t, `products:{"__typename":"Product","representation":{"upc":"1"}}`, sibling.Items[0].L1Key) + // One hint per fetch that lost its store access — two fetches here. + assert.Equal(t, []UncacheablePrivate{ + {Subgraph: "products", Reason: UncacheablePrivateNoIdentity}, + {Subgraph: "products", Reason: UncacheablePrivateNoIdentity}, + }, obs.hints) + }) + + t.Run("the negative sentinel is skipped too, and stays known-missing in L1", func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + cfg.NegativeCacheTTL = 5 * time.Second + rc := NewController(store, nil).BeginRequest(privateContext(t, nil)) + item := productItem(t, "404") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, emptyEntityInput(item))) + rc.EndRequest() + + // A "this entity does not exist" answer can be requester-specific, so it + // never reaches a shared keyspace either. + assert.Equal(t, []testStoreOp(nil), store.ops) + _, sibling := prepare(t, rc, cfg, productItem(t, "404")) + require.NotNil(t, sibling) + assert.True(t, sibling.Items[0].NegativeHit) + }) + + t.Run("a private root field has no cache at all without an identity", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := rootFieldConfig(time.Minute) + cfg.Private = true + rc := NewController(store, obs).BeginRequest(privateContext(t, nil)) + item := rootItem() + decision, handle := rc.PrepareFetch(prepareInput(cfg, item)) + + // Root fields never carry L1, so nothing is left to prepare. + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle) + assert.Equal(t, []testStoreOp(nil), store.ops) + assert.Equal(t, []UncacheablePrivate{ + {Subgraph: "products", Reason: UncacheablePrivateNoIdentity}, + }, obs.hints) + }) +} + +// TestControllerPrivateIsolation is the cross-requester property: two requests +// with different identities never see each other's entries, in either +// direction. +func TestControllerPrivateIsolation(t *testing.T) { + fresh := func(name string) string { + return `{"__typename":"Product","name":"` + name + `","price":100}` + } + + t.Run("two identities warm two entries, each a miss for the other", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + + userA := NewController(store, nil).BeginRequest(privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-a"}})) + keyA := fetchWithCacheControl(t, userA, cfg, productItem(t, "1"), fresh("Table for A"), "").Items[0].RenderedKey + store.ops = nil + + // User B asks for the SAME entity: a different key, so a miss and its + // own write, with user A's value untouched. + userB := NewController(store, nil).BeginRequest(privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-b"}})) + keyB := fetchWithCacheControl(t, userB, cfg, productItem(t, "1"), fresh("Table for B"), "").Items[0].RenderedKey + assert.NotEqual(t, keyA, keyB) + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{keyB}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: keyB, + Value: `{"data":{"__typename":"Product","name":"Table for B","price":100},"cc":{"ttl":60,"created":946684800,"scope":"private"}}`, + TTL: time.Minute, + // Different key, IDENTICAL tags: user B's entry is + // addressable by the same entity tag as user A's. + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + + // Each identity's repeat request hits its OWN entry and reads its OWN + // value back. + store.ops = nil + repeatA := NewController(store, nil).BeginRequest(privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-a"}})) + decision, handle := prepare(t, repeatA, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NotNil(t, handle) + assert.Equal(t, fresh("Table for A"), string(handle.Items[0].FromCache.MarshalTo(nil))) + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{keyA}, Hits: []bool{true}}, + }, store.ops) + }) + }) + + t.Run("two header-hash identities are two entries as well", func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + cfg.IncludeSubgraphHeaders = true + + first := NewController(store, nil).BeginRequest(privateContext(t, nil)) + _, firstHandle := prepareWithHeaderHash(first, cfg, 1, productItem(t, "1")) + require.NotNil(t, firstHandle) + second := NewController(store, nil).BeginRequest(privateContext(t, nil)) + _, secondHandle := prepareWithHeaderHash(second, cfg, 2, productItem(t, "1")) + require.NotNil(t, secondHandle) + + assert.NotEqual(t, firstHandle.Items[0].RenderedKey, secondHandle.Items[0].RenderedKey) + }) +} + +// TestControllerScopeMismatch is the defense-in-depth read guard: an entry +// carrying the other privacy scope was written by a differently-configured +// deployment and is discarded as a miss, in BOTH directions. +func TestControllerScopeMismatch(t *testing.T) { + privateEnvelope := `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"private"}}` + publicEnvelope := `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}` + + t.Run("a private entry found on a public path is never served", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := entityConfig(t, time.Minute) + // Config drift: the subgraph was PRIVATE when this entry was written and + // is PUBLIC now, so the entry sits under a key the public path derives. + _, seeding := prepare(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1")) + require.NotNil(t, seeding) + key := seeding.Items[0].RenderedKey + store.data[key] = testStoreEntry{value: []byte(privateEnvelope), expiresAt: time.Now().Add(time.Hour)} + store.ops = nil + + decision, handle := prepare(t, NewController(store, obs).BeginRequest(nil), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + assert.Nil(t, handle.Items[0].FromCache) + // The entry WAS read and hit — the scope guard, not the lookup, rejected + // it, and the fetch falls back to the origin. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + assert.Equal(t, []ScopeMismatch{ + {Subgraph: "products", StoredScope: "private"}, + }, obs.scopeMismatches) + }) + + t.Run("a public entry found on a private path is never served either", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := privateEntityConfig(t, time.Minute) + ctx := privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-a"}}) + _, seeding := prepare(t, NewController(store, nil).BeginRequest(ctx), cfg, productItem(t, "1")) + require.NotNil(t, seeding) + key := seeding.Items[0].RenderedKey + store.data[key] = testStoreEntry{value: []byte(publicEnvelope), expiresAt: time.Now().Add(time.Hour)} + store.ops = nil + + decision, handle := prepare(t, NewController(store, obs).BeginRequest(ctx), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + assert.Nil(t, handle.Items[0].FromCache) + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + assert.Equal(t, []ScopeMismatch{ + {Subgraph: "products", StoredScope: "public"}, + }, obs.scopeMismatches) + }) + + t.Run("a private negative sentinel on a public path is discarded, not served as missing", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := entityConfig(t, time.Minute) + _, seeding := prepare(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "404")) + require.NotNil(t, seeding) + key := seeding.Items[0].RenderedKey + store.data[key] = testStoreEntry{ + value: []byte(`{"data":null,"cc":{"ttl":5,"created":946684800,"scope":"private"}}`), + expiresAt: time.Now().Add(time.Hour), + } + store.ops = nil + + decision, handle := prepare(t, NewController(store, obs).BeginRequest(nil), cfg, productItem(t, "404")) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + assert.False(t, handle.Items[0].NegativeHit) + assert.Equal(t, []ScopeMismatch{ + {Subgraph: "products", StoredScope: "private"}, + }, obs.scopeMismatches) + }) + + t.Run("a private root-field entry on a public path is discarded", func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := rootFieldConfig(time.Minute) + ctx := variableContext(t, `{"first":1}`) + key := rootFieldCacheKey(cfg, 0, ctx, "") + store.data[key] = testStoreEntry{ + value: []byte(`{"data":{"products":[{"name":"Table"}]},"cc":{"ttl":60,"created":946684800,"scope":"private"}}`), + expiresAt: time.Now().Add(time.Hour), + } + + decision, handle := NewController(store, obs).BeginRequest(ctx).PrepareFetch(prepareInput(cfg, rootItem())) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + assert.Nil(t, handle.Items[0].FromCache) + assert.Equal(t, []ScopeMismatch{ + {Subgraph: "products", StoredScope: "private"}, + }, obs.scopeMismatches) + }) +} + +// TestControllerPrivateHeaderInterplay: on a statically-private fetch the +// runtime directives meet a keyspace that is ALREADY partitioned. +func TestControllerPrivateHeaderInterplay(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("a private response header confirms the declaration and writes anyway", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + obs := &privateObserver{} + cfg := privateEntityConfig(t, time.Minute) + ctx := privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-a"}}) + rc := NewController(store, obs).BeginRequest(ctx) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "private, max-age=30") + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":30,"created":946684800,"scope":"private"}}`, + TTL: 30 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + // Nothing to report: the configuration already caches this + // partitioned, which is exactly what the header asks for. + assert.Equal(t, []UncacheablePrivate(nil), obs.hints) + }) + }) + + t.Run("no-store still kills the write of a partitioned entry", func(t *testing.T) { + store := newTestStore() + cfg := privateEntityConfig(t, time.Minute) + ctx := privateContext(t, &partitionProvider{identities: map[string]string{"products": "user-a"}}) + rc := NewController(store, nil).BeginRequest(ctx) + handle := fetchWithCacheControl(t, rc, cfg, productItem(t, "1"), fresh, "no-store") + + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + }) +} diff --git a/v2/pkg/engine/cache/controller_rootfield_test.go b/v2/pkg/engine/cache/controller_rootfield_test.go new file mode 100644 index 0000000000..e3b9569148 --- /dev/null +++ b/v2/pkg/engine/cache/controller_rootfield_test.go @@ -0,0 +1,195 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// rootFieldConfig is a root-field-scope config over Query.products. +func rootFieldConfig(ttl time.Duration) *resolve.FetchCacheConfig { + cfg := &resolve.FetchCacheConfig{ + L2: ttl > 0, + SubgraphName: "products", + TTL: ttl, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeRootField, + TypeName: "Query", + FieldName: "products", + }, + ProvidesData: &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("products"), + Value: &resolve.Array{ + Nullable: false, + Path: []string{"products"}, + Item: &resolve.Object{ + Nullable: false, + Fields: []*resolve.Field{ + {Name: []byte("name"), Value: &resolve.Scalar{Nullable: false, Path: []string{"name"}}}, + }, + }, + }, + }, + }, + }, + } + resolve.ComputeHasAliases(cfg.ProvidesData) + return cfg +} + +func rootItem() *astjson.Value { + return astjson.MustParseBytes([]byte(`{}`)) +} + +// TestControllerRootFieldRows covers the runtime root-field arms of the D and +// F rows plus the flush and shadow-asymmetry rows. +func TestControllerRootFieldRows(t *testing.T) { + newRC := func(store Store, ctx *resolve.Context) resolve.RequestCache { + return NewController(store, nil).BeginRequest(ctx) + } + responseData := `{"products":[{"name":"Table"},{"name":"Chair"}]}` + + primeRoot := func(t *testing.T, store *testStore, cfg *resolve.FetchCacheConfig, ctx *resolve.Context, data string) string { + t.Helper() + rc := newRC(store, ctx) + item := rootItem() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(data)), + Arena: beginner(), + })) + rc.EndRequest() + return handle.Items[0].RenderedKey + } + + t.Run("[D-root] miss then hit: read key == write key, splice serves the whole value", func(t *testing.T) { + store := newTestStore() + cfg := rootFieldConfig(time.Minute) + key := primeRoot(t, store, cfg, nil, responseData) + store.ops = nil // request 2's ops assert in isolation + + rc := newRC(store, nil) + item := rootItem() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.Equal(t, key, handle.Items[0].RenderedKey) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + Arena: beginner(), + })) + assert.Equal(t, responseData, string(item.MarshalTo(nil))) + rc.EndRequest() + // The hit's single read, under the SAME key the prime wrote. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + }) + + t.Run("[D-root] coverage failure: a smaller cached value never serves a bigger selection", func(t *testing.T) { + store := newTestStore() + cfg := rootFieldConfig(time.Minute) + // The cached value lacks the products field entirely. + key := primeRoot(t, store, cfg, nil, `{"promotions":[]}`) + store.ops = nil // the second request's ops assert in isolation + + decision, handle := prepare(t, newRC(store, nil), cfg, rootItem()) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.Items[0].FromCache) + // The entry WAS read and HIT — coverage, not the lookup, rejected it. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + }) + + t.Run("[key] different variables produce different keys; order does not matter", func(t *testing.T) { + cfg := rootFieldConfig(time.Minute) + ctxA := variableContext(t, `{"a":1,"b":2}`) + ctxAReordered := variableContext(t, `{"b":2,"a":1}`) + ctxB := variableContext(t, `{"a":9,"b":2}`) + keyA := rootFieldCacheKey(cfg, 0, ctxA, "") + keyAReordered := rootFieldCacheKey(cfg, 0, ctxAReordered, "") + keyB := rootFieldCacheKey(cfg, 0, ctxB, "") + assert.Equal(t, keyA, keyAReordered) + assert.NotEqual(t, keyA, keyB) + }) + + t.Run("[F-root] the write gate blocks failed fetches", func(t *testing.T) { + store := newTestStore() + cfg := rootFieldConfig(time.Minute) + rc := newRC(store, nil) + item := rootItem() + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + FetchFailed: true, + Arena: beginner(), + })) + rc.EndRequest() + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{handle.Items[0].RenderedKey}, Hits: []bool{false}}, + }, store.ops) + }) + + t.Run("[H5] root-field shadow: hit force-refetches, ZERO compares, L2 overwritten", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := rootFieldConfig(time.Minute) + cfg.ShadowMode = true + key := primeRoot(t, store, cfg, nil, responseData) + + obs := &recordingShadowObserver{} + rc := NewController(store, obs).BeginRequest(nil) + item := rootItem() + decision, handle := prepare(t, rc, cfg, item) + // The asymmetry: a plain Fetch — no stash, no Shadow flag, so a + // compare is structurally impossible. + assert.Equal(t, resolve.DecisionFetch, decision) + assert.False(t, handle.Shadow) + assert.Nil(t, handle.ShadowStash) + + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"products":[{"name":"Renamed"}]}`)), + Arena: beginner(), + })) + rc.EndRequest() + assert.Empty(t, obs.compares) + stored, ok := store.data[key] + require.True(t, ok) + assert.Equal(t, `{"data":{"products":[{"name":"Renamed"}]},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, string(stored.value)) + }) + }) + + t.Run("[J] NO-OP vs L2 produce identical data through the splice", func(t *testing.T) { + store := newTestStore() + cfg := rootFieldConfig(time.Minute) + primeRoot(t, store, cfg, nil, responseData) + + // L2: served from cache. + rc := newRC(store, nil) + cachedItem := rootItem() + decision, handle := prepare(t, rc, cfg, cachedItem) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{Items: []*astjson.Value{cachedItem}, Arena: beginner()})) + + // NO-OP (nil config): the loader would merge the network response; the + // resulting item data is identical. + networkItem := rootItem() + tx := beginner().Begin() + _, err := tx.MergeValues(networkItem, astjson.MustParseBytes([]byte(responseData))) + tx.Commit() + require.NoError(t, err) + assert.Equal(t, string(networkItem.MarshalTo(nil)), string(cachedItem.MarshalTo(nil))) + }) +} diff --git a/v2/pkg/engine/cache/controller_shadow_test.go b/v2/pkg/engine/cache/controller_shadow_test.go new file mode 100644 index 0000000000..af740f81cd --- /dev/null +++ b/v2/pkg/engine/cache/controller_shadow_test.go @@ -0,0 +1,251 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// shadowConfig is the entity config in shadow mode. +func shadowConfig(t *testing.T) *resolve.FetchCacheConfig { + t.Helper() + cfg := entityConfig(t, time.Minute) + cfg.ShadowMode = true + return cfg +} + +// recordingShadowObserver records the shadow compares as (key, isFresh, age), +// and nothing else. +type recordingShadowObserver struct { + noopObserver + + compares []struct { + key string + isFresh bool + age time.Duration + } +} + +func (o *recordingShadowObserver) CompareShadow(h *resolve.FetchCacheHandle, fresh *astjson.Value, tx *resolve.CacheTransaction) { + for _, entry := range h.ShadowStash { + freshBytes := []byte("null") + if fresh != nil { + freshBytes = fresh.MarshalTo(nil) + } + o.compares = append(o.compares, struct { + key string + isFresh bool + age time.Duration + }{ + key: entry.CacheKey, + isFresh: string(entry.CachedValue.MarshalTo(nil)) == string(freshBytes), + age: entry.CacheTTL - entry.RemainingTTL, + }) + } +} + +// TestControllerShadowRows covers the H rows. +func TestControllerShadowRows(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + primeShadow := func(t *testing.T, store *testStore, cfg *resolve.FetchCacheConfig) string { + t.Helper() + // A shadow MISS behaves exactly like a plain miss: fetch + write. + return writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), fresh) + } + + t.Run("[H1] shadow hit stashes, never serves, and forces the fetch", func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) + key := primeShadow(t, store, cfg) + store.ops = nil // the shadow request's ops assert in isolation + + rc := NewController(store, nil).BeginRequest(nil) + decision, handle := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetchShadow, decision) + assert.True(t, handle.Shadow) + assert.False(t, handle.WasHit) + require.Len(t, handle.Items, 1) + // Nothing is servable; the read is stashed. + assert.Nil(t, handle.Items[0].FromCache) + require.Contains(t, handle.ShadowStash, 0) + assert.Equal(t, key, handle.ShadowStash[0].CacheKey) + assert.Equal(t, fresh, string(handle.ShadowStash[0].CachedValue.MarshalTo(nil))) + // The store shows the read happened and hit (and nothing else). + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + }) + + t.Run("[H2] compare MATCH: exact CacheAge, compare precedes the L2 overwrite", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) + key := primeShadow(t, store, cfg) + + time.Sleep(20 * time.Second) // age the entry inside the bubble + + obs := &recordingShadowObserver{} + rc := NewController(store, obs).BeginRequest(nil) + item := productItem(t, "1") + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetchShadow, decision) + + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(fresh)), + Arena: beginner(), + })) + // The compare ran BEFORE any write (the deferred set flushes at + // EndRequest; the compare is already recorded here). + require.Len(t, obs.compares, 1) + assert.Equal(t, key, obs.compares[0].key) + assert.True(t, obs.compares[0].isFresh) + assert.Equal(t, 20*time.Second, obs.compares[0].age) + + rc.EndRequest() + // L2 was overwritten with the fresh value after the compare; the + // rewrite's envelope carries the CURRENT write moment. + value, ok := store.value(key) + require.True(t, ok) + assert.Equal(t, `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684820,"scope":"public"}}`, string(value)) + }) + }) + + t.Run("[H3] compare MISMATCH: IsFresh false, L2 overwritten with fresh", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) + key := primeShadow(t, store, cfg) + + obs := &recordingShadowObserver{} + rc := NewController(store, obs).BeginRequest(nil) + item := productItem(t, "1") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Renamed","price":100}`)), + Arena: beginner(), + })) + require.Len(t, obs.compares, 1) + assert.False(t, obs.compares[0].isFresh) + + rc.EndRequest() + value, ok := store.value(key) + require.True(t, ok) + assert.Equal(t, `{"data":{"__typename":"Product","name":"Renamed","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, string(value)) + }) + }) + + t.Run("envelope metadata is not staleness: only the data reaches the compare", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) + key := primeShadow(t, store, cfg) + // Rewrite the entry with the SAME data under a DIFFERENT write + // moment and TTL, so the entry is selected and only its metadata + // differs. + store.data[key] = testStoreEntry{ + value: []byte(`{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":600,"created":946600000,"scope":"public"}}`), + expiresAt: time.Now().Add(time.Minute), + } + + obs := &recordingShadowObserver{} + rc := NewController(store, obs).BeginRequest(nil) + item := productItem(t, "1") + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetchShadow, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(fresh)), + Arena: beginner(), + })) + require.Len(t, obs.compares, 1) + assert.True(t, obs.compares[0].isFresh) + }) + }) + + t.Run("[H6] nil observer: force-fetch, nothing recorded, writes still land", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) + key := primeShadow(t, store, cfg) + + rc := NewController(store, nil).BeginRequest(nil) + item := productItem(t, "1") + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetchShadow, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(fresh)), + Arena: beginner(), + })) + rc.EndRequest() + value, ok := store.value(key) + require.True(t, ok) + assert.Equal(t, `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, string(value)) + }) + }) + + t.Run("[H7] L2-off shadow never yields DecisionFetchShadow", func(t *testing.T) { + cfg := shadowConfig(t) + cfg.L2 = false + cfg.L1 = false // NO-OP shape: the controller stays out entirely + rc := NewController(newTestStore(), nil).BeginRequest(nil) + decision, handle := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle) + }) + + t.Run("[H7] L1-only shadow is a plain fetch with no stash", func(t *testing.T) { + cfg := shadowConfig(t) + cfg.L2 = false // L1 stays true: shadow semantics are L2-read-only + store := newTestStore() + rc := NewController(store, nil).BeginRequest(nil) + decision, handle := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + assert.False(t, handle.Shadow) + assert.Empty(t, store.ops) + }) + + t.Run("[H] a shadow probe never populates L1: the second read still probes L2", func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) // L1 + L2 + shadow + key := primeShadow(t, store, cfg) + store.ops = nil // the shadow request's ops assert in isolation + + rc := NewController(store, nil).BeginRequest(nil) + _, handleA := prepare(t, rc, cfg, productItem(t, "1")) + stashA, okA := handleA.ShadowStash[0] + require.True(t, okA) + assert.Equal(t, fresh, string(stashA.CachedValue.MarshalTo(nil))) + _, handleB := prepare(t, rc, cfg, productItem(t, "1")) + stashB, okB := handleB.ShadowStash[0] + require.True(t, okB) + assert.Equal(t, fresh, string(stashB.CachedValue.MarshalTo(nil))) + // BOTH reads hit L2: only SERVED values enter the request's L1, and a + // shadow probe serves nothing. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + }) + + t.Run("[H] shadow miss is a plain fetch (no stash, no shadow decision)", func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) + rc := NewController(store, nil).BeginRequest(nil) + decision, handle := prepare(t, rc, cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.False(t, handle.Shadow) + assert.Nil(t, handle.ShadowStash) + }) +} diff --git a/v2/pkg/engine/cache/controller_store_test.go b/v2/pkg/engine/cache/controller_store_test.go new file mode 100644 index 0000000000..562114f67d --- /dev/null +++ b/v2/pkg/engine/cache/controller_store_test.go @@ -0,0 +1,574 @@ +package cache + +import ( + "context" + "errors" + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// storeFetchInput is prepareInput carrying the fetch item the controller reads +// the subgraph name from for store-failure reporting. +func storeFetchInput(cfg *resolve.FetchCacheConfig, items ...*astjson.Value) resolve.PrepareFetchInput { + in := prepareInput(cfg, items...) + in.Item = &resolve.FetchItem{ + Fetch: &resolve.EntityFetch{Info: &resolve.FetchInfo{DataSourceName: "inventory"}}, + } + return in +} + +// storeErrorObserver is the observer double for the store-failure rows: it +// records OnStoreError as the very StoreError the production observer keeps, +// and nothing else. +type storeErrorObserver struct { + noopObserver + + storeErrors []StoreError +} + +func (o *storeErrorObserver) OnStoreError(op string, subgraph string, keyCount int, err error) { + o.storeErrors = append(o.storeErrors, StoreError{ + Op: op, + Subgraph: subgraph, + KeyCount: keyCount, + Err: err, + }) +} + +// ctxCapturingStore records the context each call ran under. +type ctxCapturingStore struct { + getCtx context.Context + setCtx context.Context +} + +func (s *ctxCapturingStore) GetMany(ctx context.Context, keys []string) ([]Entry, error) { + s.getCtx = ctx + return make([]Entry, len(keys)), nil +} + +func (s *ctxCapturingStore) SetMany(ctx context.Context, _ []Item) error { + s.setCtx = ctx + return nil +} + +// misalignedStore answers with FEWER entries than it was asked keys — the +// contract violation that would otherwise serve values under the wrong keys. +type misalignedStore struct { + entries []Entry +} + +func (s *misalignedStore) GetMany(context.Context, []string) ([]Entry, error) { + return s.entries, nil +} + +func (s *misalignedStore) SetMany(context.Context, []Item) error { return nil } + +// TestControllerStoreBatching pins the store call SHAPE: one read per fetch +// carrying every key that fetch still needs, one write per request carrying +// every deferred item, and no call at all when there is nothing to ask for. +func TestControllerStoreBatching(t *testing.T) { + table := `{"__typename":"Product","name":"Table","price":100}` + desk := `{"__typename":"Product","name":"Desk","price":80}` + + t.Run("a 3-entity batch issues ONE read carrying all three keys", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + + buckets := [][]*astjson.Value{ + {productItem(t, "1")}, + {productItem(t, "2")}, + {productItem(t, "3")}, + } + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.Equal(t, resolve.DecisionFetch, decision) + require.Len(t, handle.Items, 3) + + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{ + handle.Items[0].RenderedKey, + handle.Items[1].RenderedKey, + handle.Items[2].RenderedKey, + }, + Hits: []bool{false, false, false}, + }, + }, store.ops) + }) + + t.Run("positional entries: a mixed batch serves exactly the primed positions", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + // Buckets 0 and 2 are primed with DISTINCT values; bucket 1 is not, so a + // misaligned answer could not pass unnoticed. + key1 := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), table) + key3 := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "3"), desk) + store.ops = nil // the mixed batch's ops assert in isolation + + rc := NewController(store, nil).BeginRequest(nil) + buckets := [][]*astjson.Value{ + {productItem(t, "1")}, + {productItem(t, "2")}, + {productItem(t, "3")}, + } + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + // Full-batch semantics: ANY uncovered bucket refetches everything. + require.Equal(t, resolve.DecisionFetch, decision) + require.Len(t, handle.Items, 3) + + require.NotNil(t, handle.Items[0].FromCache) + assert.Equal(t, table, string(handle.Items[0].FromCache.MarshalTo(nil))) + assert.Nil(t, handle.Items[1].FromCache) + require.NotNil(t, handle.Items[2].FromCache) + assert.Equal(t, desk, string(handle.Items[2].FromCache.MarshalTo(nil))) + + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{key1, handle.Items[1].RenderedKey, key3}, + Hits: []bool{true, false, true}, + }, + }, store.ops) + }) + + t.Run("a single-entity fetch reads exactly one key", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + + decision, handle := prepare(t, rc, cfg, productItem(t, "1")) + require.Equal(t, resolve.DecisionFetch, decision) + require.Len(t, handle.Items, 1) + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{handle.Items[0].RenderedKey}, + Hits: []bool{false}, + }, + }, store.ops) + }) + + t.Run("a root-field fetch reads exactly one key", func(t *testing.T) { + store := newTestStore() + cfg := rootFieldConfig(time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + + decision, handle := prepare(t, rc, cfg, rootItem()) + require.Equal(t, resolve.DecisionFetch, decision) + require.Len(t, handle.Items, 1) + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{handle.Items[0].RenderedKey}, + Hits: []bool{false}, + }, + }, store.ops) + }) + + t.Run("keys already served from L1 stay out of the batch read", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) // L1 + L2 + rc := NewController(store, nil).BeginRequest(nil) + + // Fetch A populates L1 (and defers its L2 write) for upc 1. + item := productItem(t, "1") + _, handleA := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handleA, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(table)), + Arena: beginner(), + })) + + // The batch needs upc 1 and upc 2, but only upc 2 reaches the store. + buckets := [][]*astjson.Value{{productItem(t, "1")}, {productItem(t, "2")}} + _, handleB := rc.PrepareFetch(batchInput(cfg, buckets...)) + require.Len(t, handleB.Items, 2) + require.NotNil(t, handleB.Items[0].FromCache) + assert.Equal(t, "l1", handleB.Items[0].ServedFromLayer) + assert.Nil(t, handleB.Items[1].FromCache) + + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{handleA.Items[0].RenderedKey}, + Hits: []bool{false}, + }, + { + Kind: "GetMany", + Keys: []string{handleB.Items[1].RenderedKey}, + Hits: []bool{false}, + }, + }, store.ops) + }) + + t.Run("EndRequest writes every deferred item in ONE call with its own TTL", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + minuteCfg := entityConfig(t, time.Minute) + halfMinuteCfg := entityConfig(t, 30*time.Second) + negativeCfg := entityConfig(t, time.Minute) + negativeCfg.NegativeCacheTTL = 5 * time.Second + rc := NewController(store, nil).BeginRequest(nil) + + itemA := productItem(t, "1") + _, handleA := rc.PrepareFetch(prepareInput(minuteCfg, itemA)) + require.NoError(t, rc.OnFetchResult(handleA, resolve.MergeInput{ + Items: []*astjson.Value{itemA}, + ResponseData: astjson.MustParseBytes([]byte(table)), + Arena: beginner(), + })) + + itemB := productItem(t, "2") + _, handleB := rc.PrepareFetch(prepareInput(halfMinuteCfg, itemB)) + require.NoError(t, rc.OnFetchResult(handleB, resolve.MergeInput{ + Items: []*astjson.Value{itemB}, + ResponseData: astjson.MustParseBytes([]byte(desk)), + Arena: beginner(), + })) + + itemC := productItem(t, "404") + _, handleC := rc.PrepareFetch(prepareInput(negativeCfg, itemC)) + require.NoError(t, rc.OnFetchResult(handleC, resolve.MergeInput{ + Items: []*astjson.Value{itemC}, + ResponseData: astjson.MustParseBytes([]byte(`null`)), + EmptyEntity: true, + Arena: beginner(), + })) + + rc.EndRequest() + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{handleA.Items[0].RenderedKey}, + Hits: []bool{false}, + }, + { + Kind: "GetMany", + Keys: []string{handleB.Items[0].RenderedKey}, + Hits: []bool{false}, + }, + { + Kind: "GetMany", + Keys: []string{handleC.Items[0].RenderedKey}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: handleA.Items[0].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: handleB.Items[0].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"Desk","price":80},"cc":{"ttl":30,"created":946684800,"scope":"public"}}`, + TTL: 30 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:4f93140518d68e67", // upc "2" + }, + }, + { + Key: handleC.Items[0].RenderedKey, + Value: `{"data":null,"cc":{"ttl":5,"created":946684800,"scope":"public"}}`, + TTL: 5 * time.Second, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:0256cf786a3c1be7", // upc "404" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("both store calls run under the request's own context", func(t *testing.T) { + store := &ctxCapturingStore{} + cfg := entityConfig(t, time.Minute) + ctx := resolve.NewContext(t.Context()) + rc := NewController(store, nil).BeginRequest(ctx) + + item := productItem(t, "1") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(table)), + Arena: beginner(), + })) + rc.EndRequest() + + assert.Equal(t, t.Context(), store.getCtx) + assert.Equal(t, t.Context(), store.setCtx) + }) + + t.Run("a controller without a request context falls back to the background context", func(t *testing.T) { + store := &ctxCapturingStore{} + cfg := entityConfig(t, time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + + item := productItem(t, "1") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(table)), + Arena: beginner(), + })) + rc.EndRequest() + + assert.Equal(t, context.Background(), store.getCtx) + assert.Equal(t, context.Background(), store.setCtx) + }) + + t.Run("a fetch with nothing to look up issues no read at all", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + + // An unrenderable key (no upc) leaves the batch read empty. + unrenderable := astjson.MustParseBytes([]byte(`{"__typename":"Product"}`)) + _, handle := prepare(t, rc, cfg, unrenderable) + require.NotNil(t, handle) + assert.Equal(t, "", handle.Items[0].RenderedKey) + assert.Empty(t, store.ops) + + // A batch whose every bucket is already served by L1 does the same. + item := productItem(t, "1") + _, warmup := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(warmup, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(table)), + Arena: beginner(), + })) + store.ops = nil // the all-L1 batch's ops assert in isolation + + buckets := [][]*astjson.Value{{productItem(t, "1")}, {productItem(t, "1")}} + decision, l1Handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.Equal(t, "l1", l1Handle.Items[0].ServedFromLayer) + assert.Equal(t, "l1", l1Handle.Items[1].ServedFromLayer) + assert.Empty(t, store.ops) + }) +} + +// TestControllerStoreFailures pins the degradation contract: a failed read is +// a miss for every key it carried, a failed write is dropped, neither fails the +// request, and each failure is reported to the observer exactly once. +func TestControllerStoreFailures(t *testing.T) { + table := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("a failed read misses every key, refetches, and still writes back", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + // Both entities ARE cached: only the injected failure hides them. + key1 := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), table) + key2 := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), `{"__typename":"Product","name":"Desk","price":80}`) + store.ops = nil // the failing request's ops assert in isolation + + readErr := errors.New("store read down") + store.failGetMany, store.failGetManyErr = 1, readErr + obs := &storeErrorObserver{} + rc := NewController(store, obs).BeginRequest(nil) + + buckets := [][]*astjson.Value{{productItem(t, "1")}, {productItem(t, "2")}} + in := batchInput(cfg, buckets...) + in.Item = &resolve.FetchItem{ + Fetch: &resolve.EntityFetch{Info: &resolve.FetchInfo{DataSourceName: "inventory"}}, + } + decision, handle := rc.PrepareFetch(in) + // Every key of the failed call is a miss, so the fetch proceeds. + assert.Equal(t, resolve.DecisionFetch, decision) + assert.False(t, handle.WasHit) + assert.Nil(t, handle.Items[0].FromCache) + assert.Nil(t, handle.Items[1].FromCache) + + // ONE event for the whole failed call, naming the fetch's subgraph. + assert.Equal(t, []StoreError{ + {Op: "GetMany", Subgraph: "inventory", KeyCount: 2, Err: readErr}, + }, obs.storeErrors) + + // The refetch's write-back is unaffected by the failed read. + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[` + table + `,{"__typename":"Product","name":"Desk","price":80}]`)), + Arena: beginner(), + })) + rc.EndRequest() + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{key1, key2}, + Failed: true, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key1, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: key2, + Value: `{"data":{"__typename":"Product","name":"Desk","price":80},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("an answer that does not align with the keys is refused wholesale", func(t *testing.T) { + // The store answers ONE entry for TWO keys: accepting it would serve + // entity 1's value for entity 2. + store := &misalignedStore{ + entries: []Entry{ + {Value: []byte(table), OK: true}, + }, + } + cfg := entityConfig(t, time.Minute) + obs := &storeErrorObserver{} + rc := NewController(store, obs).BeginRequest(nil) + + buckets := [][]*astjson.Value{{productItem(t, "1")}, {productItem(t, "2")}} + decision, handle := rc.PrepareFetch(batchInput(cfg, buckets...)) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.Items[0].FromCache) + assert.Nil(t, handle.Items[1].FromCache) + assert.Equal(t, []StoreError{ + { + Op: "GetMany", + Subgraph: "", + KeyCount: 2, + Err: errors.New("store returned 1 entries for 2 keys"), + }, + }, obs.storeErrors) + }) + + t.Run("a failed write is dropped without failing the request", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeErr := errors.New("store write down") + store.failSetMany, store.failSetManyErr = 1, writeErr + obs := &storeErrorObserver{} + rc := NewController(store, obs).BeginRequest(nil) + + item := productItem(t, "1") + _, handle := rc.PrepareFetch(storeFetchInput(cfg, item)) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(table)), + Arena: beginner(), + })) + // The item is served from the response either way; the merge target + // carries the fetched value untouched by the store failure. + rc.EndRequest() + + key := handle.Items[0].RenderedKey + _, stored := store.value(key) + assert.False(t, stored) + // The flush spans every fetch of the request, so it names no subgraph. + assert.Equal(t, []StoreError{ + {Op: "SetMany", Subgraph: "", KeyCount: 1, Err: writeErr}, + }, obs.storeErrors) + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{false}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + Failed: true, + }, + }, store.ops) + }) + }) + + t.Run("a nil observer swallows failures at zero cost", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + store.failGetMany, store.failGetManyErr = 1, errors.New("store read down") + store.failSetMany, store.failSetManyErr = 1, errors.New("store write down") + rc := NewController(store, nil).BeginRequest(nil) + + item := productItem(t, "1") + decision, handle := prepare(t, rc, cfg, item) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(table)), + Arena: beginner(), + })) + rc.EndRequest() + + key := handle.Items[0].RenderedKey + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Failed: true, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + Failed: true, + }, + }, store.ops) + }) + }) +} diff --git a/v2/pkg/engine/cache/controller_test.go b/v2/pkg/engine/cache/controller_test.go new file mode 100644 index 0000000000..c4584a51e0 --- /dev/null +++ b/v2/pkg/engine/cache/controller_test.go @@ -0,0 +1,673 @@ +package cache + +import ( + "context" + "slices" + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// testStore is the minimal in-memory Store for controller unit tests, with an +// ordered op log — ONE entry per call — mirroring cachetesting.FakeStore +// (which cannot be imported here: cachetesting imports this package) and +// per-op failure injection. +type testStore struct { + data map[string]testStoreEntry + ops []testStoreOp + + failGetMany int + failGetManyErr error + failSetMany int + failSetManyErr error +} + +type testStoreEntry struct { + value []byte + expiresAt time.Time + // noTTL marks an entry whose remaining TTL is UNKNOWN: the read reports it + // as a hit with remaining 0 (some backends do not expose TTLs). + noTTL bool +} + +type testStoreOp struct { + Kind string + Keys []string + Hits []bool + Items []testStoreItem + Failed bool +} + +type testStoreItem struct { + Key string + Value string + TTL time.Duration + Tags []string +} + +func newTestStore() *testStore { + return &testStore{data: map[string]testStoreEntry{}} +} + +func (s *testStore) GetMany(_ context.Context, keys []string) ([]Entry, error) { + if s.failGetMany > 0 { + s.failGetMany-- + s.ops = append(s.ops, testStoreOp{Kind: "GetMany", Keys: slices.Clone(keys), Failed: true}) + return nil, s.failGetManyErr + } + entries := make([]Entry, len(keys)) + hits := make([]bool, len(keys)) + for i, key := range keys { + entry, ok := s.data[key] + if !ok || !time.Now().Before(entry.expiresAt) { + continue + } + entries[i] = Entry{Value: append([]byte(nil), entry.value...), OK: true} + if !entry.noTTL { + entries[i].RemainingTTL = time.Until(entry.expiresAt) + } + hits[i] = true + } + s.ops = append(s.ops, testStoreOp{Kind: "GetMany", Keys: slices.Clone(keys), Hits: hits}) + return entries, nil +} + +// value reads the stored bytes under key WITHOUT logging an op, so assertions +// can inspect the store without disturbing the op log. +func (s *testStore) value(key string) ([]byte, bool) { + entry, ok := s.data[key] + if !ok || !time.Now().Before(entry.expiresAt) { + return nil, false + } + return entry.value, true +} + +func (s *testStore) SetMany(_ context.Context, items []Item) error { + op := testStoreOp{Kind: "SetMany", Items: make([]testStoreItem, 0, len(items))} + for _, item := range items { + op.Items = append(op.Items, testStoreItem{Key: item.Key, Value: string(item.Value), TTL: item.TTL, Tags: slices.Clone(item.Tags)}) + } + if s.failSetMany > 0 { + s.failSetMany-- + op.Failed = true + s.ops = append(s.ops, op) + return s.failSetManyErr + } + for _, item := range items { + s.data[item.Key] = testStoreEntry{value: append([]byte(nil), item.Value...), expiresAt: time.Now().Add(item.TTL)} + } + s.ops = append(s.ops, op) + return nil +} + +// productProvidesData is the coverage tree used across the controller rows: +// name non-nullable, price nullable. +func productProvidesData() *resolve.Object { + return &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"name"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("price"), + Value: &resolve.Scalar{Nullable: true, Path: []string{"price"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + } +} + +// entityConfig builds the shared entity config: the "upc"-keyed Product +// representation the fetch would send, over the key-builder fixture. +func entityConfig(t *testing.T, ttl time.Duration) *resolve.FetchCacheConfig { + t.Helper() + return entityConfigForRepresentation(t, ttl, productRepresentation(t, "upc")) +} + +// entityConfigForRepresentation is entityConfig with an explicit representation +// node, for rows that key on more than the @key set (e.g. @requires fields). +func entityConfigForRepresentation(t *testing.T, ttl time.Duration, node *resolve.Object) *resolve.FetchCacheConfig { + t.Helper() + fetch := entityFetchWith(node) + spec, ok := buildEntitySpec(fetch, fetch.Info) + require.True(t, ok) + return &resolve.FetchCacheConfig{ + L1: true, + L2: ttl > 0, + SubgraphName: "products", + TTL: ttl, + KeySpec: spec, + ProvidesData: productProvidesData(), + } +} + +func beginner() resolve.TransactionBeginner { + return resolve.NewTransactionBeginner(nil, &resolve.DataBuffer{}) +} + +func prepareInput(cfg *resolve.FetchCacheConfig, items ...*astjson.Value) resolve.PrepareFetchInput { + return resolve.PrepareFetchInput{ + Items: items, + Config: cfg, + Input: []byte(`{"body":{"query":"..."}}`), + Arena: beginner(), + } +} + +func productItem(t *testing.T, upc string) *astjson.Value { + t.Helper() + return astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"` + upc + `"}`)) +} + +// prepare runs one PrepareFetch and returns decision + handle. +func prepare(t *testing.T, rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, items ...*astjson.Value) (resolve.Decision, *resolve.FetchCacheHandle) { + t.Helper() + return rc.PrepareFetch(prepareInput(cfg, items...)) +} + +// writeThrough runs the miss → fetch-result → flush cycle for one item and +// returns the key it wrote under. +func writeThrough(t *testing.T, rc resolve.RequestCache, cfg *resolve.FetchCacheConfig, item *astjson.Value, responseData string) string { + t.Helper() + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + require.Len(t, handle.Items, 1) + require.NotEmpty(t, handle.Items[0].RenderedKey) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(responseData)), + Arena: beginner(), + })) + rc.EndRequest() + return handle.Items[0].RenderedKey +} + +// TestControllerDecisionRows covers the D core rows: full hit, miss, coverage +// failure (stale partial NOT served), nullability, and ProvidesData == nil. +func TestControllerDecisionRows(t *testing.T) { + newRC := func(store Store) resolve.RequestCache { + return NewController(store, nil).BeginRequest(nil) + } + + t.Run("[D1] full hit: covering value skips the fetch", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + key := writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":100}`) + + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.Equal(t, resolve.DecisionSkipFullHit, handle.Decision) + assert.True(t, handle.WasHit) + require.Len(t, handle.Items, 1) + // Key fidelity (O row): the read key IS the write key. + assert.Equal(t, key, handle.Items[0].RenderedKey) + require.NotNil(t, handle.Items[0].FromCache) + // FromCache stays in the STORED (normalized) form; denormalization to + // the requesting aliases happens at splice time. + assert.Equal(t, `{"__typename":"Product","name":"Table","price":100}`, string(handle.Items[0].FromCache.MarshalTo(nil))) + }) + + t.Run("[D2] miss: empty store fetches", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.False(t, handle.WasHit) + require.Len(t, handle.Items, 1) + assert.Nil(t, handle.Items[0].FromCache) + }) + + t.Run("[D3] coverage failure: stale partial value is NOT served", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + // The cached value lacks the non-nullable "name" field. + key := writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","price":100}`) + store.ops = nil // the second request's ops assert in isolation + + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionFetch, decision) + require.Len(t, handle.Items, 1) + assert.Nil(t, handle.Items[0].FromCache) + assert.Equal(t, key, handle.Items[0].RenderedKey) + // The entry WAS read and HIT — coverage, not the lookup, rejected it. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{true}}, + }, store.ops) + }) + + t.Run("[D4] null accepted where nullable", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":null}`) + + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + }) + + t.Run("[D5] null rejected where non-nullable", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":null,"price":100}`) + + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.Items[0].FromCache) + }) + + t.Run("[D14] ProvidesData nil disables the coverage walk: always a miss", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":100}`) + + noProvides := entityConfig(t, time.Minute) + noProvides.ProvidesData = nil + decision, handle := prepare(t, newRC(store), noProvides, productItem(t, "1")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.Items[0].FromCache) + }) + + t.Run("[D] partial hit degrades to fetch (AND-reduction)", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":100}`) + + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1"), productItem(t, "2")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionFetch, decision) + require.Len(t, handle.Items, 2) + assert.NotNil(t, handle.Items[0].FromCache) + assert.Nil(t, handle.Items[1].FromCache) + }) + + t.Run("[L] malformed cached bytes are a miss, never a panic", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + key := writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":100}`) + store.data[key] = testStoreEntry{value: []byte(`{not json`), expiresAt: time.Now().Add(time.Hour)} + + decision, handle := prepare(t, newRC(store), cfg, productItem(t, "1")) + require.NotNil(t, handle) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.Items[0].FromCache) + }) + + t.Run("[F/TTL] a written value expires exactly after its TTL", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeThrough(t, newRC(store), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":100}`) + + decision, _ := prepare(t, newRC(store), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + + time.Sleep(time.Minute + time.Second) + decision, _ = prepare(t, newRC(store), cfg, productItem(t, "1")) + assert.Equal(t, resolve.DecisionFetch, decision) + }) + }) +} + +// TestControllerWriteGateRows covers the F rows: only a clean fetch writes; +// transport/empty/parse failures, GraphQL errors, null data, status fallback, +// and empty entities all produce ZERO writes. +func TestControllerWriteGateRows(t *testing.T) { + prepareMiss := func(t *testing.T, store *testStore, cfg *resolve.FetchCacheConfig, item *astjson.Value) (resolve.RequestCache, *resolve.FetchCacheHandle) { + t.Helper() + rc := NewController(store, nil).BeginRequest(nil) + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + return rc, handle + } + + t.Run("[F1] clean fetch writes exactly once with the exact TTL", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + item := productItem(t, "1") + rc, handle := prepareMiss(t, store, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)), + StatusCode: 200, + Arena: beginner(), + })) + key := handle.Items[0].RenderedKey + rc.EndRequest() + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) + + gateRows := []struct { + name string + in func(item *astjson.Value) resolve.MergeInput + }{ + { + // The historical blocking bug: transport failures arrive with + // HasErrors == false — the gate must key off FetchFailed. + name: "[F2] transport failure writes nothing", + in: func(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{Items: []*astjson.Value{item}, FetchFailed: true, Arena: beginner()} + }, + }, + { + name: "[F3] empty body writes nothing", + in: func(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{Items: []*astjson.Value{item}, FetchFailed: true, StatusCode: 200, Arena: beginner()} + }, + }, + { + name: "[F4] parse failure writes nothing", + in: func(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{Items: []*astjson.Value{item}, FetchFailed: true, StatusCode: 200, Arena: beginner()} + }, + }, + { + name: "[F5] GraphQL errors write nothing even with data present", + in: func(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)), + HasErrors: true, + Arena: beginner(), + } + }, + }, + { + name: "[F6] JSON-null data writes nothing", + in: func(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{Items: []*astjson.Value{item}, ResponseData: astjson.MustParseBytes([]byte(`null`)), Arena: beginner()} + }, + }, + { + name: "[F7] status fallback (failed fetch with 500) writes nothing", + in: func(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{Items: []*astjson.Value{item}, FetchFailed: true, StatusCode: 500, Arena: beginner()} + }, + }, + { + name: "[F8] successful-but-empty entity writes nothing without a negative TTL", + in: func(item *astjson.Value) resolve.MergeInput { + return resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`null`)), + EmptyEntity: true, + StatusCode: 200, + Arena: beginner(), + } + }, + }, + } + for _, row := range gateRows { + t.Run(row.name, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + item := productItem(t, "1") + rc, handle := prepareMiss(t, store, cfg, item) + key := handle.Items[0].RenderedKey + require.NoError(t, rc.OnFetchResult(handle, row.in(item))) + rc.EndRequest() + // Only the lookup read; ZERO writes. + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{key}, Hits: []bool{false}}, + }, store.ops) + }) + } +} + +// TestControllerFlushRows covers the K rows: writes accumulate as bytes and +// flush once per instance at EndRequest. +func TestControllerFlushRows(t *testing.T) { + t.Run("[K1/K2] writes accumulate and flush as one batch at EndRequest", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + + item1 := productItem(t, "1") + item2 := productItem(t, "2") + _, h1 := prepare(t, rc, cfg, item1) + _, h2 := prepare(t, rc, cfg, item2) + require.NoError(t, rc.OnFetchResult(h1, resolve.MergeInput{ + Items: []*astjson.Value{item1}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)), + Arena: beginner(), + })) + require.NoError(t, rc.OnFetchResult(h2, resolve.MergeInput{ + Items: []*astjson.Value{item2}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Chair","price":50}`)), + Arena: beginner(), + })) + + var setsBeforeFlush int + for _, op := range store.ops { + if op.Kind == "SetMany" { + setsBeforeFlush++ + } + } + assert.Equal(t, 0, setsBeforeFlush) + + // Two fetches read separately (one key each) but share the SINGLE + // request-end write call. + rc.EndRequest() + assert.Equal(t, []testStoreOp{ + {Kind: "GetMany", Keys: []string{h1.Items[0].RenderedKey}, Hits: []bool{false}}, + {Kind: "GetMany", Keys: []string{h2.Items[0].RenderedKey}, Hits: []bool{false}}, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: h1.Items[0].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: h2.Items[0].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"Chair","price":50},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:4f93140518d68e67", // upc "2" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("[K3] the flush holds bytes: later value mutation cannot leak into the store", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + item := productItem(t, "1") + _, handle := prepare(t, rc, cfg, item) + responseData := astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: responseData, + Arena: beginner(), + })) + // Mutate the response value AFTER the hook, BEFORE the flush. + responseData.Set(nil, "name", astjson.StringValue(nil, "Mutated")) + rc.EndRequest() + + value, ok := store.value(handle.Items[0].RenderedKey) + require.True(t, ok) + assert.Equal(t, `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, string(value)) + }) + }) + + t.Run("[K4] nothing to flush: EndRequest is a no-op on the store", func(t *testing.T) { + store := newTestStore() + rc := NewController(store, nil).BeginRequest(nil) + rc.EndRequest() + assert.Empty(t, store.ops) + }) +} + +// TestControllerMergePath covers the D4 deviation: splice and write honor the +// surfaced non-root merge path. +func TestControllerMergePath(t *testing.T) { + t.Run("write stores the entity BELOW the merge path", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rc := NewController(store, nil).BeginRequest(nil) + item := productItem(t, "1") + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"wrapper":{"__typename":"Product","name":"Table","price":100}}`)), + MergePath: []string{"wrapper"}, + Arena: beginner(), + })) + rc.EndRequest() + value, ok := store.value(handle.Items[0].RenderedKey) + require.True(t, ok) + // The entity below the merge path is what the envelope carries. + assert.Equal(t, `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, string(value)) + }) + }) + + t.Run("splice merges the cached value AT the merge path", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":100}`) + + rc := NewController(store, nil).BeginRequest(nil) + item := productItem(t, "1") + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + MergePath: []string{"nested"}, + Arena: beginner(), + })) + assert.Equal(t, + `{"__typename":"Product","upc":"1","nested":{"name":"Table","price":100,"__typename":"Product"}}`, + string(item.MarshalTo(nil))) + }) + + t.Run("splice merges at the item root when the merge path is empty", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), `{"__typename":"Product","name":"Table","price":100}`) + + rc := NewController(store, nil).BeginRequest(nil) + item := productItem(t, "1") + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + Arena: beginner(), + })) + assert.Equal(t, + `{"__typename":"Product","upc":"1","name":"Table","price":100}`, + string(item.MarshalTo(nil))) + }) +} + +// TestControllerGates covers the prepare-side gates and nil-guards (O rows). +func TestControllerGates(t *testing.T) { + rc := NewController(newTestStore(), nil).BeginRequest(nil) + + t.Run("nil config fetches", func(t *testing.T) { + decision, handle := rc.PrepareFetch(prepareInput(nil, productItem(t, "1"))) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle) + }) + + t.Run("L1-only config participates without touching the store", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, 0) // TTL 0 => L2 false, L1 true + decision, handle := NewController(store, nil).BeginRequest(nil).PrepareFetch(prepareInput(cfg, productItem(t, "1"))) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + assert.Empty(t, store.ops) + }) + + t.Run("[I] empty batch short-circuits without a handle", func(t *testing.T) { + cfg := entityConfig(t, time.Minute) + in := prepareInput(cfg) + in.BatchStats = [][]*astjson.Value{} + decision, handle := rc.PrepareFetch(in) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle) + }) + + t.Run("zero items fetch", func(t *testing.T) { + cfg := entityConfig(t, time.Minute) + decision, handle := rc.PrepareFetch(prepareInput(cfg)) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle) + }) + + t.Run("an unrenderable key is a miss with no write", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + rcMiss := NewController(store, nil).BeginRequest(nil) + item := astjson.MustParseBytes([]byte(`{"__typename":"Product"}`)) // no upc + decision, handle := rcMiss.PrepareFetch(prepareInput(cfg, item)) + assert.Equal(t, resolve.DecisionFetch, decision) + require.NotNil(t, handle) + assert.Equal(t, "", handle.Items[0].RenderedKey) + // The fetch input could not have rendered either, so the fresh response + // has no key to be written under. + require.NoError(t, rcMiss.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)), + Arena: beginner(), + })) + rcMiss.EndRequest() + assert.Empty(t, store.ops) + }) + + t.Run("merge hooks tolerate nil handles and unknown handles", func(t *testing.T) { + assert.NoError(t, rc.OnFetchSkipped(nil, resolve.MergeInput{Arena: beginner()})) + assert.NoError(t, rc.OnFetchResult(nil, resolve.MergeInput{Arena: beginner()})) + unknown := &resolve.FetchCacheHandle{} + assert.NoError(t, rc.OnFetchSkipped(unknown, resolve.MergeInput{Arena: beginner()})) + assert.NoError(t, rc.OnFetchResult(unknown, resolve.MergeInput{Arena: beginner()})) + }) +} diff --git a/v2/pkg/engine/cache/coverage.go b/v2/pkg/engine/cache/coverage.go new file mode 100644 index 0000000000..3a40fa0849 --- /dev/null +++ b/v2/pkg/engine/cache/coverage.go @@ -0,0 +1,102 @@ +package cache + +import ( + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// covers is the per-item coverage walk: it reports whether the cached value +// contains EVERY field of the fetch's ProvidesData tree, with null accepted +// only where the schema allows it. A partially-covering (stale-shape) value +// must never be served — the walk is the always-on guard between "some cached +// bytes exist" and "this fetch can be skipped". +// +// Cached values are stored NORMALIZED, so the walk reads fields by +// their normalized name — schema name plus argument suffix — which is exactly +// what makes an argument-mismatched cached field a MISS instead of a hit. +func covers(ctx *resolve.Context, value *astjson.Value, obj *resolve.Object) bool { + if value == nil || obj == nil { + return false + } + typeName := valueTypeName(value) + for _, field := range obj.Fields { + if skipFieldForTypeName(field, typeName) { + continue + } + fieldValue := value.Get(normalizedFieldName(ctx, field)) + if fieldValue == nil { + return false + } + if !coversNode(ctx, fieldValue, field.Value) { + return false + } + } + return true +} + +// valueTypeName reads the cached value's __typename ("" when absent). +func valueTypeName(value *astjson.Value) string { + typeName := value.Get("__typename") + if typeName == nil { + return "" + } + return string(typeName.GetStringBytes()) +} + +// skipFieldForTypeName reports whether a type-conditioned field does not apply +// to the cached value's concrete type: requiring it would turn every valid +// polymorphic response into a coverage miss. An absent __typename keeps the +// field REQUIRED (conservative: no evidence the condition is satisfied means +// no serve). +func skipFieldForTypeName(field *resolve.Field, typeName string) bool { + if len(field.OnTypeNames) == 0 || typeName == "" { + return false + } + for _, onTypeName := range field.OnTypeNames { + if string(onTypeName) == typeName { + return false + } + } + return true +} + +// coversNode applies the coverage rules per node shape: scalars accept null +// only when nullable; objects recurse (null OK when nullable); arrays require +// every element to cover the item shape. +func coversNode(ctx *resolve.Context, value *astjson.Value, node resolve.Node) bool { + switch typed := node.(type) { + case *resolve.Scalar: + return value.Type() != astjson.TypeNull || typed.Nullable + case *resolve.Object: + if value.Type() == astjson.TypeNull { + return typed.Nullable + } + if value.Type() != astjson.TypeObject { + return false + } + return covers(ctx, value, typed) + case *resolve.Array: + if value.Type() == astjson.TypeNull { + return typed.Nullable + } + if value.Type() != astjson.TypeArray { + return false + } + if typed.Item == nil { + return true + } + items, err := value.Array() + if err != nil { + return false + } + for _, item := range items { + if !coversNode(ctx, item, typed.Item) { + return false + } + } + return true + default: + return false + } +} diff --git a/v2/pkg/engine/cache/coverage_test.go b/v2/pkg/engine/cache/coverage_test.go new file mode 100644 index 0000000000..4295b95a69 --- /dev/null +++ b/v2/pkg/engine/cache/coverage_test.go @@ -0,0 +1,59 @@ +package cache + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// TestCoversTypeConditionedFields pins that fields guarded by OnTypeNames are +// required only when the cached value's __typename matches — a concrete-type +// response must not miss coverage because of a SIBLING type's fields. +func TestCoversTypeConditionedFields(t *testing.T) { + polymorphic := &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"name"}}, + OnTypeNames: [][]byte{[]byte("Book"), []byte("Movie")}, + }, + { + Name: []byte("pages"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"pages"}}, + OnTypeNames: [][]byte{[]byte("Book")}, + }, + { + Name: []byte("runtime"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"runtime"}}, + OnTypeNames: [][]byte{[]byte("Movie")}, + }, + }, + } + + t.Run("a Book value covers without the Movie-only field", func(t *testing.T) { + value := astjson.MustParseBytes([]byte(`{"__typename":"Book","name":"Dune","pages":412}`)) + assert.True(t, covers(nil, value, polymorphic)) + }) + + t.Run("a Book value missing its OWN conditioned field does not cover", func(t *testing.T) { + value := astjson.MustParseBytes([]byte(`{"__typename":"Book","name":"Dune"}`)) + assert.False(t, covers(nil, value, polymorphic)) + }) + + t.Run("without __typename every conditioned field stays required (conservative)", func(t *testing.T) { + value := astjson.MustParseBytes([]byte(`{"name":"Dune","pages":412}`)) + assert.False(t, covers(nil, value, polymorphic)) + }) + + t.Run("unconditioned fields are unaffected", func(t *testing.T) { + plain := &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("name"), Value: &resolve.Scalar{Nullable: false, Path: []string{"name"}}}, + }} + assert.True(t, covers(nil, astjson.MustParseBytes([]byte(`{"__typename":"Book","name":"Dune"}`)), plain)) + assert.False(t, covers(nil, astjson.MustParseBytes([]byte(`{"__typename":"Book"}`)), plain)) + }) +} diff --git a/v2/pkg/engine/cache/envelope.go b/v2/pkg/engine/cache/envelope.go new file mode 100644 index 0000000000..c57297dd1c --- /dev/null +++ b/v2/pkg/engine/cache/envelope.go @@ -0,0 +1,105 @@ +package cache + +import ( + "strconv" + "time" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// The value envelope: every L2 entry is stored as +// +// {"data":, +// "cc":{"ttl":60,"created":1785852117,"scope":"public"}} +// +// `data` is the value the read path serves and `cc` carries the freshness +// metadata (the TTL the entry was written with, the unix second it was written +// at, and its privacy scope). L1 never sees an envelope — it holds decoded +// values. + +const ( + // cacheScopePublic marks an entry any requester may be served. + cacheScopePublic = "public" + // cacheScopePrivate marks an entry that belongs to the ONE requester whose + // identity partitions its key. Reading it through a key derivation of the + // other scope is configuration drift and discards the entry. + cacheScopePrivate = "private" +) + +// cacheControl is one entry's freshness and privacy metadata. +type cacheControl struct { + // TTL is the lifetime the entry was written with; it is stored in whole + // seconds. + TTL time.Duration + // Created is the wall-clock write moment, stored as unix seconds, so + // remaining freshness stays computable when the store cannot report it. + Created time.Time + // Scope is the entry's privacy scope. + Scope string +} + +// storedEnvelope is one decoded L2 value: the data to serve, the scope it was +// written under, and the entry's own freshness record. +type storedEnvelope struct { + Data *astjson.Value + Scope string + // TTL is the lifetime the entry was written with and Created the moment of + // the write, so what is LEFT of the entry's freshness is computable from the + // entry alone — the store's own remaining-TTL report is optional (0 means + // unknown) and would read as "expired" wherever a backend does not keep one. + TTL time.Duration + Created time.Time +} + +// encodeEnvelope renders one L2 value. A nil data writes the negative sentinel +// (`"data":null`). This is the ONE place values become stored bytes. +func encodeEnvelope(data *astjson.Value, cc cacheControl) []byte { + buf := make([]byte, 0, 128) + buf = append(buf, `{"data":`...) + if data == nil { + buf = append(buf, "null"...) + } else { + buf = data.MarshalTo(buf) + } + buf = append(buf, `,"cc":{"ttl":`...) + buf = strconv.AppendInt(buf, int64(cc.TTL/time.Second), 10) + buf = append(buf, `,"created":`...) + buf = strconv.AppendInt(buf, cc.Created.Unix(), 10) + buf = append(buf, `,"scope":"`...) + buf = append(buf, cc.Scope...) + buf = append(buf, `"}}`...) + return buf +} + +// decodeEnvelope parses one stored value. ok=false when the bytes are not a +// decodable envelope — unparseable or foreign content is a MISS, never an +// error: the fetch falls back to the origin and its write replaces the entry. +// Entries written under an older format are unreachable by construction (the +// format version leads every key), so a failure here means corruption. +func decodeEnvelope(tx *resolve.CacheTransaction, raw []byte) (storedEnvelope, bool) { + value, err := tx.ParseBytes(raw) + if err != nil || value.Type() != astjson.TypeObject { + return storedEnvelope{}, false + } + data := value.Get("data") + if data == nil { + return storedEnvelope{}, false + } + // Public is the scope reading that can only ever COST a hit (a private entry + // lives under a partitioned key a public read never derives), so it is what + // an entry that records none — a foreign or corrupt one — falls back to. + envelope := storedEnvelope{ + Data: data, + Scope: cacheScopePublic, + } + if cc := value.Get("cc"); cc != nil { + if scope := string(cc.GetStringBytes("scope")); scope != "" { + envelope.Scope = scope + } + envelope.TTL = time.Duration(cc.GetInt64("ttl")) * time.Second + envelope.Created = time.Unix(cc.GetInt64("created"), 0) + } + return envelope, true +} diff --git a/v2/pkg/engine/cache/envelope_test.go b/v2/pkg/engine/cache/envelope_test.go new file mode 100644 index 0000000000..c1f5e0ba03 --- /dev/null +++ b/v2/pkg/engine/cache/envelope_test.go @@ -0,0 +1,176 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// TestEnvelopeEncodeDecode pins the stored form byte for byte and the decode +// contract: an envelope round-trips, and anything that is not one is a MISS +// (ok=false), never an error. +func TestEnvelopeEncodeDecode(t *testing.T) { + t.Run("a value round-trips through the envelope", func(t *testing.T) { + encoded := encodeEnvelope( + astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)), + cacheControl{TTL: time.Minute, Created: time.Unix(1785852117, 0), Scope: cacheScopePublic}, + ) + assert.Equal(t, + `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":1785852117,"scope":"public"}}`, + string(encoded)) + + tx := testTx() + defer tx.Commit() + envelope, ok := decodeEnvelope(tx, encoded) + require.True(t, ok) + assert.Equal(t, `{"__typename":"Product","name":"Table","price":100}`, string(envelope.Data.MarshalTo(nil))) + }) + + t.Run("the negative sentinel is a null data member", func(t *testing.T) { + encoded := encodeEnvelope( + nil, + cacheControl{TTL: 5 * time.Second, Created: time.Unix(1785852117, 0), Scope: cacheScopePublic}, + ) + assert.Equal(t, `{"data":null,"cc":{"ttl":5,"created":1785852117,"scope":"public"}}`, string(encoded)) + + tx := testTx() + defer tx.Commit() + envelope, ok := decodeEnvelope(tx, encoded) + require.True(t, ok) + assert.Equal(t, astjson.TypeNull, envelope.Data.Type()) + }) + + t.Run("a private writer records the private scope, and the reader gets it back", func(t *testing.T) { + encoded := encodeEnvelope( + astjson.MustParseBytes([]byte(`{"name":"Table"}`)), + cacheControl{TTL: time.Minute, Created: time.Unix(1785852117, 0), Scope: cacheScopePrivate}, + ) + assert.Equal(t, `{"data":{"name":"Table"},"cc":{"ttl":60,"created":1785852117,"scope":"private"}}`, string(encoded)) + + tx := testTx() + defer tx.Commit() + envelope, ok := decodeEnvelope(tx, encoded) + require.True(t, ok) + assert.Equal(t, cacheScopePrivate, envelope.Scope) + }) + + t.Run("an entry that records no scope reads as public", func(t *testing.T) { + tx := testTx() + defer tx.Commit() + rows := []struct { + name string + raw string + }{ + {name: "an empty scope", raw: `{"data":{"name":"Table"},"cc":{"ttl":60,"created":1785852117,"scope":""}}`}, + {name: "a cc without a scope member", raw: `{"data":{"name":"Table"},"cc":{"ttl":60,"created":1785852117}}`}, + {name: "no cc at all", raw: `{"data":{"name":"Table"}}`}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + envelope, ok := decodeEnvelope(tx, []byte(row.raw)) + require.True(t, ok) + // Public is the reading that can only ever cost a hit: a private + // entry lives under a key no public read derives. + assert.Equal(t, cacheScopePublic, envelope.Scope) + }) + } + }) + + t.Run("bytes that are not an envelope decode as a miss", func(t *testing.T) { + tx := testTx() + defer tx.Commit() + rows := []struct { + name string + raw string + }{ + {name: "a bare entity value (the pre-envelope format)", raw: `{"__typename":"Product","name":"Table"}`}, + {name: "the pre-envelope negative sentinel", raw: `null`}, + {name: "truncated bytes", raw: `{"data":{"name":"Tab`}, + {name: "an array", raw: `[{"data":{"name":"Table"}}]`}, + {name: "an object without a data member", raw: `{"cc":{"ttl":60,"created":1785852117,"scope":"public"}}`}, + {name: "empty bytes", raw: ``}, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + envelope, ok := decodeEnvelope(tx, []byte(row.raw)) + assert.False(t, ok) + assert.Equal(t, storedEnvelope{}, envelope) + }) + } + }) +} + +// TestControllerEnvelopeReadRows drives the envelope through the controller: +// an undecodable entry is a plain miss that the fetch's own write replaces. +func TestControllerEnvelopeReadRows(t *testing.T) { + t.Run("an undecodable entry is a miss and is rewritten", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + cfg.ProvidesData = &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"name"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("price"), + Value: &resolve.Scalar{Nullable: true, Path: []string{"price"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + } + resolve.ComputeHasAliases(cfg.ProvidesData) + key := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), + `{"__typename":"Product","name":"Table","price":100}`) + store.data[key] = testStoreEntry{ + value: []byte(`{"data":{"__typename":"Product","name":"Tab`), + expiresAt: time.Now().Add(time.Minute), + } + store.ops = nil // the corrupted request's ops assert in isolation + + rc := NewController(store, nil).BeginRequest(nil) + item := productItem(t, "1") + decision, handle := prepare(t, rc, cfg, item) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.Items[0].FromCache) + + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)), + Arena: beginner(), + })) + rc.EndRequest() + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{key}, + Hits: []bool{true}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: key, + Value: `{"data":{"__typename":"Product","name":"Table","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + }, + }, + }, store.ops) + }) + }) +} diff --git a/v2/pkg/engine/cache/fetch_cache_configurator.go b/v2/pkg/engine/cache/fetch_cache_configurator.go new file mode 100644 index 0000000000..e9098c611c --- /dev/null +++ b/v2/pkg/engine/cache/fetch_cache_configurator.go @@ -0,0 +1,168 @@ +package cache + +import ( + "slices" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// fetchCacheConfigurator assembles the self-contained *resolve.FetchCacheConfig +// for each cache-eligible fetch (resolved configuration + built key spec + +// ProvidesData) and sets it on the concrete fetch via Fetch.SetCacheConfig — +// after createConcreteSingleFetchTypes, so the config lands on the final fetch +// types. +type fetchCacheConfigurator struct { + caching *cacheconfig.CachingConfiguration +} + +// configureTree walks one flat fetch tree and sets per-fetch cache config; a +// fetch keeps a nil Cache when its subgraph resolves to no caching, its +// coordinate has no entry, no usable key exists, or the assembled config +// enables nothing. +func (c *fetchCacheConfigurator) configureTree(response *resolve.GraphQLResponse, tree *resolve.FetchTreeNode) { + if tree == nil { + return + } + if tree.Item != nil && tree.Item.Fetch != nil { + if cfg := c.buildConfig(tree.Item.Fetch, response.CacheProvidesData()); cfg != nil { + tree.Item.Fetch.SetCacheConfig(cfg) + } + } + for _, child := range tree.ChildNodes { + c.configureTree(response, child) + } +} + +// buildConfig assembles the config for one fetch, or nil when the fetch is not +// cacheable. Info may be nil despite the engine forcing FetchInfo on — e.g. +// integrators driving postprocess directly — and then the fetch is simply not +// cached. +func (c *fetchCacheConfigurator) buildConfig(fetch resolve.Fetch, pd map[*resolve.FetchInfo]*resolve.Object) *resolve.FetchCacheConfig { + info := fetch.FetchInfo() + if info == nil || len(info.RootFields) == 0 { + return nil + } + subgraph := c.caching.Resolve(info.DataSourceID) + var cfg resolve.FetchCacheConfig + if fetch.IsEntityFetch() || fetch.IsBatchEntityFetch() { + // The key spec derives from RootFields[0].TypeName, so a fetch resolving + // entities of MIXED types (an abstract-path entity fetch collects one + // root coordinate per enclosing concrete type) has no single key space — + // decline caching entirely, the conservative mirror of the root-field + // all-or-nothing rule below. + for _, rootField := range info.RootFields[1:] { + if rootField.TypeName != info.RootFields[0].TypeName { + return nil + } + } + spec, ok := buildEntitySpec(fetch, info) + if !ok { + return nil + } + entity, ok := subgraph.Entities(entityTypeNames(info, spec.Representation)) + if !ok { + return nil + } + cfg = resolve.FetchCacheConfig{ + // L1 marks ELIGIBILITY here; optimizeL1Cache narrows it to the + // fetches whose values are actually reusable within the request. + L1: true, + L2: true, + SubgraphName: info.DataSourceName, + TTL: entity.TTL, + MaxTTL: subgraph.MaxTTL, + NegativeCacheTTL: subgraph.NegativeCacheTTL, + IncludeSubgraphHeaders: subgraph.IncludeSubgraphHeaders, + Private: entity.Scope == cacheconfig.CacheScopePrivate, + EnablePartialCacheLoad: subgraph.EnablePartialCacheLoad, + ShadowMode: subgraph.ShadowMode, + HashAnalyticsKeys: subgraph.HashAnalyticsKeys, + KeySpec: spec, + } + } else { + entry, ok := rootFieldConfigForAllRootFields(subgraph, info) + if !ok { + return nil + } + spec, ok := buildRootFieldSpec(info) + if !ok { + return nil + } + cfg = resolve.FetchCacheConfig{ + // Root fields act only as L2 providers, never L1. + L1: false, + L2: entry.TTL > 0, + SubgraphName: info.DataSourceName, + TTL: entry.TTL, + MaxTTL: subgraph.MaxTTL, + IncludeSubgraphHeaders: entry.IncludeSubgraphHeaders, + Private: entry.Scope == cacheconfig.CacheScopePrivate, + ShadowMode: entry.ShadowMode, + PartialBatchLoad: entry.PartialBatchLoad, + HashAnalyticsKeys: subgraph.HashAnalyticsKeys, + KeySpec: spec, + } + } + cfg.ProvidesData = pd[info] + if cfg.ProvidesData != nil { + resolve.ComputeHasAliases(cfg.ProvidesData) + } + if !cfg.L1 && !cfg.L2 && !cfg.ShadowMode { + // All-flags-false safety net: a config that enables nothing must not + // reach the loader (the per-fetch gate is cfg == nil). + return nil + } + return &cfg +} + +// entityTypeNames lists the entity types ONE entity fetch can resolve: its +// root-field type plus every type its merged representation conditions fields +// on. A batch fetch over an abstract type sends representations of several +// concrete types under one fetch, and each of them may carry its own static +// declaration, so all of them contribute to the fetch's resolved static tier. +func entityTypeNames(info *resolve.FetchInfo, representation *resolve.Object) []string { + names := []string{info.RootFields[0].TypeName} + if representation == nil { + return names + } + for _, field := range representation.Fields { + for _, onTypeName := range field.OnTypeNames { + if name := string(onTypeName); !slices.Contains(names, name) { + names = append(names, name) + } + } + } + return names +} + +// rootFieldConfigForAllRootFields returns an entry only when EVERY root field +// of the fetch resolves to the SAME cache settings. A merged fetch mixing +// settings (or mixing cached and uncached fields) declines caching entirely — +// the conservative safety net that the per-root-field planner isolation keeps +// rare. +func rootFieldConfigForAllRootFields(subgraph cacheconfig.EffectiveSubgraphConfig, info *resolve.FetchInfo) (cacheconfig.RootFieldCacheConfig, bool) { + first, ok := subgraph.RootField(info.RootFields[0].TypeName, info.RootFields[0].FieldName) + if !ok { + return cacheconfig.RootFieldCacheConfig{}, false + } + for _, rootField := range info.RootFields[1:] { + entry, ok := subgraph.RootField(rootField.TypeName, rootField.FieldName) + if !ok || !sameRootFieldCacheConfig(first, entry) { + return cacheconfig.RootFieldCacheConfig{}, false + } + } + return first, true +} + +// sameRootFieldCacheConfig compares the cache settings, excluding the +// coordinate: a merged fetch whose root fields all carry equal settings is +// cacheable as one unit (the value covers all its fields; coverage guards +// servability). +func sameRootFieldCacheConfig(a, b cacheconfig.RootFieldCacheConfig) bool { + return a.TTL == b.TTL && + a.IncludeSubgraphHeaders == b.IncludeSubgraphHeaders && + a.Scope == b.Scope && + a.ShadowMode == b.ShadowMode && + a.PartialBatchLoad == b.PartialBatchLoad +} diff --git a/v2/pkg/engine/cache/fetch_cache_configurator_rootfield_test.go b/v2/pkg/engine/cache/fetch_cache_configurator_rootfield_test.go new file mode 100644 index 0000000000..75426f5b3d --- /dev/null +++ b/v2/pkg/engine/cache/fetch_cache_configurator_rootfield_test.go @@ -0,0 +1,190 @@ +package cache + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +func rootFieldInfo(fields ...string) *resolve.FetchInfo { + info := &resolve.FetchInfo{DataSourceID: "products", DataSourceName: "products"} + for _, field := range fields { + info.RootFields = append(info.RootFields, resolve.GraphCoordinate{TypeName: "Query", FieldName: field}) + } + return info +} + +func rootFieldCaching(entries ...cacheconfig.RootFieldCacheConfig) *cacheconfig.CachingConfiguration { + return productCaching(cacheconfig.SubgraphCacheConfig{RootFields: entries}) +} + +func configureRootFieldFetch(t *testing.T, caching *cacheconfig.CachingConfiguration, info *resolve.FetchInfo) *resolve.SingleFetch { + t.Helper() + configurator := &fetchCacheConfigurator{caching: caching} + fetch := &resolve.SingleFetch{Info: info} + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + return fetch +} + +// TestFetchCacheConfiguratorRootFieldArm covers the plan-side root-field rows: +// full config for a single cached root field, the subgraph-level fold, and the +// conservative declines. +func TestFetchCacheConfiguratorRootFieldArm(t *testing.T) { + products := cacheconfig.RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "products", + TTL: time.Minute, + ShadowMode: true, + PartialBatchLoad: true, + IncludeSubgraphHeaders: true, + } + + t.Run("single cached root field receives the full config", func(t *testing.T) { + fetch := configureRootFieldFetch(t, rootFieldCaching(products), rootFieldInfo("products")) + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: false, + L2: true, + SubgraphName: "products", + TTL: time.Minute, + IncludeSubgraphHeaders: true, + ShadowMode: true, + PartialBatchLoad: true, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeRootField, + TypeName: "Query", + FieldName: "products", + }, + }, fetch.Cache) + }) + + t.Run("subgraph shadow mode and header inclusion reach the root field", func(t *testing.T) { + caching := productCaching(cacheconfig.SubgraphCacheConfig{ + ShadowMode: ptr(true), + IncludeSubgraphHeaders: ptr(true), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", TTL: time.Minute}, + }, + }) + fetch := configureRootFieldFetch(t, caching, rootFieldInfo("products")) + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: false, + L2: true, + SubgraphName: "products", + TTL: time.Minute, + IncludeSubgraphHeaders: true, + ShadowMode: true, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeRootField, + TypeName: "Query", + FieldName: "products", + }, + }, fetch.Cache) + }) + + t.Run("a private coordinate marks its fetch private", func(t *testing.T) { + private := cacheconfig.RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "me", + TTL: time.Minute, + Scope: cacheconfig.CacheScopePrivate, + } + fetch := configureRootFieldFetch(t, rootFieldCaching(private), rootFieldInfo("me")) + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: false, + L2: true, + SubgraphName: "products", + TTL: time.Minute, + Private: true, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeRootField, + TypeName: "Query", + FieldName: "me", + }, + }, fetch.Cache) + }) + + t.Run("a fetch merging a private and a public coordinate declines caching", func(t *testing.T) { + private := cacheconfig.RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "me", + TTL: time.Minute, + Scope: cacheconfig.CacheScopePrivate, + } + public := cacheconfig.RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "products", + TTL: time.Minute, + } + // One fetch, one key, one scope: caching a mixed pair would have to pick + // one of them, and either pick is wrong. + fetch := configureRootFieldFetch(t, rootFieldCaching(private, public), rootFieldInfo("me", "products")) + assert.Nil(t, fetch.Cache) + }) + + t.Run("the global HashAnalyticsKeys reaches the root field", func(t *testing.T) { + caching := rootFieldCaching(products) + caching.Global.HashAnalyticsKeys = true + fetch := configureRootFieldFetch(t, caching, rootFieldInfo("products")) + require.NotNil(t, fetch.Cache) + assert.True(t, fetch.Cache.HashAnalyticsKeys) + }) + + t.Run("identical settings across a merged fetch keep the config", func(t *testing.T) { + promotions := products + promotions.FieldName = "promotions" + fetch := configureRootFieldFetch(t, rootFieldCaching(products, promotions), rootFieldInfo("products", "promotions")) + require.NotNil(t, fetch.Cache) + // The key spec carries the FIRST coordinate; the cached value covers + // all of the fetch's fields and coverage guards servability. + assert.Equal(t, resolve.CacheKeySpec{ + Scope: resolve.CacheScopeRootField, + TypeName: "Query", + FieldName: "products", + }, fetch.Cache.KeySpec) + }) + + t.Run("mixed settings decline caching", func(t *testing.T) { + promotions := cacheconfig.RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "promotions", + TTL: time.Second, + } + fetch := configureRootFieldFetch(t, rootFieldCaching(products, promotions), rootFieldInfo("products", "promotions")) + assert.Nil(t, fetch.Cache) + }) + + t.Run("cached + uncached merge declines caching", func(t *testing.T) { + fetch := configureRootFieldFetch(t, rootFieldCaching(products), rootFieldInfo("products", "promotions")) + assert.Nil(t, fetch.Cache) + }) + + t.Run("an entry enabling nothing yields nil config", func(t *testing.T) { + inert := cacheconfig.RootFieldCacheConfig{TypeName: "Query", FieldName: "products"} + fetch := configureRootFieldFetch(t, rootFieldCaching(inert), rootFieldInfo("products")) + assert.Nil(t, fetch.Cache) + }) + + t.Run("the subgraph veto declines an otherwise cached coordinate", func(t *testing.T) { + caching := productCaching(cacheconfig.SubgraphCacheConfig{ + Enabled: ptr(false), + RootFields: []cacheconfig.RootFieldCacheConfig{products}, + }) + fetch := configureRootFieldFetch(t, caching, rootFieldInfo("products")) + assert.Nil(t, fetch.Cache) + }) + + t.Run("a subgraph TTL alone never caches a root field", func(t *testing.T) { + caching := productCaching(cacheconfig.SubgraphCacheConfig{DefaultTTL: ptr(time.Minute)}) + fetch := configureRootFieldFetch(t, caching, rootFieldInfo("products")) + assert.Nil(t, fetch.Cache) + }) +} diff --git a/v2/pkg/engine/cache/fetch_cache_configurator_test.go b/v2/pkg/engine/cache/fetch_cache_configurator_test.go new file mode 100644 index 0000000000..743bb2bdf3 --- /dev/null +++ b/v2/pkg/engine/cache/fetch_cache_configurator_test.go @@ -0,0 +1,285 @@ +package cache + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +func newEntityConfigurator(caching *cacheconfig.CachingConfiguration) *fetchCacheConfigurator { + return &fetchCacheConfigurator{caching: caching} +} + +func productCaching(subgraph cacheconfig.SubgraphCacheConfig) *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{"products": subgraph}, + } +} + +func ptr[T any](value T) *T { + return &value +} + +// upcRepresentation is the expected frozen representation for a Product fetch +// keyed by "upc". +func upcRepresentation() *resolve.Object { + return &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{Path: []string{"__typename"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("upc"), + Value: &resolve.String{Path: []string{"upc"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + CacheEntityKeyField: true, + }, + }, + } +} + +func TestFetchCacheConfiguratorEntityArm(t *testing.T) { + fullCaching := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{HashAnalyticsKeys: true}, + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + DefaultTTL: ptr(time.Minute), + NegativeCacheTTL: ptr(5 * time.Second), + EnablePartialCacheLoad: ptr(true), + ShadowMode: ptr(true), + IncludeSubgraphHeaders: ptr(true), + }, + }, + } + + t.Run("entity fetch receives the full config", func(t *testing.T) { + configurator := newEntityConfigurator(fullCaching) + info := productEntityInfo() + providesData := &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("productName"), + OriginalName: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"productName"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + } + fetch := entityFetchWith(productRepresentation(t, "upc")) + fetch.Info = info + response := &resolve.GraphQLResponse{} + response.SetCacheProvidesData(map[*resolve.FetchInfo]*resolve.Object{info: providesData}) + tree := &resolve.FetchTreeNode{ + Kind: resolve.FetchTreeNodeKindSequence, + ChildNodes: []*resolve.FetchTreeNode{ + {Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}}, + }, + } + configurator.configureTree(response, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: time.Minute, + NegativeCacheTTL: 5 * time.Second, + IncludeSubgraphHeaders: true, + EnablePartialCacheLoad: true, + ShadowMode: true, + HashAnalyticsKeys: true, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: upcRepresentation(), + }, + ProvidesData: &resolve.Object{ + HasAliases: true, // ComputeHasAliases folded in (OriginalName present) + Fields: []*resolve.Field{ + { + Name: []byte("productName"), + OriginalName: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"productName"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + }, + }, fetch.Cache) + // The ProvidesData is the side-table's tree itself, not a copy. + assert.Same(t, providesData, fetch.Cache.ProvidesData) + }) + + t.Run("batch entity fetch receives config through the interface", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Minute), + })) + fetch := batchEntityFetchWith(productRepresentation(t, "upc")) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: time.Minute, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: upcRepresentation(), + }, + }, fetch.Cache) + }) + + t.Run("a private subgraph marks its entity fetches private", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Minute), + Scope: ptr(cacheconfig.CacheScopePrivate), + })) + fetch := entityFetchWith(productRepresentation(t, "upc")) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: time.Minute, + Private: true, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: upcRepresentation(), + }, + }, fetch.Cache) + }) + + t.Run("the global DefaultTTL alone caches a subgraph without an entry", func(t *testing.T) { + configurator := newEntityConfigurator(&cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{DefaultTTL: 30 * time.Second}, + }) + fetch := entityFetchWith(productRepresentation(t, "upc")) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: 30 * time.Second, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: upcRepresentation(), + }, + }, fetch.Cache) + }) + + t.Run("the negative cache TTL alone caches the subgraph", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + NegativeCacheTTL: ptr(5 * time.Second), + })) + fetch := entityFetchWith(productRepresentation(t, "upc")) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + NegativeCacheTTL: 5 * time.Second, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: upcRepresentation(), + }, + }, fetch.Cache) + }) + + nilRows := []struct { + name string + fetch func(t *testing.T) resolve.Fetch + caching *cacheconfig.CachingConfiguration + }{ + { + // A single fetch takes the root-field arm, which needs a coordinate + // entry; the subgraph's entity settings do not reach it. + name: "single fetch without a root field entry", + fetch: func(*testing.T) resolve.Fetch { return &resolve.SingleFetch{Info: productEntityInfo()} }, + caching: fullCaching, + }, + { + name: "a subgraph without any resolved TTL", + fetch: func(t *testing.T) resolve.Fetch { + return entityFetchWith(productRepresentation(t, "upc")) + }, + caching: &cacheconfig.CachingConfiguration{}, + }, + { + name: "a shadow-only subgraph does not cache entities", + fetch: func(t *testing.T) resolve.Fetch { + return entityFetchWith(productRepresentation(t, "upc")) + }, + caching: productCaching(cacheconfig.SubgraphCacheConfig{ShadowMode: ptr(true)}), + }, + { + name: "the subgraph veto beats a positive TTL", + fetch: func(t *testing.T) resolve.Fetch { + return entityFetchWith(productRepresentation(t, "upc")) + }, + caching: productCaching(cacheconfig.SubgraphCacheConfig{ + Enabled: ptr(false), + DefaultTTL: ptr(time.Minute), + }), + }, + { + // No representation on the fetch means no key material at all. + name: "no usable key", + fetch: func(*testing.T) resolve.Fetch { return &resolve.EntityFetch{Info: productEntityInfo()} }, + caching: fullCaching, + }, + { + name: "nil fetch info", + fetch: func(*testing.T) resolve.Fetch { return &resolve.EntityFetch{} }, + caching: fullCaching, + }, + { + // An abstract-path entity fetch can collect one root coordinate + // per enclosing concrete type; the key spec derives from + // RootFields[0].TypeName, so mixed types decline entirely. + name: "mixed entity types decline caching", + fetch: func(t *testing.T) resolve.Fetch { + fetch := entityFetchWith(productRepresentation(t, "upc")) + fetch.Info = &resolve.FetchInfo{ + DataSourceID: "products", + DataSourceName: "products", + RootFields: []resolve.GraphCoordinate{ + {TypeName: "Product", FieldName: "name"}, + {TypeName: "User", FieldName: "username"}, + }, + } + return fetch + }, + caching: fullCaching, + }, + } + for _, row := range nilRows { + t.Run(row.name, func(t *testing.T) { + fetch := row.fetch(t) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + newEntityConfigurator(row.caching).configureTree(&resolve.GraphQLResponse{}, tree) + assert.Nil(t, fetch.CacheConfig()) + }) + } +} diff --git a/v2/pkg/engine/cache/fetch_cache_configurator_types_test.go b/v2/pkg/engine/cache/fetch_cache_configurator_types_test.go new file mode 100644 index 0000000000..7941c1371b --- /dev/null +++ b/v2/pkg/engine/cache/fetch_cache_configurator_types_test.go @@ -0,0 +1,193 @@ +package cache + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// TestFetchCacheConfiguratorTypeDeclarations pins the narrowest static tier as +// it lands on a fetch: a type's own declaration replaces the subgraph lifetime, +// a type declared uncacheable is stamped with no configuration at all, and a +// fetch batching several concrete types folds all their declarations into one. +func TestFetchCacheConfiguratorTypeDeclarations(t *testing.T) { + t.Run("the declared lifetime replaces the subgraph DefaultTTL", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Minute), + NegativeCacheTTL: ptr(5 * time.Second), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + }, + })) + fetch := entityFetchWith(productRepresentation(t, "upc")) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: 30 * time.Second, + NegativeCacheTTL: 5 * time.Second, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: upcRepresentation(), + }, + }, fetch.Cache) + }) + + t.Run("a PRIVATE declaration partitions one type of a public subgraph", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Minute), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second, Scope: cacheconfig.CacheScopePrivate}, + }, + })) + fetch := entityFetchWith(productRepresentation(t, "upc")) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: 30 * time.Second, + Private: true, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: upcRepresentation(), + }, + }, fetch.Cache) + }) + + t.Run("a type declared uncacheable is stamped with nothing, sentinel included", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Minute), + NegativeCacheTTL: ptr(5 * time.Second), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 0}, + }, + })) + fetch := entityFetchWith(productRepresentation(t, "upc")) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + assert.Nil(t, fetch.CacheConfig()) + }) + + // The abstract-path node: one conditioned key-field group per concrete type, + // built by the planner's own representation builder. Its OnTypeNames are the + // only static source of the types ONE such fetch can resolve. + abstractRepresentation := func(t *testing.T) *resolve.Object { + t.Helper() + return mergedRepresentation(t, plan.FederationMetaData{}, + plan.FederationFieldConfiguration{TypeName: "Product", SelectionSet: "upc"}, + plan.FederationFieldConfiguration{TypeName: "Brand", SelectionSet: "id"}, + ) + } + wantAbstractRepresentation := &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{Path: []string{"__typename"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + { + Name: []byte("upc"), + Value: &resolve.String{Path: []string{"upc"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + CacheEntityKeyField: true, + }, + { + Name: []byte("__typename"), + Value: &resolve.String{Path: []string{"__typename"}}, + OnTypeNames: [][]byte{[]byte("Brand")}, + }, + { + Name: []byte("id"), + Value: &resolve.String{Path: []string{"id"}}, + OnTypeNames: [][]byte{[]byte("Brand")}, + CacheEntityKeyField: true, + }, + }, + } + + t.Run("a batch over two concrete types takes the shortest declared lifetime", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Hour), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + "Brand": {MaxAge: 10 * time.Second}, + }, + })) + fetch := batchEntityFetchWith(abstractRepresentation(t)) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: 10 * time.Second, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: wantAbstractRepresentation, + }, + }, fetch.Cache) + }) + + t.Run("one private declaration turns the whole batch private", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Minute), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Brand": {MaxAge: 45 * time.Second, Scope: cacheconfig.CacheScopePrivate}, + }, + })) + fetch := batchEntityFetchWith(abstractRepresentation(t)) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + require.NotNil(t, fetch.Cache) + assert.Equal(t, &resolve.FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + // Product is undeclared and contributes the subgraph minute; Brand's + // declared 45s is shorter and wins the fold. + TTL: 45 * time.Second, + Private: true, + KeySpec: resolve.CacheKeySpec{ + Scope: resolve.CacheScopeEntity, + TypeName: "Product", + Representation: wantAbstractRepresentation, + }, + }, fetch.Cache) + }) + + t.Run("one uncacheable concrete type vetoes the whole batch", func(t *testing.T) { + configurator := newEntityConfigurator(productCaching(cacheconfig.SubgraphCacheConfig{ + DefaultTTL: ptr(time.Minute), + Types: map[string]cacheconfig.TypeCacheConfig{ + "Brand": {MaxAge: 0}, + }, + })) + fetch := batchEntityFetchWith(abstractRepresentation(t)) + tree := &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} + configurator.configureTree(&resolve.GraphQLResponse{}, tree) + + assert.Nil(t, fetch.CacheConfig()) + }) +} diff --git a/v2/pkg/engine/cache/observer.go b/v2/pkg/engine/cache/observer.go new file mode 100644 index 0000000000..bae556c064 --- /dev/null +++ b/v2/pkg/engine/cache/observer.go @@ -0,0 +1,229 @@ +package cache + +import ( + "maps" + "slices" + "sync" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// TraceObserver is the production CacheObserver: it accumulates per-fetch +// cache trace from the opaque FetchCacheHandle and attaches the assembled +// CacheTrace to the fetch's ART trace at request end. The observer is +// composed INSIDE the controller — the loader never calls it — and a nil +// observer on the controller records nothing at zero cost. OnEntity and +// OnFieldValue are deliberate no-ops. +type TraceObserver struct { + // mu guards compares and storeErrors: CompareShadow runs inside per-request + // hook transactions, and one TraceObserver instance serves MANY concurrent + // requests. + mu sync.Mutex + compares map[*resolve.FetchCacheHandle][]resolve.CacheShadowCompareTrace + storeErrors []StoreError + // uncacheablePrivate records the private results the store never received, + // one entry per occurrence. + uncacheablePrivate []UncacheablePrivate + // scopeMismatches counts the entries discarded because their recorded scope + // is not the one the reading fetch keys under, per subgraph and per STORED + // scope — the two directions of configuration drift. + scopeMismatches map[ScopeMismatch]int +} + +// UncacheablePrivate is one private result that never reached the store: the +// subgraph that produced it and the reason it stayed out. +type UncacheablePrivate struct { + Subgraph string + Reason string +} + +// ScopeMismatch identifies one direction of privacy-scope drift: entries of a +// subgraph found under StoredScope while the reading fetch keys under the other +// one. +type ScopeMismatch struct { + Subgraph string + StoredScope string +} + +// StoreError is one recorded store failure: the op that failed, the subgraph +// whose keys it carried (empty for the request-end write flush), the number of +// keys in the call, and the store's error. +type StoreError struct { + Op string + Subgraph string + KeyCount int + Err error +} + +// NewTraceObserver builds the ART trace observer. +func NewTraceObserver() *TraceObserver { + return &TraceObserver{ + compares: make(map[*resolve.FetchCacheHandle][]resolve.CacheShadowCompareTrace), + } +} + +func (o *TraceObserver) BeginRequest(*resolve.Context) {} +func (o *TraceObserver) EndRequest(*resolve.Context) {} + +// CompareShadow materializes the shadow staleness probe: cached-vs-fresh byte +// equality per stashed entry, with the entry's age (CacheTTL - RemainingTTL). +// Results are computed EAGERLY into plain values — nothing arena-owned +// survives the transaction — and drained by OnFetchObserved. +func (o *TraceObserver) CompareShadow(h *resolve.FetchCacheHandle, fresh *astjson.Value, tx *resolve.CacheTransaction) { + if h == nil || len(h.ShadowStash) == 0 { + return + } + var batch []*astjson.Value + if h.BatchEntityKey && fresh != nil { + batch = fresh.GetArray() + } + compares := make([]resolve.CacheShadowCompareTrace, 0, len(h.ShadowStash)) + for _, itemIndex := range slices.Sorted(maps.Keys(h.ShadowStash)) { + entry := h.ShadowStash[itemIndex] + freshValue := fresh + if h.BatchEntityKey { + freshValue = nil + if itemIndex >= 0 && itemIndex < len(h.Items) { + if batchIndex := h.Items[itemIndex].BatchIndex; batchIndex >= 0 && batchIndex < len(batch) { + freshValue = batch[batchIndex] + } + } + } + freshBytes := []byte("null") + if freshValue != nil { + freshBytes = freshValue.MarshalTo(nil) + } + compares = append(compares, resolve.CacheShadowCompareTrace{ + Key: traceKey(entry.CacheKey, h.HashAnalyticsKeys), + IsFresh: string(entry.CachedValue.MarshalTo(nil)) == string(freshBytes), + CacheAgeNano: int64(entry.CacheTTL - entry.RemainingTTL), + }) + } + o.mu.Lock() + defer o.mu.Unlock() + o.compares[h] = append(o.compares[h], compares...) +} + +// OnFetchObserved assembles the finished handle's CacheTrace and attaches it +// to the fetch's ART trace. It runs at EndRequest — single-threaded per +// request, no lock (beyond draining the cross-request compare map), no arena. +func (o *TraceObserver) OnFetchObserved(h *resolve.FetchCacheHandle) { + if h == nil { + return + } + o.mu.Lock() + compares := o.compares[h] + delete(o.compares, h) + o.mu.Unlock() + if h.Trace == nil { + // Tracing disabled: the drain above still prevents cross-request + // accumulation; nothing is emitted. + return + } + trace := &resolve.CacheTrace{ + Decision: h.Decision.String(), + Hit: h.WasHit, + Shadow: h.Shadow, + ShadowCompares: compares, + } + for i := range h.Items { + item := &h.Items[i] + trace.Items = append(trace.Items, resolve.CacheItemTrace{ + Key: traceKey(itemTraceKey(item), h.HashAnalyticsKeys), + ServedFrom: item.ServedFromLayer, + Hit: item.FromCache != nil, + NegativeHit: item.NegativeHit, + RemainingTTLNano: int64(item.RemainingTTL), + }) + } + h.Trace.CacheTrace = trace +} + +// OnStoreError records one failed store round trip. Failures are degradations, +// never request errors: the reads they lost are served from the origin and the +// writes they lost are dropped. +func (o *TraceObserver) OnStoreError(op string, subgraph string, keyCount int, err error) { + o.mu.Lock() + defer o.mu.Unlock() + o.storeErrors = append(o.storeErrors, StoreError{ + Op: op, + Subgraph: subgraph, + KeyCount: keyCount, + Err: err, + }) +} + +// OnUncacheablePrivate records one private result whose store entry is +// silently never written — exactly the kind of invisible cache miss an operator +// needs surfaced, with the reason naming the knob that would fix it. +func (o *TraceObserver) OnUncacheablePrivate(subgraph string, reason string) { + o.mu.Lock() + defer o.mu.Unlock() + o.uncacheablePrivate = append(o.uncacheablePrivate, UncacheablePrivate{ + Subgraph: subgraph, + Reason: reason, + }) +} + +// UncacheablePrivate returns the recorded private results the store never +// received, in occurrence order. +func (o *TraceObserver) UncacheablePrivate() []UncacheablePrivate { + o.mu.Lock() + defer o.mu.Unlock() + return slices.Clone(o.uncacheablePrivate) +} + +// OnScopeMismatch counts one entry discarded for carrying the other privacy +// scope. A steady count means two deployments disagree about a subgraph's +// scope; every such entry is refetched from the origin, never served. +func (o *TraceObserver) OnScopeMismatch(subgraph string, storedScope string) { + o.mu.Lock() + defer o.mu.Unlock() + if o.scopeMismatches == nil { + o.scopeMismatches = make(map[ScopeMismatch]int) + } + o.scopeMismatches[ScopeMismatch{Subgraph: subgraph, StoredScope: storedScope}]++ +} + +// ScopeMismatches returns the discarded-entry counts per subgraph and stored +// scope. +func (o *TraceObserver) ScopeMismatches() map[ScopeMismatch]int { + o.mu.Lock() + defer o.mu.Unlock() + return maps.Clone(o.scopeMismatches) +} + +// StoreErrors returns the recorded store failures in occurrence order. +func (o *TraceObserver) StoreErrors() []StoreError { + o.mu.Lock() + defer o.mu.Unlock() + return slices.Clone(o.storeErrors) +} + +func (o *TraceObserver) OnEntity(*resolve.FetchCacheHandle, *astjson.Value) {} +func (o *TraceObserver) OnFieldValue(resolve.GraphCoordinate, resolve.FieldValue) {} + +// itemTraceKey identifies the item's cache entry in trace output: its L2 key, +// or — for an L1-only fetch, which derives no store key — the hash of its raw +// preimage, so the entity's @key VALUES never reach a trace. An item whose key +// did not render has neither and traces without a key. +func itemTraceKey(item *resolve.ItemCacheState) string { + if item.RenderedKey != "" { + return item.RenderedKey + } + if item.L1Key == "" { + return "" + } + return hashHex([]byte(item.L1Key)) +} + +// traceKey returns the key as-is, or its 16-hex xxhash64 when the policy asks +// for hashed key material in analytics/trace output. +func traceKey(key string, hash bool) string { + if !hash || key == "" { + return key + } + return hashHex([]byte(key)) +} diff --git a/v2/pkg/engine/cache/observer_test.go b/v2/pkg/engine/cache/observer_test.go new file mode 100644 index 0000000000..1a1a91990f --- /dev/null +++ b/v2/pkg/engine/cache/observer_test.go @@ -0,0 +1,322 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// noopObserver is the do-nothing resolve.CacheObserver the package's observer +// doubles embed (cachetesting cannot be imported here), so a double spells out +// only the hooks it actually records. +type noopObserver struct{} + +func (noopObserver) BeginRequest(*resolve.Context) {} +func (noopObserver) EndRequest(*resolve.Context) {} +func (noopObserver) OnFetchObserved(*resolve.FetchCacheHandle) {} +func (noopObserver) CompareShadow(*resolve.FetchCacheHandle, *astjson.Value, *resolve.CacheTransaction) { +} +func (noopObserver) OnStoreError(string, string, int, error) {} +func (noopObserver) OnUncacheablePrivate(string, string) {} +func (noopObserver) OnScopeMismatch(string, string) {} +func (noopObserver) OnEntity(*resolve.FetchCacheHandle, *astjson.Value) {} +func (noopObserver) OnFieldValue(resolve.GraphCoordinate, resolve.FieldValue) {} + +// tracedInput wires a fetch with an ART trace destination into the prepare +// input, exactly as the loader does when tracing is enabled. +func tracedInput(cfg *resolve.FetchCacheConfig, items ...*astjson.Value) (resolve.PrepareFetchInput, *resolve.DataSourceLoadTrace) { + trace := &resolve.DataSourceLoadTrace{} + in := prepareInput(cfg, items...) + in.Item = &resolve.FetchItem{Fetch: &resolve.EntityFetch{Trace: trace}} + return in, trace +} + +// TestTraceObserverRows pins the COMPLETE assembled CacheTrace per scenario. +func TestTraceObserverRows(t *testing.T) { + fresh := `{"__typename":"Product","name":"Table","price":100}` + + t.Run("miss + fetch: decision and the item's key", func(t *testing.T) { + obs := NewTraceObserver() + rc := NewController(newTestStore(), obs).BeginRequest(nil) + cfg := entityConfig(t, time.Minute) + item := productItem(t, "1") + in, trace := tracedInput(cfg, item) + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(fresh)), + Arena: beginner(), + })) + rc.EndRequest() + assert.Equal(t, &resolve.CacheTrace{ + Decision: "Fetch", + Hit: false, + Items: []resolve.CacheItemTrace{ + { + Key: handle.Items[0].RenderedKey, + Hit: false, + }, + }, + }, trace.CacheTrace) + }) + + t.Run("L2 hit: served_from l2 with the EXACT remaining TTL", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) + key := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), fresh) + + time.Sleep(20 * time.Second) // age inside the bubble + + obs := NewTraceObserver() + rc := NewController(store, obs).BeginRequest(nil) + item := productItem(t, "1") + in, trace := tracedInput(cfg, item) + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + Arena: beginner(), + })) + rc.EndRequest() + assert.Equal(t, &resolve.CacheTrace{ + Decision: "SkipFullHit", + Hit: true, + Items: []resolve.CacheItemTrace{ + { + Key: key, + ServedFrom: "l2", + Hit: true, + RemainingTTLNano: int64(40 * time.Second), + }, + }, + }, trace.CacheTrace) + }) + }) + + t.Run("L1 hit: served_from l1, no TTL", func(t *testing.T) { + obs := NewTraceObserver() + rc := NewController(newTestStore(), obs).BeginRequest(nil) + cfg := entityConfig(t, time.Minute) + l1Fetch(t, rc, cfg, productItem(t, "1"), astjson.MustParseBytes([]byte(fresh))) + + item := productItem(t, "1") + in, trace := tracedInput(cfg, item) + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + Arena: beginner(), + })) + rc.EndRequest() + assert.Equal(t, &resolve.CacheTrace{ + Decision: "SkipFullHit", + Hit: true, + Items: []resolve.CacheItemTrace{ + { + Key: handle.Items[0].RenderedKey, + ServedFrom: "l1", + Hit: true, + }, + }, + }, trace.CacheTrace) + }) + + t.Run("L1-only fetch: the item traces under the HASH of its preimage", func(t *testing.T) { + obs := NewTraceObserver() + rc := NewController(newTestStore(), obs).BeginRequest(nil) + cfg := entityConfig(t, 0) // TTL 0: L1 true, L2 false + l1Fetch(t, rc, cfg, productItem(t, "1"), astjson.MustParseBytes([]byte(fresh))) + + item := productItem(t, "1") + in, trace := tracedInput(cfg, item) + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + rc.EndRequest() + // No store key exists to trace, and the raw preimage carries the + // entity's @key values — so the trace identifies the entry by the + // preimage's hash. + assert.Equal(t, `products:{"__typename":"Product","representation":{"upc":"1"}}`, handle.Items[0].L1Key) + assert.Equal(t, &resolve.CacheTrace{ + Decision: "SkipFullHit", + Hit: true, + Items: []resolve.CacheItemTrace{ + { + Key: hashHex([]byte(`products:{"__typename":"Product","representation":{"upc":"1"}}`)), + ServedFrom: "l1", + Hit: true, + }, + }, + }, trace.CacheTrace) + }) + + t.Run("negative hit is marked", func(t *testing.T) { + store := newTestStore() + cfg := negativeConfig(t, 5*time.Second) + key := writeNegativeThrough(t, store, cfg, "404") + + obs := NewTraceObserver() + rc := NewController(store, obs).BeginRequest(nil) + item := productItem(t, "404") + in, trace := tracedInput(cfg, item) + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc.OnFetchSkipped(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + Arena: beginner(), + })) + rc.EndRequest() + require.NotNil(t, trace.CacheTrace) + require.Len(t, trace.CacheTrace.Items, 1) + assert.True(t, trace.CacheTrace.Items[0].NegativeHit) + assert.True(t, trace.CacheTrace.Items[0].Hit) + assert.Equal(t, key, trace.CacheTrace.Items[0].Key) + _ = handle + }) + + t.Run("shadow: compares recorded with the EXACT cache age", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := shadowConfig(t) + key := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), fresh) + + time.Sleep(15 * time.Second) + + obs := NewTraceObserver() + rc := NewController(store, obs).BeginRequest(nil) + item := productItem(t, "1") + in, trace := tracedInput(cfg, item) + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionFetchShadow, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(fresh)), + Arena: beginner(), + })) + rc.EndRequest() + require.NotNil(t, trace.CacheTrace) + assert.Equal(t, "FetchShadow", trace.CacheTrace.Decision) + assert.True(t, trace.CacheTrace.Shadow) + assert.Equal(t, []resolve.CacheShadowCompareTrace{ + {Key: key, IsFresh: true, CacheAgeNano: int64(15 * time.Second)}, + }, trace.CacheTrace.ShadowCompares) + }) + }) + + t.Run("HashAnalyticsKeys hashes key material in trace output", func(t *testing.T) { + obs := NewTraceObserver() + rc := NewController(newTestStore(), obs).BeginRequest(nil) + cfg := entityConfig(t, time.Minute) + cfg.HashAnalyticsKeys = true + item := productItem(t, "1") + in, trace := tracedInput(cfg, item) + _, handle := rc.PrepareFetch(in) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(fresh)), + Arena: beginner(), + })) + rc.EndRequest() + require.NotNil(t, trace.CacheTrace) + require.Len(t, trace.CacheTrace.Items, 1) + hashed := trace.CacheTrace.Items[0].Key + raw := handle.Items[0].RenderedKey + assert.NotEqual(t, raw, hashed) + assert.Equal(t, hashHex([]byte(raw)), hashed) + assert.Len(t, hashed, 16) + }) + + t.Run("tracing off: nothing attached, compares drained", func(t *testing.T) { + obs := NewTraceObserver() + rc := NewController(newTestStore(), obs).BeginRequest(nil) + cfg := entityConfig(t, time.Minute) + item := productItem(t, "1") + // No Item on the input: the loader with tracing disabled leaves + // handle.Trace nil. + decision, handle := prepare(t, rc, cfg, item) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(fresh)), + Arena: beginner(), + })) + rc.EndRequest() + assert.Nil(t, handle.Trace) + assert.Empty(t, obs.compares) + }) +} + +// writeNegativeThrough primes the negative sentinel for one item and returns +// its key. +func writeNegativeThrough(t *testing.T, store *testStore, cfg *resolve.FetchCacheConfig, upc string) string { + t.Helper() + rc := NewController(store, nil).BeginRequest(nil) + item := productItem(t, upc) + _, handle := prepare(t, rc, cfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`null`)), + EmptyEntity: true, + Arena: beginner(), + })) + rc.EndRequest() + return handle.Items[0].RenderedKey +} + +// countingObserver counts OnFetchObserved calls around the real TraceObserver. +type countingObserver struct { + *TraceObserver + + observed int +} + +func (c *countingObserver) OnFetchObserved(h *resolve.FetchCacheHandle) { + c.observed++ + c.TraceObserver.OnFetchObserved(h) +} + +// TestFlushTracesBeforeEndRequest: the resolver flushes cache traces BEFORE +// the response renders (extensions.trace serializes during Resolve, EndRequest +// runs after the response is written). The trace must be attached by +// FlushTraces, and the handle observed exactly ONCE — EndRequest skips +// already-flushed handles. +func TestFlushTracesBeforeEndRequest(t *testing.T) { + obs := &countingObserver{TraceObserver: NewTraceObserver()} + rc := NewController(newTestStore(), obs).BeginRequest(nil) + cfg := entityConfig(t, time.Minute) + item := productItem(t, "1") + in, trace := tracedInput(cfg, item) + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionFetch, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","name":"Table","price":100}`)), + Arena: beginner(), + })) + + flusher, ok := rc.(resolve.CacheTraceFlusher) + require.True(t, ok, "requestCache must implement CacheTraceFlusher") + flusher.FlushTraces() + assert.Equal(t, &resolve.CacheTrace{ + Decision: "Fetch", + Hit: false, + Items: []resolve.CacheItemTrace{ + { + Key: handle.Items[0].RenderedKey, + Hit: false, + }, + }, + }, trace.CacheTrace) + assert.Equal(t, 1, obs.observed) + + rc.EndRequest() + assert.Equal(t, 1, obs.observed) +} diff --git a/v2/pkg/engine/cache/optimize_l1_cache.go b/v2/pkg/engine/cache/optimize_l1_cache.go new file mode 100644 index 0000000000..9ec145f343 --- /dev/null +++ b/v2/pkg/engine/cache/optimize_l1_cache.go @@ -0,0 +1,442 @@ +package cache + +import ( + "cmp" + "slices" + "strings" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// optimizeL1Cache narrows cfg.L1 CROSS-TREE after all fetch configs are set: +// L1 stays enabled only where a request-lifetime provider/consumer pair exists +// — a fetch whose value no later fetch can reuse (canWrite) and that no prior +// fetch can serve (canRead) drops its eligibility. The configurator is the +// SOLE eligibility setter; this pass NEVER turns L1 on. Wrong narrowing costs +// only a missed hit, never correctness. +type optimizeL1Cache struct { + // treeParents is the per-run tree ancestry (index of the enclosing tree, + // -1 for roots); see optimize. + treeParents []int +} + +// entityFetchInfo is the narrowing view of one L1-relevant entity fetch. +type entityFetchInfo struct { + fetchID int + coordinate string + entityType string + // treeIndex is the fetch's tree position in the facade's execution-ordered + // tree list: 0 is the initial response tree, 1+ are defer groups. + treeIndex int + providesData *resolve.Object + dependsOn []int + fetch resolve.Fetch +} + +// optimize runs the cross-tree narrowing over ALL fetch trees of one response +// (the root tree and every defer group — the L1 store is request-lifetime, so +// provider/consumer pairs span trees). +func (o *optimizeL1Cache) optimize(trees []*resolve.FetchTreeNode, treeParents []int) { + // treeParents encodes the defer-group ancestry (parent tree index per + // tree, -1 for roots); nil defaults to "tree 0 encloses every other + // tree" — the plain root-before-defers rule. + o.treeParents = treeParents + if len(o.treeParents) != len(trees) { + o.treeParents = make([]int, len(trees)) + for i := range o.treeParents { + o.treeParents[i] = 0 + } + if len(o.treeParents) > 0 { + o.treeParents[0] = -1 + } + } + var entities []*entityFetchInfo + // dependencies indexes EVERY fetch in the trees (cached or not): a + // provider/consumer chain routinely passes THROUGH unconfigured fetches + // (products -> reviews -> products), and a chain walk restricted to cached + // entity fetches would break at the middle hop. + dependencies := make(map[int][]int) + for treeIndex, tree := range trees { + collectFetchDependencies(tree, dependencies) + collected := o.collectEntityFetches(tree) + for _, entity := range collected { + entity.treeIndex = treeIndex + } + entities = append(entities, collected...) + } + if len(entities) == 0 { + return + } + + slices.SortFunc(entities, func(a, b *entityFetchInfo) int { + return cmp.Or( + cmp.Compare(a.fetchID, b.fetchID), + cmp.Compare(a.coordinate, b.coordinate), + ) + }) + + eligible := make([]*entityFetchInfo, 0, len(entities)) + for _, entity := range entities { + if cfg := entity.fetch.CacheConfig(); cfg != nil && cfg.L1 { + eligible = append(eligible, entity) + } + } + + for _, entity := range eligible { + if o.hasValidProvider(entity, eligible, dependencies) || o.hasValidConsumer(entity, eligible, dependencies) { + continue + } + cfg := entity.fetch.CacheConfig() + cfg.L1 = false + if !cfg.L2 && !cfg.ShadowMode { + // The config enables nothing anymore: re-nil it so the loader's + // per-fetch gate skips the fetch entirely (tidy, not correctness). + entity.fetch.SetCacheConfig(nil) + } + } +} + +func (o *optimizeL1Cache) collectEntityFetches(node *resolve.FetchTreeNode) []*entityFetchInfo { + if node == nil { + return nil + } + switch node.Kind { + case resolve.FetchTreeNodeKindSingle: + if node.Item == nil { + return nil + } + if entity := o.extractEntityFetchInfo(node.Item.Fetch); entity != nil { + return []*entityFetchInfo{entity} + } + case resolve.FetchTreeNodeKindParallel, resolve.FetchTreeNodeKindSequence: + var result []*entityFetchInfo + for _, child := range node.ChildNodes { + result = append(result, o.collectEntityFetches(child)...) + } + return result + } + return nil +} + +func (o *optimizeL1Cache) extractEntityFetchInfo(fetch resolve.Fetch) *entityFetchInfo { + if fetch == nil || fetch.CacheConfig() == nil { + return nil + } + if !fetch.IsEntityFetch() && !fetch.IsBatchEntityFetch() { + return nil + } + info := fetch.FetchInfo() + if info == nil || len(info.RootFields) == 0 || info.RootFields[0].TypeName == "" { + return nil + } + deps := fetch.Dependencies() + if deps == nil { + return nil + } + return &entityFetchInfo{ + fetchID: deps.FetchID, + coordinate: info.RootFields[0].TypeName + "." + info.RootFields[0].FieldName, + entityType: info.RootFields[0].TypeName, + providesData: fetch.CacheConfig().ProvidesData, + dependsOn: deps.DependsOnFetchIDs, + fetch: fetch, + } +} + +// hasValidProvider reports canRead: a prior fetch of the same entity type (or +// the union of all priors) provides a SUPERSET of this fetch's tree. +func (o *optimizeL1Cache) hasValidProvider(consumer *entityFetchInfo, candidates []*entityFetchInfo, dependencies map[int][]int) bool { + for _, provider := range candidates { + if provider.fetchID == consumer.fetchID { + continue + } + if provider.entityType != consumer.entityType { + continue + } + if !o.executesBefore(provider, consumer, dependencies) { + continue + } + if objectProvidesAllFields(provider.providesData, consumer.providesData) { + return true + } + } + union := o.collectAncestorUnion(consumer, candidates, dependencies) + return union != nil && objectProvidesAllFields(union, consumer.providesData) +} + +// hasValidConsumer reports canWrite: a later fetch of the same entity type +// needs a SUBSET of this fetch's tree, either from this fetch alone or from a +// union THIS FETCH CONTRIBUTES TO. The contribution gate is the fix for the +// OLD union-fallback flaw: without it, a provider sharing a consumer with +// other, sufficient providers stayed L1-eligible although nothing ever reused +// its cached data. +func (o *optimizeL1Cache) hasValidConsumer(provider *entityFetchInfo, candidates []*entityFetchInfo, dependencies map[int][]int) bool { + for _, consumer := range candidates { + if consumer.fetchID == provider.fetchID { + continue + } + if consumer.entityType != provider.entityType { + continue + } + if !o.executesBefore(provider, consumer, dependencies) { + continue + } + if objectProvidesAllFields(provider.providesData, consumer.providesData) { + return true + } + if !objectSharesAnyField(provider.providesData, consumer.providesData) { + continue + } + union := o.collectAncestorUnion(consumer, candidates, dependencies) + if union != nil && objectProvidesAllFields(union, consumer.providesData) { + return true + } + } + return false +} + +// executesBefore resolves ordering from two sources: the dependency edges +// (direct or transitive), and TREE order — the initial response tree always +// completes before any defer group starts, so an initial-tree fetch executes +// before every defer-group fetch even across branches with no dependency +// edge. Defer groups among themselves stay unordered (conservative: they may +// run in parallel). +func (o *optimizeL1Cache) executesBefore(a, b *entityFetchInfo, dependencies map[int][]int) bool { + if o.treeEncloses(a.treeIndex, b.treeIndex) { + return true + } + visited := make(map[int]bool) + return o.isInDependencyChain(b.dependsOn, a.fetchID, dependencies, visited) +} + +// treeEncloses reports whether tree a is a strict ancestor of tree b: the +// resolver resolves a parent defer group fully before its children (and the +// initial tree before every group), so ancestor-tree fetches execute before +// every descendant-tree fetch. SIBLING groups stay unordered (parallel). +// The walk is bounded by the tree count: treeParents crosses the public +// ConfigureCaching API, and a malformed parent cycle must terminate, never +// hang. Within such a cycle direct parent edges may still report enclosure — +// harmless: L1 is only an eligibility hint, and the runtime still gates every +// serve on key and coverage matches against actually-cached values. +func (o *optimizeL1Cache) treeEncloses(a, b int) bool { + if a == b { + return false + } + cur := b + for range o.treeParents { + if cur < 0 || cur >= len(o.treeParents) { + return false + } + parent := o.treeParents[cur] + if parent == a { + return true + } + if parent == cur { + return false + } + cur = parent + } + return false +} + +func (o *optimizeL1Cache) isInDependencyChain(dependsOn []int, targetID int, dependencies map[int][]int, visited map[int]bool) bool { + for _, depID := range dependsOn { + if depID == targetID { + return true + } + if visited[depID] { + continue + } + visited[depID] = true + if o.isInDependencyChain(dependencies[depID], targetID, dependencies, visited) { + return true + } + } + return false +} + +// collectFetchDependencies records fetchID -> DependsOnFetchIDs for every +// fetch under node. +func collectFetchDependencies(node *resolve.FetchTreeNode, out map[int][]int) { + if node == nil { + return + } + if node.Item != nil && node.Item.Fetch != nil { + if deps := node.Item.Fetch.Dependencies(); deps != nil { + out[deps.FetchID] = deps.DependsOnFetchIDs + } + } + for _, child := range node.ChildNodes { + collectFetchDependencies(child, out) + } +} + +// collectAncestorUnion unions the trees of every same-type provider executing +// before the consumer. +func (o *optimizeL1Cache) collectAncestorUnion(consumer *entityFetchInfo, candidates []*entityFetchInfo, dependencies map[int][]int) *resolve.Object { + var union *resolve.Object + for _, provider := range candidates { + if provider.fetchID == consumer.fetchID { + continue + } + if provider.entityType != consumer.entityType { + continue + } + if !o.executesBefore(provider, consumer, dependencies) { + continue + } + if provider.providesData != nil { + union = unionObjects(union, provider.providesData) + } + } + return union +} + +// fieldNarrowingName identifies a field for provider/consumer matching: the +// SCHEMA name (alias-independent — the L1 store holds normalized values) plus +// the argument bindings (fields selected with different arguments are +// different cache fields). CacheArgs are sorted at capture time, so +// plain concatenation is deterministic. +func fieldNarrowingName(field *resolve.Field) string { + name := string(field.Name) + if len(field.OriginalName) > 0 { + name = string(field.OriginalName) + } + if len(field.CacheArgs) == 0 { + return name + } + var b strings.Builder + b.WriteString(name) + b.WriteByte('(') + for i, arg := range field.CacheArgs { + if i > 0 { + b.WriteByte(',') + } + b.WriteString(arg.Name) + b.WriteByte(':') + b.WriteString(arg.VariableName) + } + b.WriteByte(')') + return b.String() +} + +func findFieldByNarrowingName(fields []*resolve.Field, name string) *resolve.Field { + for _, field := range fields { + if fieldNarrowingName(field) == name { + return field + } + } + return nil +} + +// objectProvidesAllFields reports whether the provider tree contains EVERY +// field of the consumer tree, recursively. +func objectProvidesAllFields(provider, consumer *resolve.Object) bool { + if consumer == nil { + return true + } + if provider == nil { + return len(consumer.Fields) == 0 + } + for _, consumerField := range consumer.Fields { + providerField := findFieldByNarrowingName(provider.Fields, fieldNarrowingName(consumerField)) + if providerField == nil { + return false + } + if !nodeProvidesAllFields(providerField.Value, consumerField.Value) { + return false + } + } + return true +} + +// objectSharesAnyField reports whether the provider supplies at least one +// field PATH the consumer needs — the union-fallback contribution gate. The +// walk is recursive: sharing only a nested object's NAME while providing none +// of its leaves the consumer reads is not a contribution. +func objectSharesAnyField(provider, consumer *resolve.Object) bool { + if provider == nil || consumer == nil { + return false + } + for _, consumerField := range consumer.Fields { + providerField := findFieldByNarrowingName(provider.Fields, fieldNarrowingName(consumerField)) + if providerField != nil && nodeSharesAnyField(providerField.Value, consumerField.Value) { + return true + } + } + return false +} + +func nodeSharesAnyField(provider, consumer resolve.Node) bool { + if provider == nil || consumer == nil { + return false + } + switch consumerNode := consumer.(type) { + case *resolve.Object: + providerObj, ok := provider.(*resolve.Object) + return ok && objectSharesAnyField(providerObj, consumerNode) + case *resolve.Array: + providerArr, ok := provider.(*resolve.Array) + return ok && nodeSharesAnyField(providerArr.Item, consumerNode.Item) + default: + return true + } +} + +func nodeProvidesAllFields(provider, consumer resolve.Node) bool { + if consumer == nil { + return true + } + if provider == nil { + return false + } + switch consumerNode := consumer.(type) { + case *resolve.Object: + providerObj, ok := provider.(*resolve.Object) + if !ok { + return false + } + return objectProvidesAllFields(providerObj, consumerNode) + case *resolve.Array: + providerArr, ok := provider.(*resolve.Array) + if !ok { + return false + } + return nodeProvidesAllFields(providerArr.Item, consumerNode.Item) + default: + return true + } +} + +// unionObjects merges two trees into a NEW object. Overlapping object fields +// merge recursively into COPIED field structs — the inputs are live +// ProvidesData trees on the fetch configs, and mutating them here would +// corrupt the configs. +func unionObjects(a, b *resolve.Object) *resolve.Object { + if a == nil { + return b + } + if b == nil { + return a + } + merged := make([]*resolve.Field, 0, len(a.Fields)+len(b.Fields)) + merged = append(merged, a.Fields...) + for _, bField := range b.Fields { + name := fieldNarrowingName(bField) + existingIdx := slices.IndexFunc(merged, func(f *resolve.Field) bool { + return fieldNarrowingName(f) == name + }) + if existingIdx < 0 { + merged = append(merged, bField) + continue + } + existingObj, existingIsObj := merged[existingIdx].Value.(*resolve.Object) + bObj, bIsObj := bField.Value.(*resolve.Object) + if existingIsObj && bIsObj { + fieldCopy := *merged[existingIdx] + fieldCopy.Value = unionObjects(existingObj, bObj) + merged[existingIdx] = &fieldCopy + } + } + return &resolve.Object{Fields: merged} +} diff --git a/v2/pkg/engine/cache/optimize_l1_cache_test.go b/v2/pkg/engine/cache/optimize_l1_cache_test.go new file mode 100644 index 0000000000..192915827b --- /dev/null +++ b/v2/pkg/engine/cache/optimize_l1_cache_test.go @@ -0,0 +1,234 @@ +package cache + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// narrowingTree builds an entity tree with the given scalar fields (nested +// object fields expressed as "parent.child"). +func narrowingTree(fieldNames ...string) *resolve.Object { + obj := &resolve.Object{} + for _, name := range fieldNames { + obj.Fields = append(obj.Fields, &resolve.Field{ + Name: []byte(name), + Value: &resolve.Scalar{Path: []string{name}}, + }) + } + return obj +} + +// narrowingFetch builds one entity fetch node for the pass. +func narrowingFetch(fetchID int, dependsOn []int, typeName string, provides *resolve.Object, l1, l2 bool) *resolve.FetchTreeNode { + fetch := &resolve.EntityFetch{ + FetchDependencies: resolve.FetchDependencies{FetchID: fetchID, DependsOnFetchIDs: dependsOn}, + Info: &resolve.FetchInfo{RootFields: []resolve.GraphCoordinate{{TypeName: typeName}}}, + Cache: &resolve.FetchCacheConfig{ + L1: l1, + L2: l2, + SubgraphName: "products", + ProvidesData: provides, + }, + } + return &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSingle, Item: &resolve.FetchItem{Fetch: fetch}} +} + +func tree(nodes ...*resolve.FetchTreeNode) *resolve.FetchTreeNode { + return &resolve.FetchTreeNode{Kind: resolve.FetchTreeNodeKindSequence, ChildNodes: nodes} +} + +func l1Of(node *resolve.FetchTreeNode) bool { + cfg := node.Item.Fetch.CacheConfig() + return cfg != nil && cfg.L1 +} + +// TestOptimizeL1CacheRows covers the narrowing rows, including the adversarial +// ones the OLD test set lacked. +func TestOptimizeL1CacheRows(t *testing.T) { + pass := &optimizeL1Cache{} + + t.Run("provider/consumer pair via a dependency edge keeps both", func(t *testing.T) { + provider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), true, true) + consumer := narrowingFetch(2, []int{1}, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(provider, consumer)}, nil) + assert.True(t, l1Of(provider)) + assert.True(t, l1Of(consumer)) + }) + + t.Run("a lone fetch is narrowed off", func(t *testing.T) { + lone := narrowingFetch(1, nil, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(lone)}, nil) + assert.False(t, l1Of(lone)) + }) + + t.Run("narrowing a lone L1-only fetch re-nils the inert config", func(t *testing.T) { + lone := narrowingFetch(1, nil, "Product", narrowingTree("name"), true, false) + pass.optimize([]*resolve.FetchTreeNode{tree(lone)}, nil) + assert.Nil(t, lone.Item.Fetch.CacheConfig()) + }) + + t.Run("never turns L1 on: a configurator-false fetch stays false despite a pair", func(t *testing.T) { + provider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), false, true) + consumer := narrowingFetch(2, []int{1}, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(provider, consumer)}, nil) + assert.False(t, l1Of(provider)) + // The consumer's only candidate provider is ineligible: no pair, off. + assert.False(t, l1Of(consumer)) + }) + + t.Run("union of two partial providers covers the consumer: all three keep L1", func(t *testing.T) { + providerA := narrowingFetch(1, nil, "Product", narrowingTree("name"), true, true) + providerB := narrowingFetch(2, nil, "Product", narrowingTree("price"), true, true) + consumer := narrowingFetch(3, []int{1, 2}, "Product", narrowingTree("name", "price"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(providerA, providerB, consumer)}, nil) + assert.True(t, l1Of(providerA)) + assert.True(t, l1Of(providerB)) + assert.True(t, l1Of(consumer)) + }) + + t.Run("[flaw pin] an irrelevant provider sharing a consumer is narrowed off", func(t *testing.T) { + relevant := narrowingFetch(1, nil, "Product", narrowingTree("name"), true, true) + irrelevant := narrowingFetch(2, nil, "Product", narrowingTree("weight"), true, true) + consumer := narrowingFetch(3, []int{1, 2}, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(relevant, irrelevant, consumer)}, nil) + assert.True(t, l1Of(relevant)) + // Shares NO field with the consumer: the union fallback must not keep + // it merely because the OTHER provider covers the consumer. + assert.False(t, l1Of(irrelevant)) + assert.True(t, l1Of(consumer)) + }) + + t.Run("[flaw pin] nested NAME-only overlap is not a contribution", func(t *testing.T) { + // The irrelevant provider shares the OBJECT NAME "warehouse" but none + // of the leaves the consumer reads; the relevant provider covers the + // consumer alone. The contribution gate must recurse past the name. + warehouseWith := func(leaf string) *resolve.Object { + return &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("warehouse"), Value: &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte(leaf), Value: &resolve.Scalar{Path: []string{leaf}}}, + }}}, + }} + } + relevant := narrowingFetch(1, nil, "Product", warehouseWith("location"), true, true) + irrelevant := narrowingFetch(2, nil, "Product", warehouseWith("id"), true, true) + consumer := narrowingFetch(3, []int{1, 2}, "Product", warehouseWith("location"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(relevant, irrelevant, consumer)}, nil) + assert.True(t, l1Of(relevant)) + assert.False(t, l1Of(irrelevant)) + assert.True(t, l1Of(consumer)) + }) + + t.Run("partial overlap without full coverage narrows both off", func(t *testing.T) { + provider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), true, true) + consumer := narrowingFetch(2, []int{1}, "Product", narrowingTree("price", "weight"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(provider, consumer)}, nil) + assert.False(t, l1Of(provider)) + assert.False(t, l1Of(consumer)) + }) + + t.Run("empty union: a consumer with no prior providers is narrowed off", func(t *testing.T) { + later := narrowingFetch(2, nil, "Product", narrowingTree("name"), true, true) + unrelated := narrowingFetch(1, nil, "User", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(unrelated, later)}, nil) + assert.False(t, l1Of(later)) + assert.False(t, l1Of(unrelated)) + }) + + t.Run("transitive dependency chains order fetches", func(t *testing.T) { + provider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), true, true) + bridge := narrowingFetch(2, []int{1}, "User", narrowingTree("id"), true, true) + consumer := narrowingFetch(3, []int{2}, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(provider, bridge, consumer)}, nil) + assert.True(t, l1Of(provider)) + assert.True(t, l1Of(consumer)) + assert.False(t, l1Of(bridge)) + }) + + t.Run("cross-tree: a root provider is kept because its only consumer is deferred", func(t *testing.T) { + // NO dependency edge between the two — different branches; only tree + // order relates them. + provider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), true, true) + consumer := narrowingFetch(7, []int{5}, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(provider), tree(consumer)}, nil) + assert.True(t, l1Of(provider)) + assert.True(t, l1Of(consumer)) + + // Per-tree-only behavior is rejected: the SAME shapes narrowed off when + // the pass only sees the root tree. + soloProvider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(soloProvider)}, nil) + assert.False(t, l1Of(soloProvider)) + }) + + t.Run("a parent defer group orders before its NESTED child group", func(t *testing.T) { + provider := narrowingFetch(3, nil, "Product", narrowingTree("name", "price"), true, true) + consumer := narrowingFetch(4, nil, "Product", narrowingTree("name"), true, true) + // treeParents: tree 1 (outer group) encloses tree 2 (nested group). + pass.optimize([]*resolve.FetchTreeNode{tree(), tree(provider), tree(consumer)}, []int{-1, 0, 1}) + assert.True(t, l1Of(provider)) + assert.True(t, l1Of(consumer)) + }) + + t.Run("defer groups among themselves stay unordered", func(t *testing.T) { + deferA := narrowingFetch(3, nil, "Product", narrowingTree("name", "price"), true, true) + deferB := narrowingFetch(4, nil, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(), tree(deferA), tree(deferB)}, nil) + assert.False(t, l1Of(deferA)) + assert.False(t, l1Of(deferB)) + }) + + t.Run("a malformed treeParents cycle degrades to unordered, never hangs", func(t *testing.T) { + // treeParents crosses the public ConfigureCaching API: probing whether + // the ROOT tree encloses a member of a 1<->2 parent cycle must + // terminate (the walk never reaches -1), leaving root and cycle + // unordered — the root provider loses its only consumer and both + // narrow off. + provider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), true, true) + consumer := narrowingFetch(4, nil, "Product", narrowingTree("name"), true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(provider), tree(consumer), tree()}, []int{-1, 2, 1}) + assert.False(t, l1Of(provider)) + assert.False(t, l1Of(consumer)) + }) + + t.Run("determinism: a second run leaves the narrowed state unchanged", func(t *testing.T) { + provider := narrowingFetch(1, nil, "Product", narrowingTree("name", "price"), true, true) + consumer := narrowingFetch(2, []int{1}, "Product", narrowingTree("name"), true, true) + lone := narrowingFetch(3, nil, "User", narrowingTree("id"), true, true) + trees := []*resolve.FetchTreeNode{tree(provider, consumer, lone)} + pass.optimize(trees, nil) + first := []bool{l1Of(provider), l1Of(consumer), l1Of(lone)} + pass.optimize(trees, nil) + assert.Equal(t, first, []bool{l1Of(provider), l1Of(consumer), l1Of(lone)}) + assert.Equal(t, []bool{true, true, false}, first) + }) + + t.Run("union computation never mutates the provider trees", func(t *testing.T) { + providerA := narrowingFetch(1, nil, "Product", &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("brand"), Value: &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("id"), Value: &resolve.Scalar{Path: []string{"id"}}}, + }}}, + }}, true, true) + providerB := narrowingFetch(2, nil, "Product", &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("brand"), Value: &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("location"), Value: &resolve.Scalar{Path: []string{"location"}}}, + }}}, + }}, true, true) + consumer := narrowingFetch(3, []int{1, 2}, "Product", &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("brand"), Value: &resolve.Object{Fields: []*resolve.Field{ + {Name: []byte("id"), Value: &resolve.Scalar{Path: []string{"id"}}}, + {Name: []byte("location"), Value: &resolve.Scalar{Path: []string{"location"}}}, + }}}, + }}, true, true) + pass.optimize([]*resolve.FetchTreeNode{tree(providerA, providerB, consumer)}, nil) + assert.True(t, l1Of(consumer)) // served by the recursive union + // The FIRST-PASS aliasing bug: the union merged INTO provider A's live + // tree. A's brand object must still have exactly its own field. + brandA := providerA.Item.Fetch.CacheConfig().ProvidesData.Fields[0].Value.(*resolve.Object) + require.Len(t, brandA.Fields, 1) + assert.Equal(t, "id", string(brandA.Fields[0].Name)) + }) +} diff --git a/v2/pkg/engine/cache/partial.go b/v2/pkg/engine/cache/partial.go new file mode 100644 index 0000000000..7f88e02a94 --- /dev/null +++ b/v2/pkg/engine/cache/partial.go @@ -0,0 +1,107 @@ +package cache + +import ( + "errors" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// errPartialBatchEntityCountMismatch surfaces a subgraph contract violation: +// the reduced _entities response must contain exactly one element per sent +// representation (nulls included), like the loader's own full-batch +// invalidBatchItemCount check. +var errPartialBatchEntityCountMismatch = errors.New("partial batch _entities count does not match the reduced representations") + +// Partial fetching: a batch entity fetch with SOME buckets covered +// and some not serves the covered ones from cache and sends the subgraph a +// REDUCED representations list; the response then realigns to the original +// bucket positions via ItemCacheState.BatchIndex. The controller marks the +// missing buckets on handle.BatchFetchKeep and the LOADER assembles the +// reduced input from the already-rendered representation segments (before any +// bytes are parsed back); the data merge lives in the partial arm of +// OnFetchResult (one hook, one lock acquisition). + +// onPartialBatchResult is the FetchPartial merge arm: within ONE transaction +// it splices every covered bucket from cache (denormalized per merge target) +// and realigns the REDUCED response — fetched buckets consume the _entities +// array in order — merging and cache-writing the fresh values. On failure +// signals the covered splice still happens (the cached data is valid; the +// loader has already rendered the fetch errors) and only the fetched subset's +// merge and writes are skipped. +func (r *requestCache) onPartialBatchResult(h *resolve.FetchCacheHandle, in resolve.MergeInput, state *handleState) error { + cfg := state.cfg + tx := in.Arena.Begin() + defer tx.Commit() + + fetchFailed := in.FetchFailed || in.HasErrors || in.ResponseData == nil + var batch []*astjson.Value + if !fetchFailed { + batch = in.ResponseData.GetArray() + if batch == nil { + fetchFailed = true + } + } + // The storability of the FETCHED subset only; the covered buckets are served + // from entries that already exist and owe no write. Resolving it behind the + // failure gate also keeps a failed fetch from reporting a private result it + // would never have stored. + var decision cachingDecision + if !fetchFailed { + decision = r.cachingDecisionFor(cfg, in) + } + // The FETCHED subset's contribution to the client cache answer; the covered + // buckets fold their own remaining freshness below, item by item. + r.foldFetchedResult(h, in, decision) + + fetchedIndex := 0 + for i := range h.Items { + item := &h.Items[i] + var targets []*astjson.Value + if item.BatchIndex >= 0 && item.BatchIndex < len(in.BatchStats) { + targets = in.BatchStats[item.BatchIndex] + } + if item.FromCache != nil { + // Covered bucket: identical duties to OnFetchSkipped — fold, splice, + // and nothing at all for a negative sentinel. + r.foldServedItem(cfg, item) + if err := r.spliceCachedItem(tx, cfg.ProvidesData, item, targets, in.MergePath); err != nil { + return err + } + continue + } + // Fetched bucket: consume the reduced response in order. + if fetchFailed { + continue + } + if fetchedIndex >= len(batch) { + return errPartialBatchEntityCountMismatch + } + src := batch[fetchedIndex] + fetchedIndex++ + if src == nil || src.Type() == astjson.TypeNull { + // A legitimately missing entity: nothing to merge, nothing to + // write (negative caching needs the loader's EmptyEntity signal, + // which is whole-response scoped — out of the partial path). + continue + } + for _, target := range targets { + if target == nil { + continue + } + if len(in.MergePath) > 0 { + if _, err := tx.MergeValuesWithPath(target, tx.StructuralCopy(src), in.MergePath...); err != nil { + return err + } + } else if _, err := tx.MergeValues(target, tx.StructuralCopy(src)); err != nil { + return err + } + } + r.writeFetchedValue(tx, decision, state, item, src) + } + if !fetchFailed && fetchedIndex != len(batch) { + return errPartialBatchEntityCountMismatch + } + return nil +} diff --git a/v2/pkg/engine/cache/partial_test.go b/v2/pkg/engine/cache/partial_test.go new file mode 100644 index 0000000000..83ebf365e6 --- /dev/null +++ b/v2/pkg/engine/cache/partial_test.go @@ -0,0 +1,283 @@ +package cache + +import ( + "strings" + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// partialConfig is the batch entity config with partial loading enabled. +func partialConfig(t *testing.T) *resolve.FetchCacheConfig { + t.Helper() + cfg := entityConfig(t, time.Minute) + cfg.EnablePartialCacheLoad = true + return cfg +} + +// batchPrepareInput builds a PrepareFetchInput with BatchStats buckets (one +// target per bucket) and the rendered representations input matching them. +func batchPrepareInput(t *testing.T, cfg *resolve.FetchCacheConfig, upcs ...string) (resolve.PrepareFetchInput, [][]*astjson.Value) { + t.Helper() + buckets := make([][]*astjson.Value, 0, len(upcs)) + representations := make([]string, 0, len(upcs)) + for _, upc := range upcs { + representation := `{"__typename":"Product","upc":"` + upc + `"}` + representations = append(representations, representation) + buckets = append(buckets, []*astjson.Value{astjson.MustParseBytes([]byte(representation))}) + } + in := resolve.PrepareFetchInput{ + Config: cfg, + BatchStats: buckets, + Input: []byte(`{"body":{"query":"...","variables":{"representations":[` + strings.Join(representations, ",") + `]}}}`), + Arena: beginner(), + } + return in, buckets +} + +// TestPartialBatchRows covers the split, realign, adversarial, and failure rows. +func TestPartialBatchRows(t *testing.T) { + fresh := func(upc string) string { + return `{"__typename":"Product","name":"P` + upc + `","price":100}` + } + + t.Run("partial split: exact partition, reduced input, lookups for all", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + key1 := writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + store.ops = nil // the partial request's ops assert in isolation + + rc := NewController(store, nil).BeginRequest(nil) + in, _ := batchPrepareInput(t, cfg, "1", "2", "3") + decision, handle := rc.PrepareFetch(in) + assert.Equal(t, resolve.DecisionFetchPartial, decision) + require.NotNil(t, handle) + // Exact partition: bucket 1 covered, buckets 0 and 2 missing. + assert.Nil(t, handle.Items[0].FromCache) + require.NotNil(t, handle.Items[1].FromCache) + assert.Equal(t, fresh("2"), string(handle.Items[1].FromCache.MarshalTo(nil))) + assert.Nil(t, handle.Items[2].FromCache) + // The keep mask marks EXACTLY the missing buckets (the loader then + // assembles the reduced input from the pre-rendered segments). + assert.Equal(t, []bool{true, false, true}, handle.BatchFetchKeep) + // ONE batched lookup covering ALL buckets in bucket order, with only + // the primed key hitting. + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{handle.Items[0].RenderedKey, key1, handle.Items[2].RenderedKey}, + Hits: []bool{false, true, false}, + }, + }, store.ops) + }) + + t.Run("realign: fetched entities land at their ORIGINAL positions; writes only for fetched", func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + store.ops = nil + + rc := NewController(store, nil).BeginRequest(nil) + in, buckets := batchPrepareInput(t, cfg, "1", "2", "3") + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionFetchPartial, decision) + + // The REDUCED response: entities for upc 1 and 3 only, in order. + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[` + fresh("1") + `,` + fresh("3") + `]`)), + Arena: beginner(), + })) + // Full merged targets: cached bucket 1 spliced, fetched 0 and 2 merged + // at their original positions. + assert.Equal(t, `{"__typename":"Product","upc":"1","name":"P1","price":100}`, string(buckets[0][0].MarshalTo(nil))) + assert.Equal(t, `{"__typename":"Product","upc":"2","name":"P2","price":100}`, string(buckets[1][0].MarshalTo(nil))) + assert.Equal(t, `{"__typename":"Product","upc":"3","name":"P3","price":100}`, string(buckets[2][0].MarshalTo(nil))) + + rc.EndRequest() + // Writes ONLY for the fetched buckets (0 and 2), none for the covered one. + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{handle.Items[0].RenderedKey, handle.Items[1].RenderedKey, handle.Items[2].RenderedKey}, + Hits: []bool{false, true, false}, + }, + { + Kind: "SetMany", + Items: []testStoreItem{ + { + Key: handle.Items[0].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"P1","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:d3cc039c7a9789e7", // upc "1" + }, + }, + { + Key: handle.Items[2].RenderedKey, + Value: `{"data":{"__typename":"Product","name":"P3","price":100},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, + TTL: time.Minute, + Tags: []string{ + "subgraph:products", + "type:products:Product", + "entity:products:Product:dae7809df4f7fdee", // upc "3" + }, + }, + }, + }, + }, store.ops) + }) + }) + + t.Run("duplicated representations: one bucket, many targets, all served", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + + rc := NewController(store, nil).BeginRequest(nil) + in, buckets := batchPrepareInput(t, cfg, "1", "2") + // The "1" bucket has TWO merge targets (a duplicated representation). + buckets[0] = append(buckets[0], astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`))) + in.BatchStats = buckets + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionFetchPartial, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[` + fresh("1") + `]`)), + Arena: beginner(), + })) + assert.Equal(t, `{"__typename":"Product","upc":"1","name":"P1","price":100}`, string(buckets[0][0].MarshalTo(nil))) + assert.Equal(t, `{"__typename":"Product","upc":"1","name":"P1","price":100}`, string(buckets[0][1].MarshalTo(nil))) + assert.Equal(t, `{"__typename":"Product","upc":"2","name":"P2","price":100}`, string(buckets[1][0].MarshalTo(nil))) + }) + + t.Run("all-hit degenerates to SkipFullHit; all-miss to Fetch", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "1"), fresh("1")) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + + rc := NewController(store, nil).BeginRequest(nil) + inHit, _ := batchPrepareInput(t, cfg, "1", "2") + decision, handle := rc.PrepareFetch(inHit) + assert.Equal(t, resolve.DecisionSkipFullHit, decision) + assert.Nil(t, handle.BatchFetchKeep) + + inMiss, _ := batchPrepareInput(t, cfg, "8", "9") + decision, handle = rc.PrepareFetch(inMiss) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.BatchFetchKeep) + }) + + t.Run("single-element batch never goes partial", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + rc := NewController(store, nil).BeginRequest(nil) + in, _ := batchPrepareInput(t, cfg, "1") + decision, handle := rc.PrepareFetch(in) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.BatchFetchKeep) + }) + + t.Run("failure in the fetched subset: spliced subset intact, zero writes", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + store.ops = nil + + rc := NewController(store, nil).BeginRequest(nil) + in, buckets := batchPrepareInput(t, cfg, "1", "2") + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionFetchPartial, decision) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + FetchFailed: true, + Arena: beginner(), + })) + rc.EndRequest() + // The covered bucket is spliced; the failed bucket's target untouched. + assert.Equal(t, `{"__typename":"Product","upc":"1"}`, string(buckets[0][0].MarshalTo(nil))) + assert.Equal(t, `{"__typename":"Product","upc":"2","name":"P2","price":100}`, string(buckets[1][0].MarshalTo(nil))) + // The lookup is the request's ONLY store op: a failed fetched subset + // writes nothing. + assert.Equal(t, []testStoreOp{ + { + Kind: "GetMany", + Keys: []string{handle.Items[0].RenderedKey, handle.Items[1].RenderedKey}, + Hits: []bool{false, true}, + }, + }, store.ops) + }) + + t.Run("a short reduced response is a contract violation, not a silent skip", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + + rc := NewController(store, nil).BeginRequest(nil) + in, buckets := batchPrepareInput(t, cfg, "1", "2", "3") + decision, handle := rc.PrepareFetch(in) + require.Equal(t, resolve.DecisionFetchPartial, decision) + // TWO representations were sent; only ONE entity came back. + err := rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[` + fresh("1") + `]`)), + Arena: beginner(), + }) + assert.ErrorIs(t, err, errPartialBatchEntityCountMismatch) + }) + + t.Run("an over-long reduced response is a contract violation too", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + + rc := NewController(store, nil).BeginRequest(nil) + in, buckets := batchPrepareInput(t, cfg, "1", "2") + _, handle := rc.PrepareFetch(in) + err := rc.OnFetchResult(handle, resolve.MergeInput{ + BatchStats: buckets, + ResponseData: astjson.MustParseBytes([]byte(`[` + fresh("1") + `,` + fresh("9") + `]`)), + Arena: beginner(), + }) + assert.ErrorIs(t, err, errPartialBatchEntityCountMismatch) + }) + + t.Run("config gate: partial disabled keeps all-or-nothing", func(t *testing.T) { + store := newTestStore() + cfg := entityConfig(t, time.Minute) // EnablePartialCacheLoad false + writeThrough(t, NewController(store, nil).BeginRequest(nil), cfg, productItem(t, "2"), fresh("2")) + + rc := NewController(store, nil).BeginRequest(nil) + in, _ := batchPrepareInput(t, cfg, "1", "2") + decision, handle := rc.PrepareFetch(in) + assert.Equal(t, resolve.DecisionFetch, decision) + assert.Nil(t, handle.BatchFetchKeep) + }) + + t.Run("shadow wins over partial", func(t *testing.T) { + store := newTestStore() + cfg := partialConfig(t) + cfg.ShadowMode = true + writeThrough(t, NewController(store, nil).BeginRequest(nil), func() *resolve.FetchCacheConfig { + plain := partialConfig(t) + return plain + }(), productItem(t, "2"), fresh("2")) + + rc := NewController(store, nil).BeginRequest(nil) + in, _ := batchPrepareInput(t, cfg, "1", "2") + decision, handle := rc.PrepareFetch(in) + assert.Equal(t, resolve.DecisionFetchShadow, decision) + assert.Nil(t, handle.BatchFetchKeep) + }) +} diff --git a/v2/pkg/engine/cache/transform.go b/v2/pkg/engine/cache/transform.go new file mode 100644 index 0000000000..9cbb9a0cec --- /dev/null +++ b/v2/pkg/engine/cache/transform.go @@ -0,0 +1,186 @@ +package cache + +import ( + "cmp" + "slices" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" + "github.com/wundergraph/graphql-go-tools/v2/pkg/pool" +) + +// The transform module: values are cached in NORMALIZED form — schema field +// names (aliases resolved via Field.OriginalName) with a deterministic +// argument suffix folded into the object key (from Field.CacheArgs and the +// request's variable values) — and DENORMALIZED back to the requesting +// operation's aliases at serve time. Normalization is what makes a value +// cached by one operation reusable by another with different aliases, and the +// argument suffix is what keeps `friends(first:5)` from ever serving +// `friends(first:20)`. Partial fetching reuses these walks per field. + +// normalizedFieldName is the SINGLE derivation of a field's cache-side key: +// the schema name (OriginalName when aliased) plus the argument suffix. The +// write path, the coverage walk, and the read path all go through it, so the +// key spaces cannot diverge. +func normalizedFieldName(ctx *resolve.Context, field *resolve.Field) string { + name := string(field.Name) + if len(field.OriginalName) > 0 { + name = string(field.OriginalName) + } + if len(field.CacheArgs) == 0 { + return name + } + return name + computeArgSuffix(ctx, field.CacheArgs) +} + +// computeArgSuffix hashes the field's variable-bound argument values into a +// deterministic "_<16-hex xxhash64>" suffix: args sorted by name, each value +// taken from the request variables (through the remap that normalization may +// have applied), absent values hashed as null. +func computeArgSuffix(ctx *resolve.Context, args []resolve.CacheFieldArg) string { + sorted := args + if !slices.IsSortedFunc(sorted, func(a, b resolve.CacheFieldArg) int { + return cmp.Compare(a.Name, b.Name) + }) { + sorted = slices.Clone(args) + slices.SortFunc(sorted, func(a, b resolve.CacheFieldArg) int { + return cmp.Compare(a.Name, b.Name) + }) + } + h := pool.Hash64.Get() + for i, arg := range sorted { + if i > 0 { + _, _ = h.WriteString(",") + } + _, _ = h.WriteString(arg.Name) + _, _ = h.WriteString(":") + var value *astjson.Value + if ctx != nil && ctx.Variables != nil { + variableName := arg.VariableName + if mapped, ok := ctx.RemapVariables[variableName]; ok { + variableName = mapped + } + value = ctx.Variables.Get(variableName) + } + if value == nil { + _, _ = h.WriteString("null") + } else { + _, _ = h.Write(value.MarshalTo(nil)) + } + } + sum := h.Sum64() + pool.Hash64.Put(h) + return "_" + hex64(sum) +} + +// normalizeToSchema rewrites a fetched (alias-shaped) value into the stored +// form: object keys become normalized field names, recursively; fields the +// tree does not select (e.g. __typename, key fields) are preserved as-is. The +// caller gates on HasAliases — a tree without aliases or args stores the raw +// value unchanged. +func normalizeToSchema(tx *resolve.CacheTransaction, ctx *resolve.Context, value *astjson.Value, node resolve.Node) *astjson.Value { + if value == nil || node == nil { + return value + } + switch typed := node.(type) { + case *resolve.Object: + if value.Type() != astjson.TypeObject { + return value + } + out := tx.NewObject() + seen := make(map[string]struct{}, len(typed.Fields)) + for _, field := range typed.Fields { + responseKey := string(field.Name) + fieldValue := value.Get(responseKey) + if fieldValue == nil { + continue + } + out.Set(nil, normalizedFieldName(ctx, field), normalizeToSchema(tx, ctx, fieldValue, field.Value)) + seen[responseKey] = struct{}{} + } + obj, err := value.Object() + if err != nil { + return value + } + obj.Visit(func(key []byte, fieldValue *astjson.Value) { + responseKey := string(key) + if _, ok := seen[responseKey]; ok { + return + } + out.Set(nil, responseKey, fieldValue) + }) + return out + case *resolve.Array: + if value.Type() != astjson.TypeArray { + return value + } + items, err := value.Array() + if err != nil { + return value + } + out := tx.NewArray() + for i, item := range items { + out.SetArrayItem(nil, i, normalizeToSchema(tx, ctx, item, typed.Item)) + } + return out + default: + return value + } +} + +// denormalizeToSelection rewrites a cached (normalized) value into the +// REQUESTING operation's shape: fields come out under their aliases, in +// selection order, with cached-only extras appended after (so a write-back or +// resolver never loses data the selection did not name). It always builds a +// fresh transaction-owned value, which also serves as the aliasing-safe copy +// for the splice. +func denormalizeToSelection(tx *resolve.CacheTransaction, ctx *resolve.Context, value *astjson.Value, node resolve.Node) *astjson.Value { + if value == nil || node == nil { + return value + } + switch typed := node.(type) { + case *resolve.Object: + if value.Type() != astjson.TypeObject { + return value + } + out := tx.NewObject() + seen := make(map[string]struct{}, len(typed.Fields)) + for _, field := range typed.Fields { + storedKey := normalizedFieldName(ctx, field) + fieldValue := value.Get(storedKey) + if fieldValue == nil { + continue + } + out.Set(nil, string(field.Name), denormalizeToSelection(tx, ctx, fieldValue, field.Value)) + seen[storedKey] = struct{}{} + } + obj, err := value.Object() + if err != nil { + return value + } + obj.Visit(func(key []byte, fieldValue *astjson.Value) { + storedKey := string(key) + if _, ok := seen[storedKey]; ok { + return + } + out.Set(nil, storedKey, fieldValue) + }) + return out + case *resolve.Array: + if value.Type() != astjson.TypeArray { + return value + } + items, err := value.Array() + if err != nil { + return value + } + out := tx.NewArray() + for i, item := range items { + out.SetArrayItem(nil, i, denormalizeToSelection(tx, ctx, item, typed.Item)) + } + return out + default: + return value + } +} diff --git a/v2/pkg/engine/cache/transform_test.go b/v2/pkg/engine/cache/transform_test.go new file mode 100644 index 0000000000..105ee3ddde --- /dev/null +++ b/v2/pkg/engine/cache/transform_test.go @@ -0,0 +1,235 @@ +package cache + +import ( + "testing" + "testing/synctest" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// variableContext builds a resolve.Context carrying the given variables JSON. +func variableContext(t *testing.T, variables string) *resolve.Context { + t.Helper() + ctx := resolve.NewContext(t.Context()) + if variables != "" { + ctx.Variables = astjson.MustParseBytes([]byte(variables)) + } + return ctx +} + +func testTx() *resolve.CacheTransaction { + return resolve.NewTransactionBeginner(nil, &resolve.DataBuffer{}).Begin() +} + +// aliasedTree is a ProvidesData tree with an aliased scalar, an arg-suffixed +// list field, and a nested object with an aliased leaf. +func aliasedTree() *resolve.Object { + tree := &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("productName"), + OriginalName: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"productName"}}, + }, + { + Name: []byte("friends"), + CacheArgs: []resolve.CacheFieldArg{{Name: "first", VariableName: "first"}}, + Value: &resolve.Array{ + Nullable: true, + Path: []string{"friends"}, + Item: &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("handle"), + OriginalName: []byte("username"), + Value: &resolve.Scalar{Nullable: true, Path: []string{"handle"}}, + }, + }, + }, + }, + }, + }, + } + resolve.ComputeHasAliases(tree) + return tree +} + +func TestNormalizedFieldName(t *testing.T) { + ctx := variableContext(t, `{"first":5}`) + + t.Run("plain field", func(t *testing.T) { + assert.Equal(t, "name", normalizedFieldName(ctx, &resolve.Field{Name: []byte("name")})) + }) + + t.Run("aliased field uses the schema name", func(t *testing.T) { + assert.Equal(t, "name", normalizedFieldName(ctx, &resolve.Field{Name: []byte("productName"), OriginalName: []byte("name")})) + }) + + t.Run("argument suffix is deterministic and order-independent", func(t *testing.T) { + ctxAB := variableContext(t, `{"a":1,"b":2}`) + args := []resolve.CacheFieldArg{{Name: "x", VariableName: "a"}, {Name: "y", VariableName: "b"}} + reversed := []resolve.CacheFieldArg{{Name: "y", VariableName: "b"}, {Name: "x", VariableName: "a"}} + nameA := normalizedFieldName(ctxAB, &resolve.Field{Name: []byte("f"), CacheArgs: args}) + nameB := normalizedFieldName(ctxAB, &resolve.Field{Name: []byte("f"), CacheArgs: reversed}) + assert.Equal(t, nameA, nameB) + assert.Equal(t, "f"+computeArgSuffix(ctxAB, args), nameA) + }) + + t.Run("different argument values produce different suffixes", func(t *testing.T) { + field := &resolve.Field{Name: []byte("friends"), CacheArgs: []resolve.CacheFieldArg{{Name: "first", VariableName: "first"}}} + name5 := normalizedFieldName(variableContext(t, `{"first":5}`), field) + name20 := normalizedFieldName(variableContext(t, `{"first":20}`), field) + assert.NotEqual(t, name5, name20) + }) + + t.Run("remapped variables resolve through the remap", func(t *testing.T) { + ctx := variableContext(t, `{"a":5}`) + ctx.RemapVariables = map[string]string{"first": "a"} + field := &resolve.Field{Name: []byte("friends"), CacheArgs: []resolve.CacheFieldArg{{Name: "first", VariableName: "first"}}} + direct := normalizedFieldName(variableContext(t, `{"first":5}`), field) + assert.Equal(t, direct, normalizedFieldName(ctx, field)) + }) + + t.Run("absent variables hash as null", func(t *testing.T) { + field := &resolve.Field{Name: []byte("friends"), CacheArgs: []resolve.CacheFieldArg{{Name: "first", VariableName: "first"}}} + noVars := normalizedFieldName(variableContext(t, ""), field) + nilCtx := normalizedFieldName(nil, field) + assert.Equal(t, noVars, nilCtx) + }) +} + +// TestNormalizeDenormalizeRoundTrip proves the transform pair: an alias-shaped +// response normalizes to schema names + arg suffixes (full stored form +// asserted) and denormalizes back under a DIFFERENT alias set. +func TestNormalizeDenormalizeRoundTrip(t *testing.T) { + ctx := variableContext(t, `{"first":5}`) + tx := testTx() + defer tx.Commit() + + suffix := computeArgSuffix(ctx, []resolve.CacheFieldArg{{Name: "first", VariableName: "first"}}) + response := astjson.MustParseBytes([]byte(`{"__typename":"User","productName":"Table","friends":[{"handle":"alice"},{"handle":"bob"}]}`)) + + stored := normalizeToSchema(tx, ctx, response, aliasedTree()) + assert.Equal(t, + `{"name":"Table","friends`+suffix+`":[{"username":"alice"},{"username":"bob"}],"__typename":"User"}`, + string(stored.MarshalTo(nil))) + + // A DIFFERENT operation selects the same data under other aliases. + otherTree := &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("title"), + OriginalName: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"title"}}, + }, + { + Name: []byte("buddies"), + OriginalName: []byte("friends"), + CacheArgs: []resolve.CacheFieldArg{{Name: "first", VariableName: "first"}}, + Value: &resolve.Array{ + Nullable: true, + Path: []string{"buddies"}, + Item: &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("nick"), + OriginalName: []byte("username"), + Value: &resolve.Scalar{Nullable: true, Path: []string{"nick"}}, + }, + }, + }, + }, + }, + }, + } + resolve.ComputeHasAliases(otherTree) + require.True(t, covers(ctx, stored, otherTree)) + + served := denormalizeToSelection(tx, ctx, stored, otherTree) + assert.Equal(t, + `{"title":"Table","buddies":[{"nick":"alice"},{"nick":"bob"}],"__typename":"User"}`, + string(served.MarshalTo(nil))) +} + +// TestArgumentMismatchIsMiss is the D6 coverage rule: a value cached under one +// argument suffix does not satisfy the same field with different arguments. +func TestArgumentMismatchIsMiss(t *testing.T) { + writeCtx := variableContext(t, `{"first":5}`) + readCtx := variableContext(t, `{"first":20}`) + tx := testTx() + defer tx.Commit() + + tree := aliasedTree() + response := astjson.MustParseBytes([]byte(`{"__typename":"User","productName":"Table","friends":[{"handle":"alice"}]}`)) + stored := normalizeToSchema(tx, writeCtx, response, tree) + + assert.True(t, covers(writeCtx, stored, tree)) + assert.False(t, covers(readCtx, stored, tree)) +} + +// TestControllerAliasRoundTrip drives the transforms through the controller: +// an alias-shaped response is STORED normalized, and a second request with a +// different alias set is served, spliced under ITS aliases. +func TestControllerAliasRoundTrip(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + store := newTestStore() + + writeCfg := entityConfig(t, time.Minute) + writeCfg.ProvidesData = &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("productName"), + OriginalName: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"productName"}}, + }, + }, + } + resolve.ComputeHasAliases(writeCfg.ProvidesData) + + rc := NewController(store, nil).BeginRequest(variableContext(t, "")) + item := productItem(t, "1") + _, handle := prepare(t, rc, writeCfg, item) + require.NoError(t, rc.OnFetchResult(handle, resolve.MergeInput{ + Items: []*astjson.Value{item}, + ResponseData: astjson.MustParseBytes([]byte(`{"__typename":"Product","productName":"Table"}`)), + Arena: beginner(), + })) + rc.EndRequest() + key := handle.Items[0].RenderedKey + // The STORED form carries the schema name. + value, ok := store.value(key) + require.True(t, ok) + assert.Equal(t, `{"data":{"name":"Table","__typename":"Product"},"cc":{"ttl":60,"created":946684800,"scope":"public"}}`, string(value)) + + // A second operation selects the same field under ANOTHER alias. + readCfg := entityConfig(t, time.Minute) + readCfg.ProvidesData = &resolve.Object{ + Fields: []*resolve.Field{ + { + Name: []byte("label"), + OriginalName: []byte("name"), + Value: &resolve.Scalar{Nullable: false, Path: []string{"label"}}, + }, + }, + } + resolve.ComputeHasAliases(readCfg.ProvidesData) + + rc2 := NewController(store, nil).BeginRequest(variableContext(t, "")) + item2 := productItem(t, "1") + decision, handle2 := prepare(t, rc2, readCfg, item2) + require.Equal(t, resolve.DecisionSkipFullHit, decision) + require.NoError(t, rc2.OnFetchSkipped(handle2, resolve.MergeInput{ + Items: []*astjson.Value{item2}, + Arena: beginner(), + })) + assert.Equal(t, `{"__typename":"Product","upc":"1","label":"Table"}`, string(item2.MarshalTo(nil))) + }) +} diff --git a/v2/pkg/engine/datasource/graphql_datasource/graphql_datasource.go b/v2/pkg/engine/datasource/graphql_datasource/graphql_datasource.go index 55f1204813..2e99a6e3eb 100644 --- a/v2/pkg/engine/datasource/graphql_datasource/graphql_datasource.go +++ b/v2/pkg/engine/datasource/graphql_datasource/graphql_datasource.go @@ -29,6 +29,7 @@ import ( grpcdatasource "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/datasource/grpc_datasource" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/datasource/httpclient" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/representationvariable" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" "github.com/wundergraph/graphql-go-tools/v2/pkg/internal/quotes" "github.com/wundergraph/graphql-go-tools/v2/pkg/internal/unsafebytes" @@ -850,9 +851,13 @@ func (p *Planner[T]) addRepresentationsVariable() { } func (p *Planner[T]) buildRepresentationsVariable() resolve.Variable { + // Recording which representation fields are @key fields changes the plan, so + // it happens only where a consumer exists: the cache derives its per-entity + // invalidation tag from that subset. + markKeyFields := p.visitor.Config.Caching != nil objects := make([]*resolve.Object, 0, len(p.dataSourcePlannerConfig.RequiredFields)) for _, cfg := range p.dataSourcePlannerConfig.RequiredFields { - node, err := buildRepresentationVariableNode(p.visitor.Definition, cfg, p.dataSourceConfig.FederationConfiguration()) + node, err := representationvariable.BuildRepresentationVariableNode(p.visitor.Definition, cfg, p.dataSourceConfig.FederationConfiguration(), markKeyFields) if err != nil { p.stopWithError(errors.WithStack(fmt.Errorf("buildRepresentationsVariable: failed to build representation variable node: %w", err))) return nil @@ -862,7 +867,7 @@ func (p *Planner[T]) buildRepresentationsVariable() resolve.Variable { } return resolve.NewResolvableObjectVariable( - mergeRepresentationVariableNodes(objects), + representationvariable.MergeRepresentationVariableNodes(objects), ) } diff --git a/v2/pkg/engine/plan/cache_provides_data_visitor.go b/v2/pkg/engine/plan/cache_provides_data_visitor.go new file mode 100644 index 0000000000..85d9be8da7 --- /dev/null +++ b/v2/pkg/engine/plan/cache_provides_data_visitor.go @@ -0,0 +1,491 @@ +package plan + +import ( + "bytes" + "cmp" + "fmt" + "maps" + "regexp" + "slices" + "strings" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/ast" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astvisitor" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" + "github.com/wundergraph/graphql-go-tools/v2/pkg/lexer/literal" + "github.com/wundergraph/graphql-go-tools/v2/pkg/operationreport" +) + +// walk runs the caching provides-data walk on a DEDICATED walker after every +// planning walk has finished — fieldPlanners (populated by the main walk's +// LeaveField) is complete by then, and the planning walker's visitor set and +// filter stay untouched. One call carries all the state the walk needs. +func (v *cacheProvidesDataVisitor) walk(operation, definition *ast.Document, config Configuration, planners []PlannerConfiguration, fieldPlanners map[int][]int, report *operationreport.Report) { + walker := astvisitor.NewWalker(48) + v.Walker = &walker + v.operation = operation + v.definition = definition + v.config = config + v.planners = planners + v.fieldPlanners = fieldPlanners + v.reset() + walker.RegisterEnterFieldVisitor(v) + walker.RegisterLeaveFieldVisitor(v) + walker.Walk(operation, definition, report) +} + +// cacheProvidesDataVisitor is a gated SECOND, filter-free walk over the +// operation, run after the main planning walk. Per planner (i.e. per fetch) +// it builds the exact field tree that fetch RETURNS — alias-aware +// (Field.OriginalName), argument-aware (Field.CacheArgs), with inline-fragment +// OnTypeNames and the entity-boundary reset (a nested entity fetch provides +// the ENTITY's fields, not the path down to it). +type cacheProvidesDataVisitor struct { + *astvisitor.Walker + + operation, definition *ast.Document + config Configuration + // planners / fieldPlanners are the main walk's outputs: the per-planner + // configurations and the field→planner-IDs attribution. + planners []PlannerConfiguration + fieldPlanners map[int][]int + // objects is the per-planner tree under construction; currentFields the + // per-planner frame stack; entityBoundaryPaths remembers where a nested + // entity fetch's tree was reset so its direct children get OnTypeNames. + objects map[int]*resolve.Object + currentFields map[int][]objectFields + entityBoundaryPaths map[int]string +} + +// cacheProvidesDataFragmentMarkerRegex strips normalization fragment markers +// (e.g. ".$0User") from walker paths so they compare against fetch response +// paths. +var cacheProvidesDataFragmentMarkerRegex = regexp.MustCompile(`\.\$\d+\w+`) + +// reset clears all per-plan state so a Planner can be reused across Plan calls. +func (v *cacheProvidesDataVisitor) reset() { + v.objects = map[int]*resolve.Object{} + v.currentFields = map[int][]objectFields{} + v.entityBoundaryPaths = map[int]string{} +} + +func (v *cacheProvidesDataVisitor) EnterField(ref int) { + for _, plannerID := range v.fieldPlanners[ref] { + v.trackField(plannerID, ref) + } +} + +func (v *cacheProvidesDataVisitor) LeaveField(ref int) { + for _, plannerID := range v.fieldPlanners[ref] { + v.popFields(plannerID, ref) + } +} + +// attachTo resolves each planner to its fetch's *FetchInfo (the +// identity-stable key across dedup, fetchID-append, and concrete-type +// conversion, which all copy Info by reference) and stashes the side-table on +// the plan's response. Planner IDs are walked in sorted order for determinism. +func (v *cacheProvidesDataVisitor) attachTo(p Plan) { + resp := responseOf(p) + if resp == nil { + return + } + out := make(map[*resolve.FetchInfo]*resolve.Object, len(v.objects)) + for _, plannerID := range slices.Sorted(maps.Keys(v.objects)) { + if plannerID < 0 || plannerID >= len(v.planners) { + continue + } + fetchConfig := v.planners[plannerID].ObjectFetchConfiguration() + if fetchConfig == nil || fetchConfig.fetchItem == nil || fetchConfig.fetchItem.Fetch == nil { + continue + } + info := fetchConfig.fetchItem.Fetch.FetchInfo() + if info == nil { + continue + } + out[info] = v.objects[plannerID] + } + resp.SetCacheProvidesData(out) +} + +// trackField appends the field to the planner's current frame; on the +// planner's entity boundary it RESETS the tree instead, so a nested entity +// fetch's ProvidesData starts at the entity, not at the query root. +func (v *cacheProvidesDataVisitor) trackField(plannerID, fieldRef int) { + if !v.ensurePlanner(plannerID) { + return + } + + fieldName := v.operation.FieldNameBytes(fieldRef) + fetchResponseKey := v.operation.FieldAliasOrNameString(fieldRef) + + if v.isEntityBoundaryField(plannerID, fieldRef) { + entityObj := &resolve.Object{ + Fields: []*resolve.Field{}, + } + v.Walker.RunAfterEnterField(func() { + v.currentFields[plannerID] = append(v.currentFields[plannerID], objectFields{ + popOnField: fieldRef, + fields: &entityObj.Fields, + }) + }) + v.objects[plannerID] = entityObj + return + } + + // __typename dedup: normalization can leave the same __typename selection + // twice in one frame; a second entry would double-count coverage. + if bytes.Equal(fieldName, literal.TYPENAME) && len(v.currentFields[plannerID]) > 0 { + currentFields := v.currentFields[plannerID][len(v.currentFields[plannerID])-1] + for _, existingField := range *currentFields.fields { + if !bytes.Equal(existingField.Name, []byte(fetchResponseKey)) { + continue + } + existingValue, ok := existingField.Value.(*resolve.Scalar) + if ok && len(existingValue.Path) > 0 && existingValue.Path[0] == fetchResponseKey { + return + } + } + } + + fieldDefinition, ok := v.Walker.FieldDefinition(fieldRef) + if !ok { + return + } + fieldType := v.definition.FieldDefinitionType(fieldDefinition) + fieldValue := v.createFieldValue(fieldType, []string{fetchResponseKey}) + field := &resolve.Field{ + Name: []byte(fetchResponseKey), + Value: fieldValue, + OnTypeNames: v.resolveEntityOnTypeNames(plannerID, fieldRef, fieldName), + } + if fetchResponseKey != string(fieldName) { + field.OriginalName = fieldName + } + if v.operation.FieldHasArguments(fieldRef) { + // Root-operation-field arguments are part of the ROOT-FIELD cache key + // (rendered from the fetch input), not per-field CacheArgs. + enclosingType := v.Walker.EnclosingTypeDefinition.NameString(v.definition) + if !v.definition.Index.IsRootOperationTypeNameString(enclosingType) { + field.CacheArgs = v.captureFieldCacheArgs(fieldRef) + } + } + + currentFields := v.currentFields[plannerID][len(v.currentFields[plannerID])-1] + *currentFields.fields = append(*currentFields.fields, field) + + // Descend through list nesting to the object node (if any) and push its + // field slice as the new frame for this planner. + for { + switch node := fieldValue.(type) { + case *resolve.Array: + fieldValue = node.Item + case *resolve.Object: + v.Walker.RunAfterEnterField(func() { + v.currentFields[plannerID] = append(v.currentFields[plannerID], objectFields{ + popOnField: fieldRef, + fields: &node.Fields, + }) + }) + return + default: + return + } + } +} + +// ensurePlanner lazily creates the planner's root object and frame stack. +func (v *cacheProvidesDataVisitor) ensurePlanner(plannerID int) bool { + if plannerID < 0 || plannerID >= len(v.planners) { + return false + } + if _, ok := v.objects[plannerID]; ok { + return true + } + v.objects[plannerID] = &resolve.Object{ + Fields: []*resolve.Field{}, + } + v.currentFields[plannerID] = []objectFields{ + { + popOnField: -1, + fields: &v.objects[plannerID].Fields, + }, + } + return true +} + +// captureFieldCacheArgs records the field's variable-bound arguments, sorted +// by argument name so cache keys are order-independent. Literal (inline) +// argument values are intentionally skipped: they are part of the normalized +// operation and thus already part of the fetch input the key derives from. +func (v *cacheProvidesDataVisitor) captureFieldCacheArgs(fieldRef int) []resolve.CacheFieldArg { + argRefs := v.operation.FieldArguments(fieldRef) + if len(argRefs) == 0 { + return nil + } + + args := make([]resolve.CacheFieldArg, 0, len(argRefs)) + for _, argRef := range argRefs { + argName := v.operation.ArgumentNameString(argRef) + argValue := v.operation.ArgumentValue(argRef) + if argValue.Kind != ast.ValueKindVariable { + continue + } + args = append(args, resolve.CacheFieldArg{ + Name: argName, + VariableName: v.operation.VariableValueNameString(argValue.Ref), + }) + } + if len(args) == 0 { + return nil + } + slices.SortFunc(args, func(a, b resolve.CacheFieldArg) int { + return cmp.Compare(a.Name, b.Name) + }) + return args +} + +// createFieldValue maps a schema type to the resolve node shape the coverage +// walk consumes: scalars/enums to Scalar, composites to Object, lists to +// Array; nullability follows the schema. +func (v *cacheProvidesDataVisitor) createFieldValue(typeRef int, path []string) resolve.Node { + ofType := v.definition.Types[typeRef].OfType + + switch v.definition.Types[typeRef].TypeKind { + case ast.TypeKindNonNull: + node := v.createFieldValue(ofType, path) + switch n := node.(type) { + case *resolve.Scalar: + n.Nullable = false + case *resolve.Object: + n.Nullable = false + case *resolve.Array: + n.Nullable = false + } + return node + case ast.TypeKindList: + return &resolve.Array{ + Nullable: true, + Path: path, + Item: v.createFieldValue(ofType, nil), + } + case ast.TypeKindNamed: + typeName := v.definition.ResolveTypeNameString(typeRef) + typeDefinitionNode, ok := v.definition.Index.FirstNodeByNameStr(typeName) + if !ok { + return &resolve.Null{} + } + switch typeDefinitionNode.Kind { + case ast.NodeKindScalarTypeDefinition, ast.NodeKindEnumTypeDefinition: + return &resolve.Scalar{ + Nullable: true, + Path: path, + } + case ast.NodeKindObjectTypeDefinition, ast.NodeKindInterfaceTypeDefinition, ast.NodeKindUnionTypeDefinition: + return &resolve.Object{ + Nullable: true, + Path: path, + Fields: []*resolve.Field{}, + } + default: + return &resolve.Null{} + } + default: + return &resolve.Null{} + } +} + +// isEntityBoundaryField reports whether the field is exactly the planner's +// fetch response path, i.e. the point where a nested entity fetch's own data +// begins. +func (v *cacheProvidesDataVisitor) isEntityBoundaryField(plannerID, fieldRef int) bool { + fetchConfig := v.planners[plannerID].ObjectFetchConfiguration() + if fetchConfig == nil || fetchConfig.fetchItem == nil || fetchConfig.fetchItem.ResponsePath == "" { + return false + } + + currentPath := v.currentFullPath(fieldRef) + rootPrefix := "query" + if idx := strings.IndexByte(currentPath, '.'); idx > 0 { + rootPrefix = currentPath[:idx] + } + responsePath := strings.ReplaceAll(rootPrefix+"."+fetchConfig.fetchItem.ResponsePath, ".@", "") + normalizedFieldPath := v.normalizePathRemovingFragments(currentPath) + if normalizedFieldPath == responsePath { + v.entityBoundaryPaths[plannerID] = normalizedFieldPath + return true + } + return false +} + +// isEntityRootField reports whether the field is a DIRECT child of the +// planner's entity boundary; those fields carry the entity type condition. +func (v *cacheProvidesDataVisitor) isEntityRootField(plannerID, fieldRef int) bool { + boundaryPath, ok := v.entityBoundaryPaths[plannerID] + if !ok { + return false + } + return v.isEntityRootPath(boundaryPath, v.currentFullPath(fieldRef)) +} + +func (v *cacheProvidesDataVisitor) isEntityRootPath(boundaryPath, fullFieldPath string) bool { + normalized := v.normalizePathRemovingFragments(fullFieldPath) + rest, ok := strings.CutPrefix(normalized, boundaryPath+".") + if !ok { + return false + } + return !strings.Contains(rest, ".") +} + +func (v *cacheProvidesDataVisitor) currentFullPath(fieldRef int) string { + path := v.Walker.Path.DotDelimitedString() + if v.Walker.CurrentKind == ast.NodeKindField { + path += "." + v.operation.FieldAliasOrNameString(fieldRef) + } + return path +} + +func (v *cacheProvidesDataVisitor) normalizePathRemovingFragments(path string) string { + return cacheProvidesDataFragmentMarkerRegex.ReplaceAllString(path, "") +} + +func (v *cacheProvidesDataVisitor) popFields(plannerID, fieldRef int) { + fields, ok := v.currentFields[plannerID] + if !ok || len(fields) == 0 { + return + } + + last := len(fields) - 1 + if fields[last].popOnField == fieldRef { + v.currentFields[plannerID] = fields[:last] + } +} + +// resolveEntityOnTypeNames gives the entity boundary's direct children the +// enclosing entity type as their type condition (an _entities response is +// polymorphic); everything else falls through to the inline-fragment rules. +func (v *cacheProvidesDataVisitor) resolveEntityOnTypeNames(plannerID, fieldRef int, fieldName ast.ByteSlice) (onTypeNames [][]byte) { + if v.isEntityRootField(plannerID, fieldRef) { + enclosingTypeName := v.Walker.EnclosingTypeDefinition.NameBytes(v.definition) + if enclosingTypeName != nil { + return [][]byte{enclosingTypeName} + } + } + return v.resolveOnTypeNames(fieldRef, fieldName) +} + +// resolveOnTypeNames derives the field's type conditions from its enclosing +// inline fragment: concrete conditions pass through (plus a possible +// interfaceObject remap); abstract conditions expand to the implementing / +// member types, narrowed by the grandparent type where fragments nest. +func (v *cacheProvidesDataVisitor) resolveOnTypeNames(fieldRef int, fieldName ast.ByteSlice) (onTypeNames [][]byte) { + if len(v.Walker.Ancestors) < 2 { + return nil + } + inlineFragment := v.Walker.Ancestors[len(v.Walker.Ancestors)-2] + if inlineFragment.Kind != ast.NodeKindInlineFragment { + return nil + } + typeName := v.operation.InlineFragmentTypeConditionName(inlineFragment.Ref) + if typeName == nil { + typeName = v.Walker.EnclosingTypeDefinition.NameBytes(v.definition) + } + node, exists := v.definition.NodeByName(typeName) + if !exists || !node.Kind.IsAbstractType() { + return v.addInterfaceObjectNameToTypeNames(fieldRef, typeName, [][]byte{v.config.Types.RenameTypeNameOnMatchBytes(typeName)}) + } + + if node.Kind == ast.NodeKindUnionTypeDefinition { + if !bytes.Equal(fieldName, literal.TYPENAME) { + // Only __typename can be selected directly on a union. + v.Walker.StopWithInternalErr(fmt.Errorf("resolveOnTypeNames called with a union type and field %s", fieldName)) + return nil + } + + typeNames, ok := v.definition.UnionTypeDefinitionMemberTypeNamesAsBytes(node.Ref) + if ok { + onTypeNames = typeNames + } + } else { + typeNames, ok := v.definition.InterfaceTypeDefinitionImplementedByObjectWithNamesAsBytes(node.Ref) + if ok { + onTypeNames = typeNames + } + } + + // Narrow the expansion by the grandparent scope where fragments nest. + if len(v.Walker.TypeDefinitions) > 1 { + grandParent := v.Walker.TypeDefinitions[len(v.Walker.TypeDefinitions)-2] + switch grandParent.Kind { + case ast.NodeKindUnionTypeDefinition: + for i := 0; i < len(onTypeNames); i++ { + possibleMember, exists := v.definition.Index.FirstNodeByNameStr(string(onTypeNames[i])) + if !exists { + continue + } + if !v.definition.NodeIsUnionMember(possibleMember, grandParent) { + onTypeNames = append(onTypeNames[:i], onTypeNames[i+1:]...) + i-- + } + } + case ast.NodeKindInterfaceTypeDefinition: + objectTypesImplementingGrandParent, _ := v.definition.InterfaceTypeDefinitionImplementedByObjectWithNames(grandParent.Ref) + for i := 0; i < len(onTypeNames); i++ { + if !slices.Contains(objectTypesImplementingGrandParent, string(onTypeNames[i])) { + onTypeNames = append(onTypeNames[:i], onTypeNames[i+1:]...) + i-- + } + } + case ast.NodeKindObjectTypeDefinition: + grandParentTypeName := grandParent.NameBytes(v.definition) + for i := 0; i < len(onTypeNames); i++ { + if !bytes.Equal(onTypeNames[i], grandParentTypeName) { + onTypeNames = append(onTypeNames[:i], onTypeNames[i+1:]...) + i-- + } + } + default: + } + } + + return onTypeNames +} + +// addInterfaceObjectNameToTypeNames appends the interfaceObject interface name +// when a planner resolving this field declares the concrete type as an +// interfaceObject member, mirroring how such subgraphs respond with the +// interface type name. +func (v *cacheProvidesDataVisitor) addInterfaceObjectNameToTypeNames(fieldRef int, typeName []byte, onTypeNames [][]byte) [][]byte { + for i := range v.planners { + if !v.planners[i].HasPathWithFieldRef(fieldRef) { + continue + } + + for _, interfaceObjCfg := range v.planners[i].DataSourceConfiguration().FederationConfiguration().InterfaceObjects { + if slices.Contains(interfaceObjCfg.ConcreteTypeNames, string(typeName)) { + return append(onTypeNames, []byte(interfaceObjCfg.InterfaceTypeName)) + } + } + } + return onTypeNames +} + +// responseOf extracts the GraphQLResponse the side-table attaches to. +func responseOf(p Plan) *resolve.GraphQLResponse { + switch t := p.(type) { + case *SynchronousResponsePlan: + return t.Response + case *DeferResponsePlan: + if t.Response == nil { + return nil + } + return t.Response.Response + case *SubscriptionResponsePlan: + if t.Response == nil { + return nil + } + return t.Response.Response + default: + return nil + } +} diff --git a/v2/pkg/engine/plan/cache_provides_data_visitor_port_test.go b/v2/pkg/engine/plan/cache_provides_data_visitor_port_test.go new file mode 100644 index 0000000000..7067807b48 --- /dev/null +++ b/v2/pkg/engine/plan/cache_provides_data_visitor_port_test.go @@ -0,0 +1,789 @@ +package plan + +import ( + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/ast" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astnormalization" + "github.com/wundergraph/graphql-go-tools/v2/pkg/asttransform" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astvalidation" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astvisitor" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" + "github.com/wundergraph/graphql-go-tools/v2/pkg/internal/unsafeparser" + "github.com/wundergraph/graphql-go-tools/v2/pkg/operationreport" +) + +// TestCacheProvidesDataVisitor asserts the FULL per-fetch ProvidesData tree +// map. Planner 0 is the root fetch (accountDS), planner 1 the nested entity +// fetch at "user" (profileDS). +func TestCacheProvidesDataVisitor(t *testing.T) { + tests := []struct { + name string + op string + want func(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[*resolve.FetchInfo]*resolve.Object + }{ + { + name: "single key entity selection", + op: ` + query { + user(id: "1") { + id + username + } + }`, + want: func(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[*resolve.FetchInfo]*resolve.Object { + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + return map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"username"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + } + }, + }, + { + name: "multi field entity with nested object", + op: ` + query { + user(id: "1") { + id + username + profile { + displayName + } + } + }`, + want: func(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[*resolve.FetchInfo]*resolve.Object { + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + return map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"username"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("profile"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"profile"}, + Fields: []*resolve.Field{ + { + Name: []byte("displayName"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"displayName"}, + }, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + } + }, + }, + { + name: "aliased field stores original name", + op: ` + query { + user(id: "1") { + id + handle: username + } + }`, + want: func(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[*resolve.FetchInfo]*resolve.Object { + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + return map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("handle"), + OriginalName: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"handle"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + } + }, + }, + { + name: "variable arguments are captured except on root operation fields", + op: ` + query($id: ID!, $first: Int, $after: String) { + user(id: $id) { + id + friends(first: $first, after: $after) { + username + } + } + }`, + want: func(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[*resolve.FetchInfo]*resolve.Object { + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + return map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("friends"), + Value: &resolve.Array{ + Nullable: true, + Path: []string{"friends"}, + Item: &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"username"}, + }, + }, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("User")}, + CacheArgs: []resolve.CacheFieldArg{ + {Name: "after", VariableName: "after"}, + {Name: "first", VariableName: "first"}, + }, + }, + }, + }, + } + }, + }, + { + name: "typename is deduplicated in one frame", + op: ` + query { + user(id: "1") { + id + __typename + __typename + username + } + }`, + want: func(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[*resolve.FetchInfo]*resolve.Object { + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + return map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + { + Name: []byte("__typename"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"__typename"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"__typename"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"username"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + } + }, + }, + { + name: "inline fragment fields carry the concrete type condition", + op: ` + query { + user(id: "1") { + id + pet { + name + ... on Dog { + barks + } + } + } + }`, + want: func(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[*resolve.FetchInfo]*resolve.Object { + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + return map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("pet"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"pet"}, + Fields: []*resolve.Field{ + { + Name: []byte("name"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"name"}, + }, + }, + { + Name: []byte("barks"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"barks"}, + }, + OnTypeNames: [][]byte{[]byte("Dog")}, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + } + }, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pd := planCacheProvidesData(t, tt.op) + + assert.Equal(t, tt.want(t, pd), pd) + }) + } +} + +// TestCacheProvidesDataVisitorAdversarial goes beyond the OLD test set (a +// verbatim port would carry latent OLD bugs): per-fetch attribution with an +// irrelevant provider sharing the consumer query, partial overlap of two +// entity fetches on the same field, and a planner with no attributed fields. +func TestCacheProvidesDataVisitorAdversarial(t *testing.T) { + t.Run("irrelevant provider does not leak into sibling trees", func(t *testing.T) { + planners := defaultProvidesDataPlanners() + planners = append(planners, newTestProvidesDataPlanner("", &resolve.FetchInfo{DataSourceID: "statsDS"})) + routes := func(path string, ref int, out map[int][]int) { + switch { + case path == "query.stats": + out[ref] = []int{2} + case path == "query.user": + out[ref] = []int{0, 1} + case path == "query.user.id": + out[ref] = []int{0} + case strings.HasPrefix(path, "query.user."): + out[ref] = []int{1} + } + } + pd := planCacheProvidesDataWith(t, ` + query { + user(id: "1") { id username } + stats + }`, planners, routes) + + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + gotStatsInfo := requireProvidesDataInfo(t, pd, "statsDS") + assert.Equal(t, map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"username"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + gotStatsInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("stats"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"stats"}, + }, + }, + }, + }, + }, pd) + }) + + t.Run("partial overlap: two entity fetches sharing one field get their own trees", func(t *testing.T) { + planners := defaultProvidesDataPlanners() + planners = append(planners, newTestProvidesDataPlanner("user", &resolve.FetchInfo{DataSourceID: "secondEntityDS"})) + routes := func(path string, ref int, out map[int][]int) { + switch { + case path == "query.user": + out[ref] = []int{0, 1, 2} + case path == "query.user.id": + out[ref] = []int{0} + case path == "query.user.username": + out[ref] = []int{1, 2} + case strings.HasPrefix(path, "query.user."): + out[ref] = []int{1} + } + } + pd := planCacheProvidesDataWith(t, ` + query { + user(id: "1") { id username profile { displayName } } + }`, planners, routes) + + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + gotSecondInfo := requireProvidesDataInfo(t, pd, "secondEntityDS") + assert.Equal(t, map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"username"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("profile"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"profile"}, + Fields: []*resolve.Field{ + { + Name: []byte("displayName"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"displayName"}, + }, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + gotSecondInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("username"), + Value: &resolve.Scalar{ + Nullable: true, + Path: []string{"username"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, + }, pd) + }) + + t.Run("empty selections: unrouted planner absent, boundary-only entity planner empty", func(t *testing.T) { + planners := defaultProvidesDataPlanners() + planners = append(planners, newTestProvidesDataPlanner("", &resolve.FetchInfo{DataSourceID: "unusedDS"})) + pd := planCacheProvidesDataWith(t, ` + query { + user(id: "1") { id } + }`, planners, defaultProvidesDataRoutes) + + accountInfo := requireProvidesDataInfo(t, pd, "accountDS") + // profileDS is attributed the boundary field but nothing below it, so + // its tree exists and is EMPTY (zero coverage); unusedDS was never + // attributed any field and is absent entirely. + profileInfo := requireProvidesDataInfo(t, pd, "profileDS") + assert.Equal(t, map[*resolve.FetchInfo]*resolve.Object{ + accountInfo: { + Fields: []*resolve.Field{ + { + Name: []byte("user"), + Value: &resolve.Object{ + Nullable: true, + Path: []string{"user"}, + Fields: []*resolve.Field{ + { + Name: []byte("id"), + Value: &resolve.Scalar{ + Nullable: false, + Path: []string{"id"}, + }, + }, + }, + }, + }, + }, + }, + profileInfo: { + Fields: []*resolve.Field{}, + }, + }, pd) + }) +} + +// TestCacheProvidesDataVisitorDeterminism plans the same operation twice and +// asserts identical side-tables (compared by datasource, since *FetchInfo keys +// differ per run). +func TestCacheProvidesDataVisitorDeterminism(t *testing.T) { + op := ` + query { + user(id: "1") { + id + handle: username + profile { displayName } + } + }` + first := rekeyProvidesDataByDataSource(t, planCacheProvidesData(t, op)) + second := rekeyProvidesDataByDataSource(t, planCacheProvidesData(t, op)) + assert.Equal(t, first, second) +} + +func rekeyProvidesDataByDataSource(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object) map[string]*resolve.Object { + t.Helper() + out := make(map[string]*resolve.Object, len(pd)) + for info, obj := range pd { + require.NotContains(t, out, info.DataSourceID) + out[info.DataSourceID] = obj + } + return out +} + +func defaultProvidesDataPlanners() []PlannerConfiguration { + return []PlannerConfiguration{ + newTestProvidesDataPlanner("", &resolve.FetchInfo{DataSourceID: "accountDS"}), + newTestProvidesDataPlanner("user", &resolve.FetchInfo{DataSourceID: "profileDS"}), + } +} + +// newTestProvidesDataPlanner builds the minimal planner configuration the +// visitor dereferences: a fetch item (with the entity-boundary response path), +// an empty datasource configuration (for the federation lookup), and an empty +// paths configuration (for HasPathWithFieldRef). +func newTestProvidesDataPlanner(responsePath string, info *resolve.FetchInfo) PlannerConfiguration { + return &plannerConfiguration[any]{ + plannerPathsConfiguration: &plannerPathsConfiguration{}, + dataSourceConfiguration: &dataSourceConfiguration[any]{ + DataSourceMetadata: &DataSourceMetadata{}, + }, + objectFetchConfiguration: &objectFetchConfiguration{ + fetchItem: &resolve.FetchItem{ + ResponsePath: responsePath, + Fetch: &resolve.SingleFetch{Info: info}, + }, + }, + } +} + +// defaultProvidesDataRoutes emulates the main walk's field→planner attribution +// for the two-planner fixture: the root fetch resolves user+id, the entity +// fetch at "user" everything below it. +func defaultProvidesDataRoutes(path string, ref int, out map[int][]int) { + switch { + case path == "query.user": + out[ref] = []int{0, 1} + case path == "query.user.__typename": + out[ref] = []int{0, 1} + case path == "query.user.id": + out[ref] = []int{0} + case strings.HasPrefix(path, "query.user."): + out[ref] = []int{1} + } +} + +func planCacheProvidesData(t *testing.T, operation string) map[*resolve.FetchInfo]*resolve.Object { + t.Helper() + return planCacheProvidesDataWith(t, operation, defaultProvidesDataPlanners(), defaultProvidesDataRoutes) +} + +func planCacheProvidesDataWith(t *testing.T, operation string, planners []PlannerConfiguration, routes func(path string, ref int, out map[int][]int)) map[*resolve.FetchInfo]*resolve.Object { + t.Helper() + + definition := unsafeparser.ParseGraphqlDocumentString(cacheProvidesDataDefinition) + require.NoError(t, asttransform.MergeDefinitionWithBaseSchema(&definition)) + + op := unsafeparser.ParseGraphqlDocumentString(operation) + var report operationreport.Report + norm := astnormalization.NewNormalizer(true, true) + norm.NormalizeOperation(&op, &definition, &report) + require.False(t, report.HasErrors(), report.Error()) + + valid := astvalidation.DefaultOperationValidator() + valid.Validate(&op, &definition, &report) + require.False(t, report.HasErrors(), report.Error()) + + walker := astvisitor.NewWalkerWithID(48, "CacheProvidesDataVisitorTest") + visitor := &cacheProvidesDataVisitor{ + Walker: &walker, + operation: &op, + definition: &definition, + planners: planners, + fieldPlanners: collectFieldPlanners(&op, &definition, routes), + } + visitor.reset() + walker.RegisterEnterFieldVisitor(visitor) + walker.RegisterLeaveFieldVisitor(visitor) + walker.Walk(&op, &definition, &report) + require.False(t, report.HasErrors(), report.Error()) + + pre := &SynchronousResponsePlan{ + Response: &resolve.GraphQLResponse{}, + } + visitor.attachTo(pre) + return pre.Response.CacheProvidesData() +} + +func requireProvidesDataInfo(t *testing.T, pd map[*resolve.FetchInfo]*resolve.Object, dataSourceID string) *resolve.FetchInfo { + t.Helper() + + for info := range pd { + if info != nil && info.DataSourceID == dataSourceID { + return info + } + } + require.Failf(t, "missing provides data info", "data source %q in %#v", dataSourceID, pd) + return nil +} + +// collectFieldPlanners emulates the main walk's fieldPlanners output using the +// row's path-based routing. +func collectFieldPlanners(operation, definition *ast.Document, routes func(path string, ref int, out map[int][]int)) map[int][]int { + fieldPlanners := make(map[int][]int) + walker := astvisitor.NewWalkerWithID(48, "CacheProvidesDataFieldPlannerCollector") + collector := &cacheProvidesDataFieldPlannerCollector{ + walker: &walker, + operation: operation, + fieldPlanners: fieldPlanners, + routes: routes, + } + walker.RegisterEnterFieldVisitor(collector) + var report operationreport.Report + walker.Walk(operation, definition, &report) + return fieldPlanners +} + +const cacheProvidesDataDefinition = ` + type Query { + user(id: ID!): User + stats: Int + } + type User { + id: ID! + username: String + profile: Profile + friends(first: Int, after: String): [User] + pet: Pet + } + type Profile { + displayName: String + } + interface Pet { + name: String + } + type Dog implements Pet { + name: String + barks: Boolean + } + type Cat implements Pet { + name: String + meows: Boolean + } +` + +type cacheProvidesDataFieldPlannerCollector struct { + walker *astvisitor.Walker + operation *ast.Document + fieldPlanners map[int][]int + routes func(path string, ref int, out map[int][]int) +} + +func (c *cacheProvidesDataFieldPlannerCollector) EnterField(ref int) { + path := c.walker.Path.DotDelimitedString() + "." + c.operation.FieldAliasOrNameString(ref) + c.routes(cacheProvidesDataFragmentMarkerRegex.ReplaceAllString(path, ""), ref, c.fieldPlanners) +} diff --git a/v2/pkg/engine/plan/cache_provides_data_visitor_test.go b/v2/pkg/engine/plan/cache_provides_data_visitor_test.go new file mode 100644 index 0000000000..e751a31978 --- /dev/null +++ b/v2/pkg/engine/plan/cache_provides_data_visitor_test.go @@ -0,0 +1,110 @@ +package plan + +import ( + "encoding/json" + "fmt" + "maps" + "reflect" + "slices" + "testing" + + "github.com/kylelemons/godebug/pretty" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/astnormalization" + "github.com/wundergraph/graphql-go-tools/v2/pkg/asttransform" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astvalidation" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/internal/unsafeparser" + "github.com/wundergraph/graphql-go-tools/v2/pkg/operationreport" +) + +// TestCacheProvidesDataVisitorGating pins the planner no-op gate: the visitor +// is constructed only when a caching configuration is set. +func TestCacheProvidesDataVisitorGating(t *testing.T) { + t.Run("not constructed without a caching configuration", func(t *testing.T) { + p, err := NewPlanner(Configuration{ + DataSources: []DataSource{testDefinitionDSConfiguration}, + }) + require.NoError(t, err) + assert.Nil(t, p.cacheProvidesData) + }) + + t.Run("constructed with a caching configuration", func(t *testing.T) { + p, err := NewPlanner(Configuration{ + DataSources: []DataSource{testDefinitionDSConfiguration}, + Caching: &cacheconfig.CachingConfiguration{}, + }) + require.NoError(t, err) + assert.NotNil(t, p.cacheProvidesData) + }) +} + +// TestCacheProvidesDataSecondWalkKeepsPlanIdentical proves the second walk +// never re-runs the planning visitor and never rebuilds the plan: with the +// visitor enabled by an empty caching configuration, the produced plan is +// identical to the plan produced without any caching configuration. +func TestCacheProvidesDataSecondWalkKeepsPlanIdentical(t *testing.T) { + planOnce := func(t *testing.T, config Configuration) Plan { + t.Helper() + + def := unsafeparser.ParseGraphqlDocumentString(testDefinition) + op := unsafeparser.ParseGraphqlDocumentString(` + query SearchResults { + searchResults { + ... on Character { + name + } + ... on Vehicle { + length + } + } + } + `) + err := asttransform.MergeDefinitionWithBaseSchema(&def) + require.NoError(t, err) + var report operationreport.Report + norm := astnormalization.NewNormalizer(true, true) + norm.NormalizeOperation(&op, &def, &report) + valid := astvalidation.DefaultOperationValidator() + valid.Validate(&op, &def, &report) + require.False(t, report.HasErrors(), "unexpected report errors: %s", report.Error()) + + p, err := NewPlanner(config) + require.NoError(t, err) + result := p.Plan(&op, &def, "SearchResults", &report) + require.False(t, report.HasErrors(), "unexpected report errors: %s", report.Error()) + return result + } + + baseConfig := func() Configuration { + return Configuration{ + DisableResolveFieldPositions: true, + DisableIncludeInfo: true, + DataSources: []DataSource{testDefinitionDSConfiguration}, + } + } + + withoutCaching := planOnce(t, baseConfig()) + + cachingConfig := baseConfig() + cachingConfig.Caching = &cacheconfig.CachingConfiguration{} + withCaching := planOnce(t, cachingConfig) + + formatterConfig := map[reflect.Type]any{ + reflect.TypeFor[[]byte](): func(b []byte) string { return fmt.Sprintf(`"%s"`, string(b)) }, + reflect.TypeOf(map[string]struct{}{}): func(m map[string]struct{}) string { + keys := slices.Sorted(maps.Keys(m)) + keysPrinted, _ := json.Marshal(keys) + return string(keysPrinted) + }, + } + prettyCfg := &pretty.Config{ + Diffable: true, + IncludeUnexported: false, + Formatter: formatterConfig, + } + + assert.Equal(t, prettyCfg.Sprint(withoutCaching), prettyCfg.Sprint(withCaching)) +} diff --git a/v2/pkg/engine/plan/cacheconfig/cache_directive.go b/v2/pkg/engine/plan/cacheconfig/cache_directive.go new file mode 100644 index 0000000000..a5bb6131ec --- /dev/null +++ b/v2/pkg/engine/plan/cacheconfig/cache_directive.go @@ -0,0 +1,106 @@ +package cacheconfig + +import ( + "fmt" + "time" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/ast" + "github.com/wundergraph/graphql-go-tools/v2/pkg/astparser" +) + +// The SDL bridge of the per-type tier: composition carries the declaration +// through to the router, and the router turns the subgraph's SDL into the +// SubgraphCacheConfig.Types map with the reader below. Nothing here runs at +// plan or request time. + +// CacheDirectiveDefinition is the SDL the per-type declaration is written in — +// the directive and the enum its scope argument takes. Composition tooling +// references it so subgraph authors and this reader agree on one spelling. +const CacheDirectiveDefinition = `enum CacheScope { + PUBLIC + PRIVATE +} + +directive @cache(maxAge: Int!, scope: CacheScope = PUBLIC) on OBJECT` + +const ( + cacheDirectiveName = "cache" + maxAgeArgumentName = "maxAge" + scopeArgumentName = "scope" +) + +// ExtractTypeCacheConfigs reads the @cache declarations of ONE subgraph SDL +// into the per-type tier of the cascade, keyed by type name. Declarations are +// read off object type definitions and object type extensions alike, since a +// subgraph's contribution to a shared entity is usually an extension. +// +// The extraction never fails: a declaration whose arguments do not fit the +// directive is skipped and named in the returned warnings, which the caller +// surfaces to the operator; the remaining types are still extracted. maxAge is +// in SECONDS, and a type declared twice keeps its first declaration. +func ExtractTypeCacheConfigs(sdl string) (map[string]TypeCacheConfig, []string) { + types := make(map[string]TypeCacheConfig) + doc, report := astparser.ParseGraphqlDocumentString(sdl) + if report.HasErrors() { + return types, []string{"no @cache declaration was read, the SDL does not parse: " + report.Error()} + } + + var warnings []string + collect := func(typeName string, directiveRefs []int) { + declaration, warning, ok := readCacheDeclaration(&doc, typeName, directiveRefs) + if warning != "" { + warnings = append(warnings, warning) + } + if !ok { + return + } + if _, duplicate := types[typeName]; duplicate { + warnings = append(warnings, fmt.Sprintf("type %q: a repeated @cache declaration was ignored", typeName)) + return + } + types[typeName] = declaration + } + for ref := range doc.ObjectTypeDefinitions { + collect(doc.ObjectTypeDefinitionNameString(ref), doc.ObjectTypeDefinitions[ref].Directives.Refs) + } + for ref := range doc.ObjectTypeExtensions { + collect(doc.ObjectTypeExtensionNameString(ref), doc.ObjectTypeExtensions[ref].Directives.Refs) + } + return types, warnings +} + +// readCacheDeclaration reads one type's @cache declaration. ok=false means the +// type declares nothing usable, and the returned warning is non-empty exactly +// when a declaration WAS found and skipped — an unusable one never falls back +// to a guessed value, because guessing PUBLIC for an unreadable scope would +// publish data the schema meant to keep private. +func readCacheDeclaration(doc *ast.Document, typeName string, directiveRefs []int) (TypeCacheConfig, string, bool) { + directiveRef, exists := doc.DirectiveWithNameBytes(directiveRefs, []byte(cacheDirectiveName)) + if !exists { + return TypeCacheConfig{}, "", false + } + + maxAge, hasMaxAge := doc.DirectiveArgumentValueByName(directiveRef, []byte(maxAgeArgumentName)) + if !hasMaxAge || maxAge.Kind != ast.ValueKindInteger || !doc.IntValueValidInt32(maxAge.Ref) || doc.IntValueIsNegative(maxAge.Ref) { + return TypeCacheConfig{}, fmt.Sprintf("type %q: @cache was skipped, its maxAge is not a non-negative Int", typeName), false + } + declaration := TypeCacheConfig{MaxAge: time.Duration(doc.IntValueAsInt32(maxAge.Ref)) * time.Second} + + scope, hasScope := doc.DirectiveArgumentValueByName(directiveRef, []byte(scopeArgumentName)) + if !hasScope { + return declaration, "", true + } + if scope.Kind != ast.ValueKindEnum { + return TypeCacheConfig{}, fmt.Sprintf("type %q: @cache was skipped, its scope is not a CacheScope value", typeName), false + } + switch doc.EnumValueNameString(scope.Ref) { + case CacheScopePublic.String(): + // PUBLIC is the absence of privacy and the zero value already carries it. + case CacheScopePrivate.String(): + declaration.Scope = CacheScopePrivate + default: + return TypeCacheConfig{}, fmt.Sprintf("type %q: @cache was skipped, its scope %q is not a CacheScope value", + typeName, doc.EnumValueNameString(scope.Ref)), false + } + return declaration, "", true +} diff --git a/v2/pkg/engine/plan/cacheconfig/cache_directive_test.go b/v2/pkg/engine/plan/cacheconfig/cache_directive_test.go new file mode 100644 index 0000000000..0d137c89e9 --- /dev/null +++ b/v2/pkg/engine/plan/cacheconfig/cache_directive_test.go @@ -0,0 +1,242 @@ +package cacheconfig + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" +) + +// TestExtractTypeCacheConfigs pins the SDL bridge: which declarations become +// the per-type tier, which are skipped, and what the operator is told about the +// skipped ones. +func TestExtractTypeCacheConfigs(t *testing.T) { + rows := []struct { + name string + sdl string + wantTypes map[string]TypeCacheConfig + wantWarnings []string + }{ + { + name: "a well-formed declaration becomes the type's entry", + sdl: `type Product @key(fields: "upc") @cache(maxAge: 60) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Product": {MaxAge: time.Minute}, + }, + wantWarnings: nil, + }, + { + name: "an omitted scope declares the type public", + sdl: `type Product @cache(maxAge: 30) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second, Scope: CacheScopePublic}, + }, + wantWarnings: nil, + }, + { + name: "an explicit PUBLIC scope reads the same as omitting it", + sdl: `type Product @cache(maxAge: 30, scope: PUBLIC) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second, Scope: CacheScopePublic}, + }, + wantWarnings: nil, + }, + { + name: "a PRIVATE scope is carried through", + sdl: `type User @cache(maxAge: 10, scope: PRIVATE) { + id: ID! + }`, + wantTypes: map[string]TypeCacheConfig{ + "User": {MaxAge: 10 * time.Second, Scope: CacheScopePrivate}, + }, + wantWarnings: nil, + }, + { + name: "maxAge 0 declares the type uncacheable", + sdl: `type Product @cache(maxAge: 0) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Product": {MaxAge: 0}, + }, + wantWarnings: nil, + }, + { + name: "a declaration on a type EXTENSION is read too", + sdl: `extend type Product @key(fields: "upc") @cache(maxAge: 120) { + upc: String! @external + stock: Int! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Product": {MaxAge: 2 * time.Minute}, + }, + wantWarnings: nil, + }, + { + name: "every declared type of one SDL is extracted, entity or not", + sdl: `type Product @key(fields: "upc") @cache(maxAge: 60) { + upc: String! + warehouse: Warehouse! + } + type Warehouse @cache(maxAge: 3600, scope: PRIVATE) { + id: ID! + } + type Review { + id: ID! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Product": {MaxAge: time.Minute}, + "Warehouse": {MaxAge: time.Hour, Scope: CacheScopePrivate}, + }, + wantWarnings: nil, + }, + { + name: "an SDL without the directive declares nothing", + sdl: `type Product @key(fields: "upc") { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{}, + wantWarnings: nil, + }, + { + name: "a maxAge that is not an Int skips the declaration and warns", + sdl: `type Product @cache(maxAge: "60") { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{}, + wantWarnings: []string{ + `type "Product": @cache was skipped, its maxAge is not a non-negative Int`, + }, + }, + { + name: "a missing maxAge skips the declaration and warns", + sdl: `type Product @cache(scope: PRIVATE) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{}, + wantWarnings: []string{ + `type "Product": @cache was skipped, its maxAge is not a non-negative Int`, + }, + }, + { + name: "a negative maxAge skips the declaration and warns", + sdl: `type Product @cache(maxAge: -1) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{}, + wantWarnings: []string{ + `type "Product": @cache was skipped, its maxAge is not a non-negative Int`, + }, + }, + { + name: "an unknown scope skips the declaration instead of guessing PUBLIC", + sdl: `type Product @cache(maxAge: 60, scope: TENANT) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{}, + wantWarnings: []string{ + `type "Product": @cache was skipped, its scope "TENANT" is not a CacheScope value`, + }, + }, + { + name: "a scope that is not an enum value skips the declaration", + sdl: `type Product @cache(maxAge: 60, scope: 1) { + upc: String! + }`, + wantTypes: map[string]TypeCacheConfig{}, + wantWarnings: []string{ + `type "Product": @cache was skipped, its scope is not a CacheScope value`, + }, + }, + { + name: "one skipped declaration leaves the other types extracted", + sdl: `type Product @cache(maxAge: "60") { + upc: String! + } + type Warehouse @cache(maxAge: 90) { + id: ID! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Warehouse": {MaxAge: 90 * time.Second}, + }, + wantWarnings: []string{ + `type "Product": @cache was skipped, its maxAge is not a non-negative Int`, + }, + }, + { + name: "a type declared twice keeps its definition's declaration", + sdl: `type Product @cache(maxAge: 60) { + upc: String! + } + extend type Product @cache(maxAge: 3600) { + stock: Int! + }`, + wantTypes: map[string]TypeCacheConfig{ + "Product": {MaxAge: time.Minute}, + }, + wantWarnings: []string{ + `type "Product": a repeated @cache declaration was ignored`, + }, + }, + { + name: "an SDL that does not parse yields no declaration and one warning", + sdl: `type Product @cache(maxAge: 60) {`, + wantTypes: map[string]TypeCacheConfig{}, + wantWarnings: []string{ + "no @cache declaration was read, the SDL does not parse: external: unexpected token - got: EOF want one of: [], locations: [{Line:0 Column:0}], path: []", + }, + }, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + types, warnings := ExtractTypeCacheConfigs(row.sdl) + assert.Equal(t, row.wantTypes, types) + assert.Equal(t, row.wantWarnings, warnings) + }) + } + + t.Run("the extracted map feeds a subgraph's per-type tier directly", func(t *testing.T) { + types, warnings := ExtractTypeCacheConfigs(`type Product @key(fields: "upc") @cache(maxAge: 60) { + upc: String! + } + type User @key(fields: "id") @cache(maxAge: 10, scope: PRIVATE) { + id: ID! + }`) + assert.Equal(t, []string(nil), warnings) + + caching := &CachingConfiguration{ + Global: GlobalCacheConfig{DefaultTTL: time.Hour}, + Subgraphs: map[string]SubgraphCacheConfig{"products": {Types: types}}, + } + effective := caching.Resolve("products") + + product, ok := effective.Entities([]string{"Product"}) + assert.True(t, ok) + assert.Equal(t, EntityCacheConfig{TTL: time.Minute}, product) + + user, ok := effective.Entities([]string{"User"}) + assert.True(t, ok) + assert.Equal(t, EntityCacheConfig{ + TTL: 10 * time.Second, + Scope: CacheScopePrivate, + }, user) + }) +} + +// TestCacheDirectiveDefinition pins the SDL composition tooling references, so +// the spelling this reader accepts and the spelling schemas are validated +// against cannot drift apart. +func TestCacheDirectiveDefinition(t *testing.T) { + assert.Equal(t, `enum CacheScope { + PUBLIC + PRIVATE +} + +directive @cache(maxAge: Int!, scope: CacheScope = PUBLIC) on OBJECT`, CacheDirectiveDefinition) +} diff --git a/v2/pkg/engine/plan/cacheconfig/cacheconfig.go b/v2/pkg/engine/plan/cacheconfig/cacheconfig.go new file mode 100644 index 0000000000..5519422cc5 --- /dev/null +++ b/v2/pkg/engine/plan/cacheconfig/cacheconfig.go @@ -0,0 +1,287 @@ +// Package cacheconfig is the LEAF caching configuration package on the plan +// side: the declarative cascade an integrator supplies and its resolution into +// the effective per-subgraph configuration. It carries no cache logic and +// imports no engine packages, so plan and engine/cache can both depend on it +// without a cycle. The cascade is global defaults → per-subgraph overrides → +// per-TYPE declarations (plus per-root-field entries), most specific wins; +// enablement is DERIVED from the resolved values — a positive lifetime, +// NegativeCacheTTL, or shadow mode — with no explicit L1/L2 switches. +package cacheconfig + +import ( + "strconv" + "time" +) + +// CacheScope is the privacy scope of the entries a subgraph — or one of its +// root-field coordinates — writes. PUBLIC is the absence of privacy and needs +// no declaration, which is why the cascade has no global scope knob: privacy is +// always narrower than "everything". +type CacheScope uint8 + +const ( + // CacheScopePublic entries are shared by every requester. + CacheScopePublic CacheScope = iota + // CacheScopePrivate entries belong to ONE requester: their keys carry a + // partition segment derived from the request's identity, and without an + // identity they are not stored at all. + CacheScopePrivate +) + +// String renders the CacheScope for logs and test assertions. +func (s CacheScope) String() string { + switch s { + case CacheScopePublic: + return "PUBLIC" + case CacheScopePrivate: + return "PRIVATE" + default: + return "CacheScope(" + strconv.Itoa(int(s)) + ")" + } +} + +// CachingConfiguration is the whole declarative caching configuration: global +// defaults plus per-subgraph overrides keyed by DATASOURCE ID. Consumers read +// it through Resolve, never by walking the levels themselves. +type CachingConfiguration struct { + Global GlobalCacheConfig + Subgraphs map[string]SubgraphCacheConfig +} + +// GlobalCacheConfig holds the defaults every subgraph inherits unless it +// overrides them. +type GlobalCacheConfig struct { + // DefaultTTL is the lifetime of a cached entry; > 0 enables entity caching. + DefaultTTL time.Duration + // MaxTTL clamps any resolved TTL; 0 means no clamp. + MaxTTL time.Duration + // NegativeCacheTTL is the lifetime of the empty-entity sentinel; > 0 + // enables entity caching on its own. + NegativeCacheTTL time.Duration + // EnablePartialCacheLoad serves the covered items of a batch from the cache + // and fetches only the rest. + EnablePartialCacheLoad bool + // HashAnalyticsKeys hashes cache keys before they reach observers. + HashAnalyticsKeys bool + // ShadowMode reads the cache and compares, but never serves cached data. + ShadowMode bool + // EmitClientCacheControl emits an aggregated Cache-Control response header; + // nil means enabled. Like EmitCdnTags it describes ONE response rather than + // one subgraph, so it has no per-subgraph level and the runtime controller + // reads it off this level directly instead of through Resolve. + EmitClientCacheControl *bool + // EmitCdnTags accumulates the invalidation tags of the entries a response + // was built from, for a CDN that purges by them. Off by default: without + // such a CDN in front, the union is pure work. + EmitCdnTags bool +} + +// EmitsClientCacheControl reports whether the aggregated client cache answer is +// computed. It is the one knob that defaults to ON, so an unset value enables +// it. +func (g GlobalCacheConfig) EmitsClientCacheControl() bool { + return g.EmitClientCacheControl == nil || *g.EmitClientCacheControl +} + +// SubgraphCacheConfig overrides the global defaults for one subgraph. A nil +// pointer field means "not set at this level" and inherits the global value. +type SubgraphCacheConfig struct { + // Enabled set to false vetoes caching for the whole subgraph, whatever the + // resolved TTLs and whatever the root-field entries say. + Enabled *bool + DefaultTTL *time.Duration + MaxTTL *time.Duration + NegativeCacheTTL *time.Duration + EnablePartialCacheLoad *bool + ShadowMode *bool + // IncludeSubgraphHeaders keys entries by the forwarded subgraph header hash, + // so they never cross header variants. It has TWO roles, one per scope: on a + // PUBLIC subgraph it is a plain vary-by-headers knob (the hash leads the + // visible key prefix); on a PRIVATE one it is the fallback source of the + // requester identity the partition segment derives from. + IncludeSubgraphHeaders *bool + // Scope declares the subgraph's entries private, so their keys are + // partitioned per requester; nil (and PUBLIC) means shared entries. + Scope *CacheScope + // RootFields carries the per-coordinate entries; a root field is cached + // only when its exact coordinate has an entry here. + RootFields []RootFieldCacheConfig + // Types carries the per-type declarations keyed by ENTITY TYPE NAME — the + // narrowest tier of the cascade, composed from the subgraph's @cache + // directives (see ExtractTypeCacheConfigs). A type without an entry falls + // back to the subgraph level. + Types map[string]TypeCacheConfig +} + +// TypeCacheConfig is what ONE type declares about its own caching. Its PRESENCE +// in SubgraphCacheConfig.Types is the declaration itself, so no separate marker +// field is needed and a MaxAge of 0 carries meaning: the type is declared +// UNCACHEABLE and its fetches get no cache configuration at all — the negative +// sentinel included, whatever NegativeCacheTTL the subgraph resolves. Negative +// caching stays a subgraph-level knob in this tier; a type declares only its +// own lifetime and privacy. +type TypeCacheConfig struct { + // MaxAge is the type's static lifetime, replacing the subgraph DefaultTTL + // for its entities; 0 declares the type uncacheable. + MaxAge time.Duration + // Scope declares the type's entries private, so their keys carry a partition + // segment. It only ever ADDS privacy: a PUBLIC type inside a private + // subgraph stays private. + Scope CacheScope +} + +// RootFieldCacheConfig caches one query root-field coordinate of a subgraph. +type RootFieldCacheConfig struct { + TypeName, FieldName string + // TTL is the coordinate's own lifetime; 0 falls back to the subgraph's (and + // then the global) DefaultTTL. + TTL time.Duration + // ShadowMode, IncludeSubgraphHeaders and Scope add to the subgraph-level + // values; they cannot switch an enabled subgraph-level setting back off, so + // a coordinate can declare itself private inside a public subgraph but never + // the reverse. + ShadowMode bool + PartialBatchLoad bool + IncludeSubgraphHeaders bool + Scope CacheScope +} + +// EffectiveSubgraphConfig is the cascade resolved for ONE subgraph: concrete +// values only, no "unset" state left for consumers to interpret. +type EffectiveSubgraphConfig struct { + // Enabled is false when the subgraph vetoed caching; nothing of it is then + // cached, entities and root fields alike. + Enabled bool + DefaultTTL time.Duration + MaxTTL time.Duration + NegativeCacheTTL time.Duration + EnablePartialCacheLoad bool + HashAnalyticsKeys bool + ShadowMode bool + IncludeSubgraphHeaders bool + Scope CacheScope + RootFields []RootFieldCacheConfig + Types map[string]TypeCacheConfig +} + +// EntityCacheConfig is the static tier resolved for ONE entity fetch: the +// lifetime its entries take when the subgraph response carries no max-age, and +// the scope their keys derive under. +type EntityCacheConfig struct { + TTL time.Duration + Scope CacheScope +} + +// Entities resolves the static tier for an entity fetch over typeNames — the +// entity types ONE fetch can resolve, which is more than one when it batches +// representations of several concrete types under an abstract type. Each type +// contributes its own declaration where it has one and the subgraph DefaultTTL +// where it has none; the fetch takes the MINIMUM contributed lifetime and turns +// private as soon as one contribution is private, so privacy widens downwards +// and never up. +// +// ok=false when the subgraph vetoed caching, when a contributing type is +// declared uncacheable (MaxAge 0, a veto covering the negative sentinel too), +// or when nothing is left to enable — neither a positive resolved TTL nor the +// subgraph's NegativeCacheTTL. +func (c EffectiveSubgraphConfig) Entities(typeNames []string) (EntityCacheConfig, bool) { + if !c.Enabled || len(typeNames) == 0 { + return EntityCacheConfig{}, false + } + entity := EntityCacheConfig{Scope: c.Scope} + for i, typeName := range typeNames { + declaration, declared := c.Types[typeName] + if declared && declaration.MaxAge <= 0 { + return EntityCacheConfig{}, false + } + ttl := c.DefaultTTL + if declared { + ttl = declaration.MaxAge + if declaration.Scope == CacheScopePrivate { + entity.Scope = CacheScopePrivate + } + } + if i == 0 || ttl < entity.TTL { + entity.TTL = ttl + } + } + if entity.TTL <= 0 && c.NegativeCacheTTL <= 0 { + return EntityCacheConfig{}, false + } + return entity, true +} + +// RootField returns the effective entry for a root-field coordinate, with the +// TTL ladder applied (coordinate entry → subgraph DefaultTTL → global +// DefaultTTL) and the subgraph-level ShadowMode, IncludeSubgraphHeaders and +// Scope folded in. An entry for the exact coordinate must EXIST for the ladder +// to run — a root field is never cached by a bare DefaultTTL. ok=false when +// the subgraph is vetoed, the coordinate has no entry, or the entry enables +// nothing (root fields never carry L1, so that means no positive TTL and no +// shadow mode) — consumers must treat that as "not cached". +func (c EffectiveSubgraphConfig) RootField(typeName, fieldName string) (RootFieldCacheConfig, bool) { + if !c.Enabled { + return RootFieldCacheConfig{}, false + } + for _, entry := range c.RootFields { + if entry.TypeName != typeName || entry.FieldName != fieldName { + continue + } + if entry.TTL <= 0 { + // The coordinate entry declares PARTICIPATION; its TTL is optional and + // falls back to the subgraph's DefaultTTL, which Resolve has already + // filled from the global default when the subgraph set none. + entry.TTL = c.DefaultTTL + } + entry.ShadowMode = entry.ShadowMode || c.ShadowMode + entry.IncludeSubgraphHeaders = entry.IncludeSubgraphHeaders || c.IncludeSubgraphHeaders + if c.Scope == CacheScopePrivate { + entry.Scope = CacheScopePrivate + } + if entry.TTL <= 0 && !entry.ShadowMode { + return RootFieldCacheConfig{}, false + } + return entry, true + } + return RootFieldCacheConfig{}, false +} + +// Resolve walks the cascade for one datasource ID: global values, then the +// subgraph's overrides where it set any. A nil configuration and a vetoed +// subgraph both resolve to a disabled configuration. +func (c *CachingConfiguration) Resolve(subgraphID string) EffectiveSubgraphConfig { + if c == nil { + return EffectiveSubgraphConfig{} + } + effective := EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: c.Global.DefaultTTL, + MaxTTL: c.Global.MaxTTL, + NegativeCacheTTL: c.Global.NegativeCacheTTL, + EnablePartialCacheLoad: c.Global.EnablePartialCacheLoad, + HashAnalyticsKeys: c.Global.HashAnalyticsKeys, + ShadowMode: c.Global.ShadowMode, + } + subgraph, ok := c.Subgraphs[subgraphID] + if !ok { + return effective + } + applyOverride(&effective.Enabled, subgraph.Enabled) + applyOverride(&effective.DefaultTTL, subgraph.DefaultTTL) + applyOverride(&effective.MaxTTL, subgraph.MaxTTL) + applyOverride(&effective.NegativeCacheTTL, subgraph.NegativeCacheTTL) + applyOverride(&effective.EnablePartialCacheLoad, subgraph.EnablePartialCacheLoad) + applyOverride(&effective.ShadowMode, subgraph.ShadowMode) + applyOverride(&effective.IncludeSubgraphHeaders, subgraph.IncludeSubgraphHeaders) + applyOverride(&effective.Scope, subgraph.Scope) + effective.RootFields = subgraph.RootFields + effective.Types = subgraph.Types + return effective +} + +// applyOverride overwrites the effective value when the narrower level set one. +func applyOverride[T any](effective *T, override *T) { + if override != nil { + *effective = *override + } +} diff --git a/v2/pkg/engine/plan/cacheconfig/cacheconfig_test.go b/v2/pkg/engine/plan/cacheconfig/cacheconfig_test.go new file mode 100644 index 0000000000..de6892f2a8 --- /dev/null +++ b/v2/pkg/engine/plan/cacheconfig/cacheconfig_test.go @@ -0,0 +1,524 @@ +package cacheconfig + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" +) + +func ptr[T any](value T) *T { + return &value +} + +// TestResolve pins the cascade resolution per field: with every global knob +// set, a subgraph inherits all of them unless it overrides that one knob. +func TestResolve(t *testing.T) { + global := GlobalCacheConfig{ + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + } + + t.Run("a subgraph without an entry inherits the global level", func(t *testing.T) { + caching := &CachingConfiguration{ + Global: global, + Subgraphs: map[string]SubgraphCacheConfig{"products": {DefaultTTL: ptr(time.Second)}}, + } + assert.Equal(t, EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, caching.Resolve("reviews")) + }) + + rows := []struct { + name string + subgraph SubgraphCacheConfig + want EffectiveSubgraphConfig + }{ + { + name: "no override inherits every global value", + subgraph: SubgraphCacheConfig{}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "Enabled false vetoes the subgraph", + subgraph: SubgraphCacheConfig{Enabled: ptr(false)}, + want: EffectiveSubgraphConfig{ + Enabled: false, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "Enabled true keeps the subgraph enabled", + subgraph: SubgraphCacheConfig{Enabled: ptr(true)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "DefaultTTL override wins", + subgraph: SubgraphCacheConfig{DefaultTTL: ptr(10 * time.Second)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: 10 * time.Second, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "DefaultTTL override to zero disables entity caching for the subgraph", + subgraph: SubgraphCacheConfig{DefaultTTL: ptr(time.Duration(0)), NegativeCacheTTL: ptr(time.Duration(0))}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: 0, + MaxTTL: time.Hour, + NegativeCacheTTL: 0, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "MaxTTL override wins", + subgraph: SubgraphCacheConfig{MaxTTL: ptr(2 * time.Minute)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: 2 * time.Minute, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "NegativeCacheTTL override wins", + subgraph: SubgraphCacheConfig{NegativeCacheTTL: ptr(time.Second)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "EnablePartialCacheLoad override wins", + subgraph: SubgraphCacheConfig{EnablePartialCacheLoad: ptr(false)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: false, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "ShadowMode override wins", + subgraph: SubgraphCacheConfig{ShadowMode: ptr(false)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: false, + IncludeSubgraphHeaders: false, + }, + }, + { + name: "IncludeSubgraphHeaders has no global level and is set per subgraph", + subgraph: SubgraphCacheConfig{IncludeSubgraphHeaders: ptr(true)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: true, + }, + }, + { + name: "Scope has no global level and is declared per subgraph", + subgraph: SubgraphCacheConfig{Scope: ptr(CacheScopePrivate)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + Scope: CacheScopePrivate, + }, + }, + { + // PUBLIC is the absence of privacy, so declaring it explicitly must + // resolve exactly like declaring nothing. + name: "an explicit PUBLIC scope resolves like no declaration", + subgraph: SubgraphCacheConfig{Scope: ptr(CacheScopePublic)}, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + Scope: CacheScopePublic, + }, + }, + { + name: "root field entries are carried through unchanged", + subgraph: SubgraphCacheConfig{ + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: 30 * time.Second}, + }, + }, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: 30 * time.Second}, + }, + }, + }, + { + name: "type declarations are carried through unchanged", + subgraph: SubgraphCacheConfig{ + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + "User": {MaxAge: 10 * time.Second, Scope: CacheScopePrivate}, + }, + }, + want: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + MaxTTL: time.Hour, + NegativeCacheTTL: 5 * time.Second, + EnablePartialCacheLoad: true, + HashAnalyticsKeys: true, + ShadowMode: true, + IncludeSubgraphHeaders: false, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + "User": {MaxAge: 10 * time.Second, Scope: CacheScopePrivate}, + }, + }, + }, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + caching := &CachingConfiguration{ + Global: global, + Subgraphs: map[string]SubgraphCacheConfig{"products": row.subgraph}, + } + assert.Equal(t, row.want, caching.Resolve("products")) + }) + } + + t.Run("an empty global level resolves to no caching at all", func(t *testing.T) { + caching := &CachingConfiguration{} + assert.Equal(t, EffectiveSubgraphConfig{ + Enabled: true, + }, caching.Resolve("products")) + }) + + t.Run("EmitClientCacheControl defaults to true and is switched off globally", func(t *testing.T) { + assert.Equal(t, true, GlobalCacheConfig{}.EmitsClientCacheControl()) + assert.Equal(t, false, GlobalCacheConfig{EmitClientCacheControl: ptr(false)}.EmitsClientCacheControl()) + assert.Equal(t, true, GlobalCacheConfig{EmitClientCacheControl: ptr(true)}.EmitsClientCacheControl()) + }) + + t.Run("a nil configuration resolves to a disabled subgraph", func(t *testing.T) { + var caching *CachingConfiguration + assert.Equal(t, EffectiveSubgraphConfig{}, caching.Resolve("products")) + }) +} + +// TestRootField pins the per-coordinate lookup: exact coordinate match, the +// subgraph-level fold, the inert-entry miss, and the veto. +func TestRootField(t *testing.T) { + t.Run("the exact coordinate entry is returned", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: time.Minute, PartialBatchLoad: true}, + {TypeName: "Query", FieldName: "topReviews", TTL: time.Second}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + TTL: time.Minute, + PartialBatchLoad: true, + }, entry) + }) + + t.Run("both coordinates must match", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: time.Minute}, + }, + } + entry, ok := effective.RootField("Query", "topReviews") + assert.False(t, ok) + assert.Equal(t, RootFieldCacheConfig{}, entry) + + entry, ok = effective.RootField("Mutation", "topProducts") + assert.False(t, ok) + assert.Equal(t, RootFieldCacheConfig{}, entry) + }) + + t.Run("subgraph shadow mode and header inclusion fold into the entry", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + ShadowMode: true, + IncludeSubgraphHeaders: true, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: time.Minute}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + TTL: time.Minute, + ShadowMode: true, + IncludeSubgraphHeaders: true, + }, entry) + }) + + t.Run("a private subgraph makes every one of its root fields private", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + Scope: CacheScopePrivate, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: time.Minute}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + TTL: time.Minute, + Scope: CacheScopePrivate, + }, entry) + }) + + t.Run("a private coordinate stays private inside a public subgraph", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + Scope: CacheScopePublic, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "me", TTL: time.Minute, Scope: CacheScopePrivate}, + {TypeName: "Query", FieldName: "topProducts", TTL: time.Minute}, + }, + } + private, ok := effective.RootField("Query", "me") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "me", + TTL: time.Minute, + Scope: CacheScopePrivate, + }, private) + + // Its sibling is untouched: privacy never widens beyond what declared it. + public, ok := effective.RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + TTL: time.Minute, + Scope: CacheScopePublic, + }, public) + }) + + t.Run("subgraph shadow mode makes a TTL-less entry effective", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + ShadowMode: true, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts"}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + ShadowMode: true, + }, entry) + }) + + t.Run("an entry enabling nothing is a miss", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", PartialBatchLoad: true}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.False(t, ok) + assert.Equal(t, RootFieldCacheConfig{}, entry) + }) + + t.Run("the subgraph veto hides every entry", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: false, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: time.Minute}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.False(t, ok) + assert.Equal(t, RootFieldCacheConfig{}, entry) + }) + + t.Run("a subgraph without entries has no cached root fields", func(t *testing.T) { + effective := EffectiveSubgraphConfig{Enabled: true, DefaultTTL: time.Minute} + entry, ok := effective.RootField("Query", "topProducts") + assert.False(t, ok) + assert.Equal(t, RootFieldCacheConfig{}, entry) + }) + + t.Run("a TTL-less entry falls back to the subgraph DefaultTTL", func(t *testing.T) { + // Resolve has already folded the global default into DefaultTTL, so this + // one field carries the whole "subgraph, else global" half of the ladder. + effective := EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: 5 * time.Minute, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", PartialBatchLoad: true}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + TTL: 5 * time.Minute, + PartialBatchLoad: true, + }, entry) + }) + + t.Run("the coordinate TTL wins over the subgraph DefaultTTL", func(t *testing.T) { + effective := EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: 5 * time.Minute, + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts", TTL: 30 * time.Second}, + }, + } + entry, ok := effective.RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + TTL: 30 * time.Second, + }, entry) + }) + + t.Run("the whole ladder from the raw cascade: global default, no narrower TTL anywhere", func(t *testing.T) { + caching := &CachingConfiguration{ + Global: GlobalCacheConfig{DefaultTTL: 2 * time.Minute}, + Subgraphs: map[string]SubgraphCacheConfig{ + "products": { + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts"}, + }, + }, + }, + } + entry, ok := caching.Resolve("products").RootField("Query", "topProducts") + assert.True(t, ok) + assert.Equal(t, RootFieldCacheConfig{ + TypeName: "Query", + FieldName: "topProducts", + TTL: 2 * time.Minute, + }, entry) + }) + + t.Run("a bare DefaultTTL never caches a coordinate without an entry", func(t *testing.T) { + caching := &CachingConfiguration{ + Global: GlobalCacheConfig{DefaultTTL: 2 * time.Minute}, + Subgraphs: map[string]SubgraphCacheConfig{ + "products": { + RootFields: []RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "topProducts"}, + }, + }, + }, + } + entry, ok := caching.Resolve("products").RootField("Query", "topReviews") + assert.False(t, ok) + assert.Equal(t, RootFieldCacheConfig{}, entry) + }) +} + +func TestCacheScopeString(t *testing.T) { + assert.Equal(t, "PUBLIC", CacheScopePublic.String()) + assert.Equal(t, "PRIVATE", CacheScopePrivate.String()) + assert.Equal(t, "CacheScope(7)", CacheScope(7).String()) +} diff --git a/v2/pkg/engine/plan/cacheconfig/type_cache_test.go b/v2/pkg/engine/plan/cacheconfig/type_cache_test.go new file mode 100644 index 0000000000..999c92c877 --- /dev/null +++ b/v2/pkg/engine/plan/cacheconfig/type_cache_test.go @@ -0,0 +1,285 @@ +package cacheconfig + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" +) + +// TestEntities pins the entity static tier: which lifetime an entity fetch +// resolves once per-type declarations join the cascade, when a declaration +// vetoes caching outright, and how privacy folds together. +func TestEntities(t *testing.T) { + rows := []struct { + name string + effective EffectiveSubgraphConfig + typeNames []string + want EntityCacheConfig + wantOK bool + }{ + { + name: "an undeclared type falls through to the subgraph DefaultTTL", + effective: EffectiveSubgraphConfig{Enabled: true, DefaultTTL: time.Minute}, + typeNames: []string{"Product"}, + want: EntityCacheConfig{TTL: time.Minute}, + wantOK: true, + }, + { + name: "no lifetime anywhere caches nothing", + effective: EffectiveSubgraphConfig{Enabled: true}, + typeNames: []string{"Product"}, + want: EntityCacheConfig{}, + wantOK: false, + }, + { + name: "the NegativeCacheTTL alone still enables an undeclared type", + effective: EffectiveSubgraphConfig{Enabled: true, NegativeCacheTTL: 5 * time.Second}, + typeNames: []string{"Product"}, + want: EntityCacheConfig{TTL: 0}, + wantOK: true, + }, + { + name: "shadow mode alone does not enable entity caching", + effective: EffectiveSubgraphConfig{Enabled: true, ShadowMode: true}, + typeNames: []string{"Product"}, + want: EntityCacheConfig{}, + wantOK: false, + }, + { + name: "the subgraph veto beats a positive declaration", + effective: EffectiveSubgraphConfig{ + Enabled: false, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + }, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{}, + wantOK: false, + }, + { + name: "a declared type beats the subgraph DefaultTTL", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + }, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{TTL: 30 * time.Second}, + wantOK: true, + }, + { + name: "a declaration LONGER than the subgraph default wins too", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: time.Hour}, + }, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{TTL: time.Hour}, + wantOK: true, + }, + { + name: "another type's declaration leaves this one on the subgraph default", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "User": {MaxAge: 30 * time.Second}, + }, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{TTL: time.Minute}, + wantOK: true, + }, + { + name: "a type declared uncacheable gets no configuration at all", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + NegativeCacheTTL: 5 * time.Second, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 0}, + }, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{}, + wantOK: false, + }, + { + name: "a private subgraph makes an undeclared type private", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Scope: CacheScopePrivate, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{ + TTL: time.Minute, + Scope: CacheScopePrivate, + }, + wantOK: true, + }, + { + name: "a PUBLIC declaration cannot make a private subgraph public", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Scope: CacheScopePrivate, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second, Scope: CacheScopePublic}, + }, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{ + TTL: 30 * time.Second, + Scope: CacheScopePrivate, + }, + wantOK: true, + }, + { + name: "a PRIVATE declaration makes one type of a public subgraph private", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second, Scope: CacheScopePrivate}, + }, + }, + typeNames: []string{"Product"}, + want: EntityCacheConfig{ + TTL: 30 * time.Second, + Scope: CacheScopePrivate, + }, + wantOK: true, + }, + { + name: "a sibling type of the same subgraph stays public", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second, Scope: CacheScopePrivate}, + }, + }, + typeNames: []string{"User"}, + want: EntityCacheConfig{TTL: time.Minute}, + wantOK: true, + }, + { + name: "a batch over several declared types takes the shortest lifetime", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + "Brand": {MaxAge: 10 * time.Second}, + }, + }, + typeNames: []string{ + "Product", + "Brand", + }, + want: EntityCacheConfig{TTL: 10 * time.Second}, + wantOK: true, + }, + { + name: "an undeclared concrete type contributes the subgraph default", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: 5 * time.Second, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + }, + }, + typeNames: []string{ + "Product", + "Brand", + }, + want: EntityCacheConfig{TTL: 5 * time.Second}, + wantOK: true, + }, + { + name: "one private declaration turns the whole batch private", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + "Brand": {MaxAge: 45 * time.Second, Scope: CacheScopePrivate}, + }, + }, + typeNames: []string{ + "Product", + "Brand", + }, + want: EntityCacheConfig{ + TTL: 30 * time.Second, + Scope: CacheScopePrivate, + }, + wantOK: true, + }, + { + name: "one uncacheable declaration vetoes the whole batch", + effective: EffectiveSubgraphConfig{ + Enabled: true, + DefaultTTL: time.Minute, + NegativeCacheTTL: 5 * time.Second, + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 30 * time.Second}, + "Brand": {MaxAge: 0}, + }, + }, + typeNames: []string{ + "Product", + "Brand", + }, + want: EntityCacheConfig{}, + wantOK: false, + }, + { + name: "a fetch without any type name resolves nothing", + effective: EffectiveSubgraphConfig{Enabled: true, DefaultTTL: time.Minute}, + typeNames: nil, + want: EntityCacheConfig{}, + wantOK: false, + }, + } + for _, row := range rows { + t.Run(row.name, func(t *testing.T) { + entity, ok := row.effective.Entities(row.typeNames) + assert.Equal(t, row.wantOK, ok) + assert.Equal(t, row.want, entity) + }) + } + + t.Run("the whole cascade from the raw configuration: a declaration overrides the global default", func(t *testing.T) { + caching := &CachingConfiguration{ + Global: GlobalCacheConfig{DefaultTTL: 2 * time.Minute}, + Subgraphs: map[string]SubgraphCacheConfig{ + "products": { + Types: map[string]TypeCacheConfig{ + "Product": {MaxAge: 15 * time.Second, Scope: CacheScopePrivate}, + }, + }, + }, + } + entity, ok := caching.Resolve("products").Entities([]string{"Product"}) + assert.True(t, ok) + assert.Equal(t, EntityCacheConfig{ + TTL: 15 * time.Second, + Scope: CacheScopePrivate, + }, entity) + + // Its sibling keeps the global default and stays public. + entity, ok = caching.Resolve("products").Entities([]string{"User"}) + assert.True(t, ok) + assert.Equal(t, EntityCacheConfig{TTL: 2 * time.Minute}, entity) + }) +} diff --git a/v2/pkg/engine/plan/configuration.go b/v2/pkg/engine/plan/configuration.go index 509f8ff27b..06602a10ea 100644 --- a/v2/pkg/engine/plan/configuration.go +++ b/v2/pkg/engine/plan/configuration.go @@ -3,6 +3,7 @@ package plan import ( "github.com/jensneuse/abstractlogger" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" ) @@ -14,6 +15,13 @@ type Configuration struct { Fields FieldConfigurations Types TypeConfigurations EntityInterfaceNames []string + + // Caching holds the declarative caching configuration cascade, its + // per-subgraph overrides keyed by datasource ID. A non-nil value gates the + // cacheProvidesDataVisitor second walk; the same value feeds + // postprocess.EnableCaching. Populated by the engine Configuration's + // SetCaching — the engine entry point is the only public producer. + Caching *cacheconfig.CachingConfiguration // DisableResolveFieldPositions should be set to true for testing purposes // This setting removes position information from all fields // In production, this should be set to false so that error messages are easier to understand diff --git a/v2/pkg/engine/plan/path_builder_visitor.go b/v2/pkg/engine/plan/path_builder_visitor.go index 22a890a6e7..890a0e09f2 100644 --- a/v2/pkg/engine/plan/path_builder_visitor.go +++ b/v2/pkg/engine/plan/path_builder_visitor.go @@ -123,6 +123,10 @@ type objectFetchConfiguration struct { rootFields []resolve.GraphCoordinate operationType ast.OperationType deferID int + // isolatedRootField marks a planner created by the per-root-field cache + // isolation gate (root_field_isolation.go): it owns exactly ONE query root + // field and never accepts another top-level operation field. + isolatedRootField bool } type currentFieldInfo struct { @@ -655,6 +659,7 @@ func (c *pathBuilderVisitor) handlePlanningField(field *currentFieldInfo) { } isMutationRoot := c.isMutationRoot(field.currentPath) + isolateRootField := shouldIsolateRootField(c.plannerConfiguration.Caching, field, field.parentPath) var ( plannerIdx int @@ -662,9 +667,14 @@ func (c *pathBuilderVisitor) handlePlanningField(field *currentFieldInfo) { ) // mutation root fields should always be planned on a new planner - // because mutations must be executed sequentially - if isMutationRoot { + // because mutations must be executed sequentially; + // cache-isolated query root fields get their own planner so each keeps + // its own cache policy and L2 key (root_field_isolation.go) + if isMutationRoot || isolateRootField { plannerIdx, planned = c.addNewPlanner(field, isMutationRoot) + if planned && isolateRootField { + c.planners[plannerIdx].ObjectFetchConfiguration().isolatedRootField = true + } } else { plannerIdx, planned = c.planWithExistingPlanners(field) if !planned { @@ -836,6 +846,15 @@ func (c *pathBuilderVisitor) planWithExistingPlanners(field *currentFieldInfo) ( continue } + if plannerConfig.ObjectFetchConfiguration().isolatedRootField && c.isParentPathIsRootOperationPath(field.parentPath) { + // an isolated planner owns exactly one root field: never fold + // another TOP-LEVEL operation field into it. The guard keys off + // the parent path, NOT IsRootNode — entity types are root nodes + // too, and an IsRootNode guard would tear the isolated field's + // own nested entity subtree apart. + continue + } + if plannerConfig.DeferID() != 0 && field.deferID == 0 { // do not plan a non-deferred field on a deferred planner continue diff --git a/v2/pkg/engine/plan/planner.go b/v2/pkg/engine/plan/planner.go index ecef6836b1..65feaca4ce 100644 --- a/v2/pkg/engine/plan/planner.go +++ b/v2/pkg/engine/plan/planner.go @@ -20,6 +20,10 @@ type Planner struct { planningVisitor *Visitor costVisitor *CostVisitor + // cacheProvidesData is the caching provides-data walk; constructed only + // when caching is configured (nil otherwise, the planner no-op gate). + cacheProvidesData *cacheProvidesDataVisitor + nodeSelectionBuilder *NodeSelectionBuilder planningPathBuilder *PathBuilder @@ -66,10 +70,16 @@ func NewPlanner(config Configuration) (*Planner, error) { planningVisitor := NewVisitor(&planningWalker) planningVisitor.disableResolveFieldPositions = config.DisableResolveFieldPositions + var cacheProvidesData *cacheProvidesDataVisitor + if config.Caching != nil { + cacheProvidesData = &cacheProvidesDataVisitor{} + } + p := &Planner{ config: config, planningWalker: &planningWalker, planningVisitor: planningVisitor, + cacheProvidesData: cacheProvidesData, prepareOperationWalker: &prepareOperationWalker, deferInfoCollector: deferInfoCollector, } @@ -224,6 +234,17 @@ func (p *Planner) Plan(operation, definition *ast.Document, operationName string p.planningVisitor.plan.SetCostCalculator(costCalc) } + // The caching provides-data walk: a gated SECOND, filter-free walk on a + // DEDICATED walker, after all planning walks are done — the planning + // walker keeps its visitors and filter, and fieldPlanners is complete here. + if p.cacheProvidesData != nil { + p.cacheProvidesData.walk(operation, definition, p.config, plannersConfigurations, p.planningVisitor.fieldPlanners, report) + if report.HasErrors() { + return + } + p.cacheProvidesData.attachTo(p.planningVisitor.plan) + } + // Step 5. Plan is handed over to postprocess.Processor. It checks fetch dependencies and // orders them into parallel or sequential groups and builds a fetch tree. return p.planningVisitor.plan diff --git a/v2/pkg/engine/datasource/graphql_datasource/representation_variable.go b/v2/pkg/engine/plan/representationvariable/representation_variable.go similarity index 81% rename from v2/pkg/engine/datasource/graphql_datasource/representation_variable.go rename to v2/pkg/engine/plan/representationvariable/representation_variable.go index 808e1ec833..38013aa6c3 100644 --- a/v2/pkg/engine/datasource/graphql_datasource/representation_variable.go +++ b/v2/pkg/engine/plan/representationvariable/representation_variable.go @@ -1,4 +1,9 @@ -package graphql_datasource +// Package representationvariable builds the resolve-node representation of a federation +// entity key: it turns one `@key` selection set into a federation-pointer-free +// *resolve.Object used to render the `representations` variable for entity fetches. +// It is shared between the graphql datasource planner and cache-key construction, +// so that both derive representation nodes from a single walker and can never skew. +package representationvariable import ( "bytes" @@ -18,7 +23,16 @@ type objectFields struct { // TODO: add support for remapping path -func buildRepresentationVariableNode(definition *ast.Document, cfg plan.FederationFieldConfiguration, federationCfg plan.FederationMetaData) (*resolve.Object, error) { +// BuildRepresentationVariableNode turns one `@key` selection set (cfg.SelectionSet on +// cfg.TypeName) into a federation-pointer-free *resolve.Object, with the +// interfaceObject/entityInterface `__typename` remap from federationCfg baked in. +// +// markKeyFields records on every emitted field whether it came from a `@key` +// set (an empty cfg.FieldName; a `@requires` set names the field carrying the +// directive), so the merged node still tells the two apart. It is a CACHING +// artifact and therefore opt-in: with caching off, plans carry no marks and +// stay byte-identical. +func BuildRepresentationVariableNode(definition *ast.Document, cfg plan.FederationFieldConfiguration, federationCfg plan.FederationMetaData, markKeyFields bool) (*resolve.Object, error) { key, report := plan.RequiredFieldsFragment(cfg.TypeName, cfg.SelectionSet, false) if report.HasErrors() { return nil, report @@ -48,6 +62,7 @@ func buildRepresentationVariableNode(definition *ast.Document, cfg plan.Federati entityInterfaceTypeName: entityInterfaceTypeName, addOnType: true, addTypeName: true, + keyFields: markKeyFields && cfg.FieldName == "", remapPaths: cfg.RemappedPaths, Walker: walker, } @@ -62,7 +77,12 @@ func buildRepresentationVariableNode(definition *ast.Document, cfg plan.Federati return visitor.rootObject, nil } +// mergeFields deep-merges one field selected by two representation sources. A +// field belonging to the `@key` set in EITHER source is a key field in the +// merged node, so the flag is OR-ed rather than taken from the left. func mergeFields(left, right *resolve.Field) *resolve.Field { + left.CacheEntityKeyField = left.CacheEntityKeyField || right.CacheEntityKeyField + switch left.Value.NodeKind() { case resolve.NodeKindObject: left.Value = mergeObjects(left.Value, right.Value) @@ -120,7 +140,10 @@ func fieldsHasField(fields []*resolve.Field, field *resolve.Field) (int, bool) { return -1, false } -func mergeRepresentationVariableNodes(objects []*resolve.Object) *resolve.Object { +// MergeRepresentationVariableNodes merges the per-key representation objects into the +// single nullable object the graphql datasource renders as its `representations` +// variable; fields with the same name and type conditions are deep-merged. +func MergeRepresentationVariableNodes(objects []*resolve.Object) *resolve.Object { fieldCount := 0 for _, object := range objects { fieldCount += len(object.Fields) @@ -144,6 +167,8 @@ func mergeRepresentationVariableNodes(objects []*resolve.Object) *resolve.Object } } +// representationVariableVisitor walks one `@key` selection set against the schema +// definition and assembles the corresponding resolve-node tree. type representationVariableVisitor struct { *astvisitor.Walker @@ -158,7 +183,11 @@ type representationVariableVisitor struct { addOnType bool addTypeName bool - remapPaths map[string]string + // keyFields marks the walked selection set as the entity's `@key` set, which + // every emitted field records so the merged node keeps key and `@requires` + // provenance apart. + keyFields bool + remapPaths map[string]string } func (v *representationVariableVisitor) EnterDocument(key, definition *ast.Document) { @@ -219,9 +248,10 @@ func (v *representationVariableVisitor) EnterField(ref int) { } currentField := &resolve.Field{ - Name: fieldName, - Value: v.resolveFieldValue(ref, fieldDefinitionType, true, []string{fieldPath}), - OnTypeNames: v.resolveOnTypeNames(ref), + Name: fieldName, + Value: v.resolveFieldValue(ref, fieldDefinitionType, true, []string{fieldPath}), + OnTypeNames: v.resolveOnTypeNames(ref), + CacheEntityKeyField: v.keyFields, } if v.addOnType && v.currentFields[len(v.currentFields)-1].isRoot { diff --git a/v2/pkg/engine/datasource/graphql_datasource/representation_variable_test.go b/v2/pkg/engine/plan/representationvariable/representation_variable_test.go similarity index 71% rename from v2/pkg/engine/datasource/graphql_datasource/representation_variable_test.go rename to v2/pkg/engine/plan/representationvariable/representation_variable_test.go index e26d1a3d82..ed5674da84 100644 --- a/v2/pkg/engine/datasource/graphql_datasource/representation_variable_test.go +++ b/v2/pkg/engine/plan/representationvariable/representation_variable_test.go @@ -1,4 +1,4 @@ -package graphql_datasource +package representationvariable import ( "testing" @@ -18,7 +18,10 @@ func TestBuildRepresentationVariableNode(t *testing.T) { SelectionSet: keyStr, } - node, err := buildRepresentationVariableNode(&definition, cfg, federationMeta) + // Without caching configured the planner asks for no @key marking, so + // these rows also pin that the node is what it was before the marking + // existed. + node, err := BuildRepresentationVariableNode(&definition, cfg, federationMeta, false) require.NoError(t, err) require.Equal(t, expectedNode, node) @@ -27,7 +30,7 @@ func TestBuildRepresentationVariableNode(t *testing.T) { t.Run("simple", func(t *testing.T) { runTest(t, ` scalar String - + type User { id: String! name: String! @@ -66,7 +69,7 @@ func TestBuildRepresentationVariableNode(t *testing.T) { t.Run("with interface object", func(t *testing.T) { runTest(t, ` scalar String - + type User { id: String! name: String! @@ -110,12 +113,58 @@ func TestBuildRepresentationVariableNode(t *testing.T) { }) }) + t.Run("with entity interface", func(t *testing.T) { + runTest(t, ` + scalar String + + type User { + id: String! + name: String! + } + `, + `id name`, + plan.FederationMetaData{ + EntityInterfaces: []plan.EntityInterfaceConfiguration{ + { + InterfaceTypeName: "Account", + ConcreteTypeNames: []string{"User", "Admin"}, + }, + }, + }, + &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{ + Path: []string{"__typename"}, + }, + OnTypeNames: [][]byte{[]byte("User"), []byte("Account")}, + }, + { + Name: []byte("id"), + Value: &resolve.String{ + Path: []string{"id"}, + }, + OnTypeNames: [][]byte{[]byte("User"), []byte("Account")}, + }, + { + Name: []byte("name"), + Value: &resolve.String{ + Path: []string{"name"}, + }, + OnTypeNames: [][]byte{[]byte("User"), []byte("Account")}, + }, + }, + }) + }) + t.Run("deeply nested", func(t *testing.T) { runTest(t, ` scalar String scalar Int scalar Float - + type User { id: String! name: String! @@ -130,7 +179,7 @@ func TestBuildRepresentationVariableNode(t *testing.T) { type Address { zip: Float! } - + `, `id name account { accoundID address(home: true) { zip } }`, plan.FederationMetaData{}, @@ -313,7 +362,7 @@ func TestMergeRepresentationVariableNodes(t *testing.T) { }, } - merged := mergeRepresentationVariableNodes([]*resolve.Object{userRepresentation, adminRepresentation}) + merged := MergeRepresentationVariableNodes([]*resolve.Object{userRepresentation, adminRepresentation}) require.Equal(t, expected, merged) }) @@ -362,7 +411,7 @@ func TestMergeRepresentationVariableNodes(t *testing.T) { }, } - merged := mergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) + merged := MergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) require.Equal(t, expected, merged) }) @@ -413,7 +462,7 @@ func TestMergeRepresentationVariableNodes(t *testing.T) { }, } - merged := mergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) + merged := MergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) require.Equal(t, expected, merged) }) @@ -567,7 +616,7 @@ func TestMergeRepresentationVariableNodes(t *testing.T) { }, } - merged := mergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) + merged := MergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) require.Equal(t, expected, merged) }) @@ -793,7 +842,216 @@ func TestMergeRepresentationVariableNodes(t *testing.T) { }, } - merged := mergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) + merged := MergeRepresentationVariableNodes([]*resolve.Object{userKeyRepresentation, userRequiresRepresentation}) require.Equal(t, expected, merged) }) } + +// TestBuildRepresentationVariableNodeKeyFieldMarking pins the @key provenance +// the cache reads off the merged representation node: which fields carry it, +// which do not, that a field selected by BOTH a @key and a @requires set stays +// a key field, and that the marking is opt-in. +func TestBuildRepresentationVariableNodeKeyFieldMarking(t *testing.T) { + definitionStr := ` + scalar String + scalar Int + + type User { + id: String! + name: String! + account: Account! + } + + type Account { + accountID: Int! + balance: Int! + } + ` + + build := func(t *testing.T, cfg plan.FederationFieldConfiguration, markKeyFields bool) *resolve.Object { + t.Helper() + definition, _ := astparser.ParseGraphqlDocumentString(definitionStr) + node, err := BuildRepresentationVariableNode(&definition, cfg, plan.FederationMetaData{}, markKeyFields) + require.NoError(t, err) + return node + } + + t.Run("a @key set marks every field it emits, at every depth", func(t *testing.T) { + node := build(t, plan.FederationFieldConfiguration{ + TypeName: "User", + SelectionSet: `id account { accountID }`, + }, true) + require.Equal(t, &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + // __typename is never part of the hashed key subset, so the + // builder leaves it unmarked. + Name: []byte("__typename"), + Value: &resolve.String{ + Path: []string{"__typename"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("id"), + Value: &resolve.String{ + Path: []string{"id"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + CacheEntityKeyField: true, + }, + { + Name: []byte("account"), + Value: &resolve.Object{ + Path: []string{"account"}, + Fields: []*resolve.Field{ + { + Name: []byte("accountID"), + Value: &resolve.Integer{ + Path: []string{"accountID"}, + }, + CacheEntityKeyField: true, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("User")}, + CacheEntityKeyField: true, + }, + }, + }, node) + }) + + t.Run("a @requires set marks nothing: it names the field carrying the directive", func(t *testing.T) { + node := build(t, plan.FederationFieldConfiguration{ + TypeName: "User", + FieldName: "shippingEstimate", + SelectionSet: `name`, + }, true) + require.Equal(t, &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{ + Path: []string{"__typename"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("name"), + Value: &resolve.String{ + Path: []string{"name"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, node) + }) + + t.Run("merging keeps a field the @key set claims, whichever side declared it first", func(t *testing.T) { + key := build(t, plan.FederationFieldConfiguration{ + TypeName: "User", + SelectionSet: `id account { accountID }`, + }, true) + requires := build(t, plan.FederationFieldConfiguration{ + TypeName: "User", + FieldName: "shippingEstimate", + SelectionSet: `id name account { balance }`, + }, true) + + // @requires FIRST, so the merge has to OR the flag onto a field it + // already collected unmarked. + require.Equal(t, &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{ + Path: []string{"__typename"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("id"), + Value: &resolve.String{ + Path: []string{"id"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + CacheEntityKeyField: true, + }, + { + Name: []byte("name"), + Value: &resolve.String{ + Path: []string{"name"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("account"), + Value: &resolve.Object{ + Path: []string{"account"}, + Fields: []*resolve.Field{ + { + Name: []byte("balance"), + Value: &resolve.Integer{ + Path: []string{"balance"}, + }, + }, + { + Name: []byte("accountID"), + Value: &resolve.Integer{ + Path: []string{"accountID"}, + }, + CacheEntityKeyField: true, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("User")}, + CacheEntityKeyField: true, + }, + }, + }, MergeRepresentationVariableNodes([]*resolve.Object{requires, key})) + }) + + t.Run("without the marking a @key set emits exactly the unmarked node", func(t *testing.T) { + node := build(t, plan.FederationFieldConfiguration{ + TypeName: "User", + SelectionSet: `id account { accountID }`, + }, false) + require.Equal(t, &resolve.Object{ + Nullable: true, + Fields: []*resolve.Field{ + { + Name: []byte("__typename"), + Value: &resolve.String{ + Path: []string{"__typename"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("id"), + Value: &resolve.String{ + Path: []string{"id"}, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + { + Name: []byte("account"), + Value: &resolve.Object{ + Path: []string{"account"}, + Fields: []*resolve.Field{ + { + Name: []byte("accountID"), + Value: &resolve.Integer{ + Path: []string{"accountID"}, + }, + }, + }, + }, + OnTypeNames: [][]byte{[]byte("User")}, + }, + }, + }, node) + }) +} diff --git a/v2/pkg/engine/plan/root_field_isolation.go b/v2/pkg/engine/plan/root_field_isolation.go new file mode 100644 index 0000000000..ad8aad5a77 --- /dev/null +++ b/v2/pkg/engine/plan/root_field_isolation.go @@ -0,0 +1,24 @@ +package plan + +import ( + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// shouldIsolateRootField is the per-root-field cache isolation gate: a QUERY +// root field whose exact (typeName, fieldName) coordinate resolves a cached +// root-field entry gets its OWN planner during path building, so sibling root +// fields with different (or no) cache settings never merge into one fetch and +// each cached field keeps its own L2 key and TTL. With caching off the +// isolation branches are dead and plans stay byte-identical; mutation roots +// are already one-planner-per-root. The decision reads the caching +// configuration ONLY — never FederationMetaData. +func shouldIsolateRootField(caching *cacheconfig.CachingConfiguration, field *currentFieldInfo, parentPath string) bool { + if caching == nil { + return false + } + if parentPath != "query" { + return false + } + _, ok := caching.Resolve(field.ds.Id()).RootField(field.typeName, field.fieldName) + return ok +} diff --git a/v2/pkg/engine/plan/root_field_isolation_test.go b/v2/pkg/engine/plan/root_field_isolation_test.go new file mode 100644 index 0000000000..e0966e2708 --- /dev/null +++ b/v2/pkg/engine/plan/root_field_isolation_test.go @@ -0,0 +1,120 @@ +package plan + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" +) + +// TestShouldIsolateRootField pins the gate predicate directly: every condition +// that must hold, and every one that must decline. The plan-level behavior +// (two parallel fetches, the entity-root-node trap, defer composition, the +// byte-identical no-op) is pinned over REAL plans in +// execution/cachingtesting/isolation_e2e_test.go. +func TestShouldIsolateRootField(t *testing.T) { + caching := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", TTL: time.Minute}, + }, + }, + }, + } + productsField := ¤tFieldInfo{ + typeName: "Query", + fieldName: "products", + ds: &dataSourceConfiguration[any]{id: "products"}, + } + + t.Run("cached query root field isolates", func(t *testing.T) { + assert.True(t, shouldIsolateRootField(caching, productsField, "query")) + }) + + t.Run("no caching configured never isolates (the provable no-op)", func(t *testing.T) { + assert.False(t, shouldIsolateRootField(nil, productsField, "query")) + }) + + t.Run("only DIRECT children of the QUERY root isolate", func(t *testing.T) { + assert.False(t, shouldIsolateRootField(caching, productsField, "mutation")) + assert.False(t, shouldIsolateRootField(caching, productsField, "subscription")) + assert.False(t, shouldIsolateRootField(caching, productsField, "query.products")) + }) + + t.Run("a subgraph without root field entries never isolates", func(t *testing.T) { + otherDS := ¤tFieldInfo{ + typeName: "Query", + fieldName: "products", + ds: &dataSourceConfiguration[any]{id: "reviews"}, + } + assert.False(t, shouldIsolateRootField(caching, otherDS, "query")) + }) + + t.Run("a coordinate without an entry never isolates", func(t *testing.T) { + uncachedField := ¤tFieldInfo{ + typeName: "Query", + fieldName: "promotions", + ds: &dataSourceConfiguration[any]{id: "products"}, + } + assert.False(t, shouldIsolateRootField(caching, uncachedField, "query")) + }) + + t.Run("a vetoed subgraph never isolates", func(t *testing.T) { + vetoed := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + Enabled: ptr(false), + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", TTL: time.Minute}, + }, + }, + }, + } + assert.False(t, shouldIsolateRootField(vetoed, productsField, "query")) + }) + + t.Run("an INERT entry (no TTL, no shadow) never isolates", func(t *testing.T) { + // The configurator's all-flags-false safety net drops such an entry's + // config entirely; isolating for it would change the plan without + // enabling any caching. + inert := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products"}, + }, + }, + }, + } + assert.False(t, shouldIsolateRootField(inert, productsField, "query")) + }) + + t.Run("a shadow-only entry isolates", func(t *testing.T) { + shadow := &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": { + RootFields: []cacheconfig.RootFieldCacheConfig{ + {TypeName: "Query", FieldName: "products", ShadowMode: true}, + }, + }, + }, + } + assert.True(t, shouldIsolateRootField(shadow, productsField, "query")) + }) + + t.Run("a global DefaultTTL alone never isolates a root field", func(t *testing.T) { + // Entity caching is subgraph-wide, root-field caching is per coordinate: + // without an entry there is nothing to isolate for. + globalOnly := &cacheconfig.CachingConfiguration{ + Global: cacheconfig.GlobalCacheConfig{DefaultTTL: time.Minute}, + } + assert.False(t, shouldIsolateRootField(globalOnly, productsField, "query")) + }) +} + +func ptr[T any](value T) *T { + return &value +} diff --git a/v2/pkg/engine/postprocess/postprocess.go b/v2/pkg/engine/postprocess/postprocess.go index d57fb27232..91d4789aed 100644 --- a/v2/pkg/engine/postprocess/postprocess.go +++ b/v2/pkg/engine/postprocess/postprocess.go @@ -3,7 +3,9 @@ package postprocess import ( "slices" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/cache" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" ) @@ -25,6 +27,9 @@ type Processor struct { responseTreeProcessors *ResponseTreeProcessors extractDeferFetches *extractDeferFetches buildDeferTree *buildDeferTree + // caching orchestrates the caching passes; with no EnableCaching option it + // is a guaranteed no-op (the planner no-op gate lives inside it). + caching *cache.Configurator } type FetchTreeProcessors struct { @@ -71,6 +76,7 @@ type processorOptions struct { collectDataSourceInfo bool disableExtractDeferFetches bool disableBuildDeferTree bool + caching *cacheconfig.CachingConfiguration } type ProcessorOption func(*processorOptions) @@ -136,6 +142,15 @@ func DisableBuildDeferTree() ProcessorOption { } } +// EnableCaching wires the caching postprocess passes. It is an INTERNAL +// detail: the public entry point is the engine Configuration's SetCaching, +// which passes the caching configuration through. +func EnableCaching(caching *cacheconfig.CachingConfiguration) ProcessorOption { + return func(o *processorOptions) { + o.caching = caching + } +} + func NewProcessor(options ...ProcessorOption) *Processor { opts := &processorOptions{} for _, o := range options { @@ -180,6 +195,7 @@ func NewProcessor(options ...ProcessorOption) *Processor { buildDeferTree: &buildDeferTree{ disable: opts.disableBuildDeferTree, }, + caching: cache.NewConfigurator(opts.caching), } } @@ -194,6 +210,8 @@ func (p *Processor) Process(pre plan.Plan) { // initialize the fetch tree p.createFetchTree(t.Response) p.fetchTreeProcessors.processFlatFetchTree(t.Response.Fetches) + // caching passes run on the flat tree, after the concrete fetch types exist + p.caching.ConfigureCaching(t.Response, nil, t.Response.Fetches) p.fetchTreeProcessors.organizeFetchTree(t.Response.Fetches) case *plan.DeferResponsePlan: @@ -214,6 +232,13 @@ func (p *Processor) Process(pre plan.Plan) { // order defer fetches into parallel/sequence groups p.buildDeferTree.Process(t.Response) + + // caching passes run AFTER the defer tree is built: the group trees + // and their ancestry come from the AUTHORITATIVE DeferTree the + // resolver executes (a parent group resolves fully before its + // children), not from a parallel derivation + cachingTrees, cachingTreeParents := collectDeferCachingTrees(t.Response) + p.caching.ConfigureCaching(t.Response.Response, cachingTreeParents, cachingTrees...) // emptily defers, as they are now ordered in a separate tree t.Response.Defers = nil @@ -223,6 +248,7 @@ func (p *Processor) Process(pre plan.Plan) { p.appendTriggerToFetchTree(t.Response) p.fetchTreeProcessors.processFlatFetchTree(t.Response.Response.Fetches) + p.caching.ConfigureCaching(t.Response.Response, nil, t.Response.Response.Fetches) // resolve input template for the root query in the subscription trigger p.fetchTreeProcessors.resolveInputTemplates.ProcessTrigger(&t.Response.Trigger) @@ -231,6 +257,64 @@ func (p *Processor) Process(pre plan.Plan) { } } +// collectDeferCachingTrees gathers the fetch trees the caching passes run +// over — the initial tree plus every defer group — with each tree's parent +// index for the L1 narrowing pass's ancestry ordering. Both come from the +// BUILT DeferTree: a Sequence node's first child is the parent group, the +// remaining children are its nested groups, Parallel children share their +// enclosing parent, and a group without fetches contributes no tree (its +// children attach to the nearest fetch-bearing ancestor). Falls back to the +// flat Defers list, all parented to the initial tree, when the defer tree was +// not built. +func collectDeferCachingTrees(response *resolve.GraphQLDeferResponse) ([]*resolve.FetchTreeNode, []int) { + trees := []*resolve.FetchTreeNode{response.Response.Fetches} + parents := []int{-1} + if response.DeferTree == nil { + for _, group := range response.Defers { + if group.Fetches == nil { + continue + } + trees = append(trees, group.Fetches) + parents = append(parents, 0) + } + return trees, parents + } + var walk func(node *resolve.DeferTreeNode, parentIndex int) + walk = func(node *resolve.DeferTreeNode, parentIndex int) { + if node == nil { + return + } + switch node.Kind { + case resolve.DeferTreeNodeKindSingle: + if node.Item != nil && node.Item.Fetches != nil { + trees = append(trees, node.Item.Fetches) + parents = append(parents, parentIndex) + } + case resolve.DeferTreeNodeKindSequence: + if len(node.ChildNodes) == 0 { + return + } + // buildDeferTree shape: ChildNodes[0] is the parent group, the + // rest is its child subtree. + before := len(trees) + walk(node.ChildNodes[0], parentIndex) + childParent := parentIndex + if len(trees) == before+1 { + childParent = before + } + for _, child := range node.ChildNodes[1:] { + walk(child, childParent) + } + case resolve.DeferTreeNodeKindParallel: + for _, child := range node.ChildNodes { + walk(child, parentIndex) + } + } + } + walk(response.DeferTree, 0) + return trees, parents +} + // createFetchTree creates an initial fetch tree from the raw fetches in the GraphQL response. // The initial fetch tree is a node of sequence fetch kind, with a flat list of fetches as children. func (p *Processor) createFetchTree(res *resolve.GraphQLResponse) { diff --git a/v2/pkg/engine/postprocess/postprocess_caching_test.go b/v2/pkg/engine/postprocess/postprocess_caching_test.go new file mode 100644 index 0000000000..e982b423ca --- /dev/null +++ b/v2/pkg/engine/postprocess/postprocess_caching_test.go @@ -0,0 +1,302 @@ +package postprocess + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/plan/cacheconfig" + "github.com/wundergraph/graphql-go-tools/v2/pkg/engine/resolve" +) + +// The postprocess-level caching suite: the FULL Processor pipeline over +// synthetic plans, pinning that EnableCaching configures fetches in the sync +// arm AND in the defer arm (where ConfigureCaching runs AFTER buildDeferTree +// and derives group ancestry from the built DeferTree), plus direct rows for +// collectDeferCachingTrees. The plan-driven end-to-end equivalents live in +// execution/cachingtesting. + +func cachingTestConfiguration(ttl time.Duration) *cacheconfig.CachingConfiguration { + return &cacheconfig.CachingConfiguration{ + Subgraphs: map[string]cacheconfig.SubgraphCacheConfig{ + "products": {DefaultTTL: &ttl}, + }, + } +} + +// productTree builds an entity coverage tree with the given scalar fields. +func productTree(fields ...string) *resolve.Object { + obj := &resolve.Object{} + for _, name := range fields { + obj.Fields = append(obj.Fields, &resolve.Field{ + Name: []byte(name), + Value: &resolve.Scalar{Nullable: true, Path: []string{name}}, + }) + } + return obj +} + +// entityRawFetch builds a raw SingleFetch that createConcreteSingleFetchTypes +// converts into an EntityFetch (RequiresEntityFetch + a representations +// variable segment), attributed to the products datasource. +func entityRawFetch(fetchID, deferID int) (*resolve.FetchItem, *resolve.FetchInfo) { + info := &resolve.FetchInfo{ + DataSourceID: "products", + DataSourceName: "products", + RootFields: []resolve.GraphCoordinate{{TypeName: "Product"}}, + } + fetch := &resolve.SingleFetch{ + FetchDependencies: resolve.FetchDependencies{FetchID: fetchID, DeferID: deferID}, + FetchConfiguration: resolve.FetchConfiguration{ + RequiresEntityFetch: true, + Input: `{"method":"POST","url":"http://products","body":{"query":"...","variables":{"representations":[$$0$$]}}}`, + Variables: resolve.Variables{ + resolve.NewResolvableObjectVariable(&resolve.Object{ + Fields: []*resolve.Field{ + {Name: []byte("__typename"), Value: &resolve.String{Path: []string{"__typename"}}}, + {Name: []byte("upc"), Value: &resolve.String{Path: []string{"upc"}}}, + }, + }), + }, + }, + Info: info, + } + return &resolve.FetchItem{Fetch: fetch, ResponsePath: "products"}, info +} + +func minimalData() *resolve.Object { + return &resolve.Object{ + Fields: []*resolve.Field{ + {Name: []byte("products"), Value: &resolve.String{Path: []string{"products"}, Nullable: true}}, + }, + } +} + +// findCacheConfigs walks a fetch tree collecting each fetch's cache config +// string (nil-safe), depth-first. +func findCacheConfigs(node *resolve.FetchTreeNode) []string { + if node == nil { + return nil + } + var out []string + if node.Item != nil && node.Item.Fetch != nil { + out = append(out, node.Item.Fetch.CacheConfig().String()) + } + for _, child := range node.ChildNodes { + out = append(out, findCacheConfigs(child)...) + } + return out +} + +// TestPostprocessCachingSyncArm: the full pipeline configures an entity fetch +// in a synchronous plan; a lone entity fetch has no L1 partner, so the +// narrowing pass turns L1 off and L2 remains. +func TestPostprocessCachingSyncArm(t *testing.T) { + entityItem, info := entityRawFetch(2, 0) + response := &resolve.GraphQLResponse{ + RawFetches: []*resolve.FetchItem{ + {Fetch: &resolve.SingleFetch{FetchDependencies: resolve.FetchDependencies{FetchID: 1}}}, + entityItem, + }, + Data: minimalData(), + } + response.SetCacheProvidesData(map[*resolve.FetchInfo]*resolve.Object{ + info: productTree("name", "price"), + }) + + processor := NewProcessor(EnableCaching(cachingTestConfiguration(time.Minute))) + processor.Process(&plan.SynchronousResponsePlan{Response: response}) + + assert.Equal(t, []string{ + ``, + `{l1:false l2:true subgraph:products ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:Entity type:Product field: representation:true providesData:true populateL2OnMutation:false mutationTTL:0s}`, + }, findCacheConfigs(response.Fetches)) +} + +// TestPostprocessCachingNoOp: a processor with EnableCaching over no +// configuration at all, and over an EMPTY configuration, both produce a plan +// equal to a plain processor's — the no-op gate at the postprocess level. +func TestPostprocessCachingNoOp(t *testing.T) { + build := func() *plan.SynchronousResponsePlan { + entityItem, _ := entityRawFetch(2, 0) + return &plan.SynchronousResponsePlan{Response: &resolve.GraphQLResponse{ + RawFetches: []*resolve.FetchItem{ + {Fetch: &resolve.SingleFetch{FetchDependencies: resolve.FetchDependencies{FetchID: 1}}}, + entityItem, + }, + Data: minimalData(), + }} + } + + plain := build() + NewProcessor().Process(plain) + + withoutCaching := build() + NewProcessor(EnableCaching(nil)).Process(withoutCaching) + + assert.Equal(t, plain, withoutCaching) + assert.Equal(t, []string{``, ``}, findCacheConfigs(withoutCaching.Response.Fetches)) + + withEmptyCaching := build() + NewProcessor(EnableCaching(&cacheconfig.CachingConfiguration{})).Process(withEmptyCaching) + + assert.Equal(t, plain, withEmptyCaching) + assert.Equal(t, []string{``, ``}, findCacheConfigs(withEmptyCaching.Response.Fetches)) +} + +// deferCachingPlan builds a DeferResponsePlan with one uncached initial fetch +// and two ENTITY fetches in defer groups 1 and 2, whose coverage trees form a +// provider/consumer pair ({name,price} ⊇ {name}). The descriptors decide +// whether group 2 is NESTED under group 1 or its SIBLING. +func deferCachingPlan(t *testing.T, descriptors map[int]resolve.DeferDescriptor) (*plan.DeferResponsePlan, *resolve.GraphQLDeferResponse) { + t.Helper() + providerItem, providerInfo := entityRawFetch(2, 1) + consumerItem, consumerInfo := entityRawFetch(3, 2) + response := &resolve.GraphQLResponse{ + RawFetches: []*resolve.FetchItem{ + {Fetch: &resolve.SingleFetch{FetchDependencies: resolve.FetchDependencies{FetchID: 1}}}, + providerItem, + consumerItem, + }, + Data: minimalData(), + } + response.SetCacheProvidesData(map[*resolve.FetchInfo]*resolve.Object{ + providerInfo: productTree("name", "price"), + consumerInfo: productTree("name"), + }) + deferResponse := &resolve.GraphQLDeferResponse{ + Response: response, + DeferDescriptors: descriptors, + } + return &plan.DeferResponsePlan{Response: deferResponse}, deferResponse +} + +// deferGroupCacheConfigs walks the BUILT DeferTree in execution order and +// returns each group's fetch cache configs. +func deferGroupCacheConfigs(node *resolve.DeferTreeNode) []string { + if node == nil { + return nil + } + var out []string + if node.Item != nil { + out = append(out, findCacheConfigs(node.Item.Fetches)...) + } + for _, child := range node.ChildNodes { + out = append(out, deferGroupCacheConfigs(child)...) + } + return out +} + +// TestPostprocessCachingDeferAncestry pins the reason ConfigureCaching runs +// AFTER buildDeferTree: the L1 narrowing pass orders defer groups by the +// AUTHORITATIVE tree's ancestry. The same provider/consumer pair keeps L1 when +// the consumer's group is NESTED under the provider's (a parent group resolves +// fully before its children) and loses it when the groups are unordered +// SIBLINGS; L2 stays on either way, so the configs survive. +func TestPostprocessCachingDeferAncestry(t *testing.T) { + t.Run("nested groups keep the L1 pair", func(t *testing.T) { + l1AndL2Config := `{l1:true l2:true subgraph:products ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:Entity type:Product field: representation:true providesData:true populateL2OnMutation:false mutationTTL:0s}` + deferPlan, deferResponse := deferCachingPlan(t, map[int]resolve.DeferDescriptor{ + 1: {ID: 1, ParentID: 0}, + 2: {ID: 2, ParentID: 1}, + }) + NewProcessor(EnableCaching(cachingTestConfiguration(time.Minute))).Process(deferPlan) + require.NotNil(t, deferResponse.DeferTree) + assert.Equal(t, []string{l1AndL2Config, l1AndL2Config}, deferGroupCacheConfigs(deferResponse.DeferTree)) + }) + + t.Run("sibling groups are unordered: L1 narrowed off, L2 kept", func(t *testing.T) { + l2OnlyConfig := `{l1:false l2:true subgraph:products ttl:1m0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:Entity type:Product field: representation:true providesData:true populateL2OnMutation:false mutationTTL:0s}` + deferPlan, deferResponse := deferCachingPlan(t, map[int]resolve.DeferDescriptor{ + 1: {ID: 1, ParentID: 0}, + 2: {ID: 2, ParentID: 0}, + }) + NewProcessor(EnableCaching(cachingTestConfiguration(time.Minute))).Process(deferPlan) + require.NotNil(t, deferResponse.DeferTree) + assert.Equal(t, []string{l2OnlyConfig, l2OnlyConfig}, deferGroupCacheConfigs(deferResponse.DeferTree)) + }) +} + +// TestCollectDeferCachingTrees pins the tree/ancestry collection directly +// over BUILT defer trees (and the not-built fallback). +func TestCollectDeferCachingTrees(t *testing.T) { + groupFetches := func(response *resolve.GraphQLDeferResponse) map[int]*resolve.FetchTreeNode { + out := make(map[int]*resolve.FetchTreeNode) + var walk func(node *resolve.DeferTreeNode) + walk = func(node *resolve.DeferTreeNode) { + if node == nil { + return + } + if node.Item != nil { + out[node.Item.DeferID] = node.Item.Fetches + } + for _, child := range node.ChildNodes { + walk(child) + } + } + walk(response.DeferTree) + return out + } + + t.Run("single root group", func(t *testing.T) { + p := makeDeferPlan(map[int]resolve.DeferDescriptor{1: {ID: 1, ParentID: 0}}, 1) + runBuildDeferTree(p) + trees, parents := collectDeferCachingTrees(p.Response) + byID := groupFetches(p.Response) + assert.Equal(t, []*resolve.FetchTreeNode{p.Response.Response.Fetches, byID[1]}, trees) + assert.Equal(t, []int{-1, 0}, parents) + }) + + t.Run("two siblings share the initial parent", func(t *testing.T) { + p := makeDeferPlan(map[int]resolve.DeferDescriptor{ + 1: {ID: 1, ParentID: 0}, + 2: {ID: 2, ParentID: 0}, + }, 1, 2) + runBuildDeferTree(p) + _, parents := collectDeferCachingTrees(p.Response) + assert.Equal(t, []int{-1, 0, 0}, parents) + }) + + t.Run("a nested chain parents each group to its enclosing group", func(t *testing.T) { + p := makeDeferPlan(map[int]resolve.DeferDescriptor{ + 1: {ID: 1, ParentID: 0}, + 3: {ID: 3, ParentID: 1}, + 5: {ID: 5, ParentID: 3}, + }, 1, 3, 5) + runBuildDeferTree(p) + trees, parents := collectDeferCachingTrees(p.Response) + byID := groupFetches(p.Response) + assert.Equal(t, []*resolve.FetchTreeNode{p.Response.Response.Fetches, byID[1], byID[3], byID[5]}, trees) + assert.Equal(t, []int{-1, 0, 1, 2}, parents) + }) + + t.Run("without a built tree every group falls back to the initial parent", func(t *testing.T) { + p := makeDeferPlan(map[int]resolve.DeferDescriptor{ + 1: {ID: 1, ParentID: 0}, + 3: {ID: 3, ParentID: 1}, + }, 1, 3) + // extract only — DeferTree stays nil (the disableBuildDeferTree shape). + ext := &extractDeferFetches{} + ext.Process(p) + require.Nil(t, p.Response.DeferTree) + _, parents := collectDeferCachingTrees(p.Response) + assert.Equal(t, []int{-1, 0, 0}, parents) + }) + + t.Run("a fetchless parent group attaches its children to the nearest ancestor", func(t *testing.T) { + child := &resolve.DeferFetchGroup{DeferID: 2, Fetches: resolve.Sequence()} + response := &resolve.GraphQLDeferResponse{ + Response: &resolve.GraphQLResponse{Fetches: resolve.Sequence()}, + DeferTree: resolve.DeferSequence( + resolve.DeferSingle(&resolve.DeferFetchGroup{DeferID: 1, Fetches: nil}), + resolve.DeferSingle(child), + ), + } + trees, parents := collectDeferCachingTrees(response) + assert.Equal(t, []*resolve.FetchTreeNode{response.Response.Fetches, child.Fetches}, trees) + assert.Equal(t, []int{-1, 0}, parents) + }) +} diff --git a/v2/pkg/engine/resolve/batch_input_assembly.go b/v2/pkg/engine/resolve/batch_input_assembly.go new file mode 100644 index 0000000000..2886d052d5 --- /dev/null +++ b/v2/pkg/engine/resolve/batch_input_assembly.go @@ -0,0 +1,48 @@ +package resolve + +import ( + "github.com/pkg/errors" + + arena "github.com/wundergraph/go-arena" +) + +// batchInputAssembly holds the pre-rendered pieces of a batch entity input: +// header/separator/footer plus one segment per UNIQUE representation (bucket +// order). All slices live on the fetch's batchEntityTools arena, which stays +// alive until resolveSingle returns. +// +// It exists to defer the final input rendering until AFTER the cache decision: +// assemble runs exactly once, producing an input that contains only the +// representations the network fetch still needs (no parse-back filtering). +type batchInputAssembly struct { + header []byte + separator []byte + footer []byte + segments [][]byte + undefinedVariables []string +} + +// assemble renders the FINAL batch input into a fresh buffer on a: the header, +// the kept segments separator-joined (nil keep = all; a segment index beyond +// keep's length is dropped), the footer — then the undefined-variables +// post-processing on the final bytes. +func (b *batchInputAssembly) assemble(a arena.Arena, keep []bool) ([]byte, error) { + buf := arena.NewArenaBuffer(a) + _, _ = buf.Write(b.header) + wroteItem := false + for i, segment := range b.segments { + if keep != nil && (i >= len(keep) || !keep[i]) { + continue + } + if wroteItem { + _, _ = buf.Write(b.separator) + } + _, _ = buf.Write(segment) + wroteItem = true + } + _, _ = buf.Write(b.footer) + if err := SetInputUndefinedVariables(buf, b.undefinedVariables); err != nil { + return nil, errors.WithStack(err) + } + return buf.Bytes(), nil +} diff --git a/v2/pkg/engine/resolve/batch_input_assembly_test.go b/v2/pkg/engine/resolve/batch_input_assembly_test.go new file mode 100644 index 0000000000..1bbc4b640b --- /dev/null +++ b/v2/pkg/engine/resolve/batch_input_assembly_test.go @@ -0,0 +1,92 @@ +package resolve + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + arena "github.com/wundergraph/go-arena" +) + +// TestBatchInputAssembly pins the exact final input bytes for every keep +// shape: the header/footer bracket, the separator-joining of kept segments, +// and the undefined-variables post-processing on the final bytes. +func TestBatchInputAssembly(t *testing.T) { + newAssembly := func() *batchInputAssembly { + return &batchInputAssembly{ + header: []byte(`{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[`), + separator: []byte(`,`), + footer: []byte(`]}}}`), + segments: [][]byte{ + []byte(`{"__typename":"Product","upc":"1"}`), + []byte(`{"__typename":"Product","upc":"2"}`), + []byte(`{"__typename":"Product","upc":"3"}`), + }, + } + } + assemble := func(t *testing.T, b *batchInputAssembly, keep []bool) string { + t.Helper() + out, err := b.assemble(arena.NewMonotonicArena(), keep) + require.NoError(t, err) + return string(out) + } + + t.Run("nil keep sends every segment", func(t *testing.T) { + assert.Equal(t, + `{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"2"},{"__typename":"Product","upc":"3"}]}}}`, + assemble(t, newAssembly(), nil)) + }) + + t.Run("all-true keep equals nil keep", func(t *testing.T) { + assert.Equal(t, + assemble(t, newAssembly(), nil), + assemble(t, newAssembly(), []bool{true, true, true})) + }) + + t.Run("dropping the middle segment keeps exactly one separator", func(t *testing.T) { + assert.Equal(t, + `{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[{"__typename":"Product","upc":"1"},{"__typename":"Product","upc":"3"}]}}}`, + assemble(t, newAssembly(), []bool{true, false, true})) + }) + + t.Run("keeping only the first segment writes no separator", func(t *testing.T) { + assert.Equal(t, + `{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[{"__typename":"Product","upc":"1"}]}}}`, + assemble(t, newAssembly(), []bool{true, false, false})) + }) + + t.Run("keeping only the last segment writes no separator", func(t *testing.T) { + assert.Equal(t, + `{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[{"__typename":"Product","upc":"3"}]}}}`, + assemble(t, newAssembly(), []bool{false, false, true})) + }) + + t.Run("all-false keep leaves an empty representations list", func(t *testing.T) { + assert.Equal(t, + `{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[]}}}`, + assemble(t, newAssembly(), []bool{false, false, false})) + }) + + t.Run("a keep shorter than the segments drops the unmarked tail", func(t *testing.T) { + assert.Equal(t, + `{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[{"__typename":"Product","upc":"1"}]}}}`, + assemble(t, newAssembly(), []bool{true})) + }) + + t.Run("undefined variables are set on the FINAL bytes", func(t *testing.T) { + b := newAssembly() + b.undefinedVariables = []string{"first", "second"} + assert.Equal(t, + `{"undefined":["first","second"],"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[{"__typename":"Product","upc":"2"}]}}}`, + assemble(t, b, []bool{false, true, false})) + }) + + t.Run("no segments renders the bare bracket", func(t *testing.T) { + b := newAssembly() + b.segments = nil + assert.Equal(t, + `{"method":"POST","url":"http://reviews","body":{"query":"query($representations: [_Any!]!){_entities(representations: $representations)}","variables":{"representations":[]}}}`, + assemble(t, b, nil)) + }) +} diff --git a/v2/pkg/engine/resolve/cache_config.go b/v2/pkg/engine/resolve/cache_config.go new file mode 100644 index 0000000000..4926b9634a --- /dev/null +++ b/v2/pkg/engine/resolve/cache_config.go @@ -0,0 +1,179 @@ +package resolve + +import ( + "fmt" + "time" +) + +// FetchCacheConfig is the self-contained, federation-free per-fetch cache +// config the caching planner passes set onto SingleFetch / EntityFetch / +// BatchEntityFetch. The loader carries it forward-only (it never reads a field +// beyond the L1/L2 gate, it hands it to the controller); the cache package +// interprets it. A nil *FetchCacheConfig means caching is disabled for this +// fetch — the gate that makes a not-run planner pass behave as a NO-OP. It +// imports NO federation types: KeySpec references the fetch's own +// representation node, frozen at plan time by the cache key builder. +type FetchCacheConfig struct { + L1 bool // participate in the request-lifetime shared L1 cache + L2 bool // participate in the cross-request L2 cache + + // SubgraphName is the fetch's subgraph — the visible cache key prefix, so + // every subgraph owns its own keyspace. + SubgraphName string + // TTL is the STATIC tier of the TTL ladder; a subgraph response's + // Cache-Control max-age overrides it per fetch result. + TTL time.Duration + // MaxTTL clamps whichever tier wins, static or header-driven; 0 = no clamp. + MaxTTL time.Duration + NegativeCacheTTL time.Duration // > 0 enables negative caching + // IncludeSubgraphHeaders keys the fetch's entries by the forwarded subgraph + // header hash. It has one role per scope: on a PUBLIC fetch the hash leads + // the visible L2 key prefix (vary-by-headers, no privacy); on a private one + // it is the fallback source of the requester identity the key's partition + // segment derives from — so a private fetch is partitioned exactly once, + // never by prefix AND partition both. + IncludeSubgraphHeaders bool + // Private marks a STATICALLY private fetch: its entries belong to one + // requester, so their L2 keys carry a partition segment and are not stored + // at all when the request carries no identity. The request-lifetime layer is + // unaffected — one request is one requester. + Private bool + EnablePartialCacheLoad bool // partial cache load (serve covered items, fetch the rest) + PartialBatchLoad bool // partial batch realign + ShadowMode bool // L2 read-but-never-serve probe + HashAnalyticsKeys bool + + // KeySpec is the frozen key derivation, data only. + KeySpec CacheKeySpec + + // ProvidesData is the field tree the fetch returns. It is request-independent + // plan data, but it is consumed at RUNTIME by the coverage walk in + // PrepareFetch. Folding it here keeps the loader from referencing *Object for + // caching. + ProvidesData *Object + + // Mutation populate inheritance (request-lifetime carry). + PopulateL2OnMutation bool + MutationTTLOverride time.Duration +} + +// Equals deep-compares two configs so plan dedup can never lose or conflate +// cache policy. It is nil-safe: two nils are equal, nil never equals non-nil. +// ProvidesData is compared by response SHAPE (Object.Equals); the cache alias +// metadata on it (OriginalName / CacheArgs / HasAliases) is not compared. +// That is sound because fetch dedup additionally requires byte-identical +// rendered Input (FetchConfiguration.Equals), which pins the alias/argument +// structure — and the production dedup pass runs before configs are attached +// (postprocess: dedupe precedes ConfigureCaching). +func (c *FetchCacheConfig) Equals(other *FetchCacheConfig) bool { + if c == nil || other == nil { + return c == other + } + if c.L1 != other.L1 || + c.L2 != other.L2 || + c.SubgraphName != other.SubgraphName || + c.TTL != other.TTL || + c.MaxTTL != other.MaxTTL || + c.NegativeCacheTTL != other.NegativeCacheTTL || + c.IncludeSubgraphHeaders != other.IncludeSubgraphHeaders || + c.Private != other.Private || + c.EnablePartialCacheLoad != other.EnablePartialCacheLoad || + c.PartialBatchLoad != other.PartialBatchLoad || + c.ShadowMode != other.ShadowMode || + c.HashAnalyticsKeys != other.HashAnalyticsKeys || + c.PopulateL2OnMutation != other.PopulateL2OnMutation || + c.MutationTTLOverride != other.MutationTTLOverride { + return false + } + if !c.KeySpec.Equals(other.KeySpec) { + return false + } + if (c.ProvidesData == nil) != (other.ProvidesData == nil) { + return false + } + if c.ProvidesData != nil && !c.ProvidesData.Equals(other.ProvidesData) { + return false + } + return true +} + +// String renders a compact, nil-safe summary for the plan pretty-printer and +// for logs. +func (c *FetchCacheConfig) String() string { + if c == nil { + return "" + } + return fmt.Sprintf( + "{l1:%t l2:%t subgraph:%s ttl:%s maxTTL:%s negativeTTL:%s includeHeaders:%t private:%t partial:%t partialBatch:%t shadow:%t hashAnalytics:%t scope:%s type:%s field:%s representation:%t providesData:%t populateL2OnMutation:%t mutationTTL:%s}", + c.L1, + c.L2, + c.SubgraphName, + c.TTL, + c.MaxTTL, + c.NegativeCacheTTL, + c.IncludeSubgraphHeaders, + c.Private, + c.EnablePartialCacheLoad, + c.PartialBatchLoad, + c.ShadowMode, + c.HashAnalyticsKeys, + c.KeySpec.Scope, + c.KeySpec.TypeName, + c.KeySpec.FieldName, + c.KeySpec.Representation != nil, + c.ProvidesData != nil, + c.PopulateL2OnMutation, + c.MutationTTLOverride, + ) +} + +// CacheScope says whether a config caches a root field or an entity. +type CacheScope uint8 + +const ( + CacheScopeRootField CacheScope = iota + CacheScopeEntity +) + +// String renders the CacheScope for logs and test assertions. +func (s CacheScope) String() string { + switch s { + case CacheScopeRootField: + return "RootField" + case CacheScopeEntity: + return "Entity" + default: + return fmt.Sprintf("CacheScope(%d)", s) + } +} + +// CacheKeySpec is DATA ONLY (no renderer, no federation types). It identifies +// the ONE cache entry a fetch reads and writes per item. In entity scope the +// identity is the fetch's own merged representation node — the very object the +// fetch sends as its `representations` element — so read key, write key and +// fetch identity are byte-identical by construction. In root-field scope the +// identity is TypeName/FieldName plus the request variables instead. +type CacheKeySpec struct { + Scope CacheScope + TypeName string + FieldName string + + // Representation is the fetch's merged representation node (entity scope + // only; nil means the fetch is not cached). It is the plan-owned node the + // fetch's input template renders, with the interfaceObject / + // entityInterface __typename remap already baked in, and it carries every + // field the fetch sends — the chosen @key set plus any @requires sets. + Representation *Object +} + +// Equals structurally compares two specs; the representation is compared by +// response SHAPE and is nil-safe. +func (c CacheKeySpec) Equals(other CacheKeySpec) bool { + if c.Scope != other.Scope || c.TypeName != other.TypeName || c.FieldName != other.FieldName { + return false + } + if (c.Representation == nil) != (other.Representation == nil) { + return false + } + return c.Representation == nil || c.Representation.Equals(other.Representation) +} diff --git a/v2/pkg/engine/resolve/cache_config_test.go b/v2/pkg/engine/resolve/cache_config_test.go new file mode 100644 index 0000000000..2e3a76fbc2 --- /dev/null +++ b/v2/pkg/engine/resolve/cache_config_test.go @@ -0,0 +1,171 @@ +package resolve + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" +) + +// fullFetchCacheConfig returns a config with every field populated, so the +// Equals table can flip one field per row and prove each one participates. +func fullFetchCacheConfig() *FetchCacheConfig { + return &FetchCacheConfig{ + L1: true, + L2: true, + SubgraphName: "products", + TTL: 30 * time.Second, + MaxTTL: 2 * time.Minute, + NegativeCacheTTL: 5 * time.Second, + IncludeSubgraphHeaders: true, + Private: true, + EnablePartialCacheLoad: true, + PartialBatchLoad: true, + ShadowMode: true, + HashAnalyticsKeys: true, + KeySpec: CacheKeySpec{ + Scope: CacheScopeEntity, + TypeName: "Product", + FieldName: "product", + Representation: &Object{ + Nullable: true, + Fields: []*Field{ + { + Name: []byte("upc"), + Value: &String{Path: []string{"upc"}}, + OnTypeNames: [][]byte{[]byte("Product")}, + }, + }, + }, + }, + ProvidesData: &Object{ + Fields: []*Field{ + { + Name: []byte("name"), + Value: &String{Path: []string{"name"}}, + }, + }, + }, + PopulateL2OnMutation: true, + MutationTTLOverride: 10 * time.Second, + } +} + +func TestFetchCacheConfigEquals(t *testing.T) { + t.Run("nil safety", func(t *testing.T) { + var nilCfg *FetchCacheConfig + assert.True(t, nilCfg.Equals(nil)) + assert.False(t, nilCfg.Equals(fullFetchCacheConfig())) + assert.False(t, fullFetchCacheConfig().Equals(nil)) + }) + + t.Run("equal when fully populated", func(t *testing.T) { + assert.True(t, fullFetchCacheConfig().Equals(fullFetchCacheConfig())) + }) + + mutations := []struct { + name string + mutate func(c *FetchCacheConfig) + }{ + {"L1", func(c *FetchCacheConfig) { c.L1 = false }}, + {"L2", func(c *FetchCacheConfig) { c.L2 = false }}, + {"SubgraphName", func(c *FetchCacheConfig) { c.SubgraphName = "reviews" }}, + {"TTL", func(c *FetchCacheConfig) { c.TTL = time.Minute }}, + {"NegativeCacheTTL", func(c *FetchCacheConfig) { c.NegativeCacheTTL = time.Minute }}, + {"IncludeSubgraphHeaders", func(c *FetchCacheConfig) { c.IncludeSubgraphHeaders = false }}, + {"Private", func(c *FetchCacheConfig) { c.Private = false }}, + {"EnablePartialCacheLoad", func(c *FetchCacheConfig) { c.EnablePartialCacheLoad = false }}, + {"PartialBatchLoad", func(c *FetchCacheConfig) { c.PartialBatchLoad = false }}, + {"ShadowMode", func(c *FetchCacheConfig) { c.ShadowMode = false }}, + {"HashAnalyticsKeys", func(c *FetchCacheConfig) { c.HashAnalyticsKeys = false }}, + {"PopulateL2OnMutation", func(c *FetchCacheConfig) { c.PopulateL2OnMutation = false }}, + {"MutationTTLOverride", func(c *FetchCacheConfig) { c.MutationTTLOverride = time.Minute }}, + {"KeySpec.Scope", func(c *FetchCacheConfig) { c.KeySpec.Scope = CacheScopeRootField }}, + {"KeySpec.TypeName", func(c *FetchCacheConfig) { c.KeySpec.TypeName = "Review" }}, + {"KeySpec.FieldName", func(c *FetchCacheConfig) { c.KeySpec.FieldName = "review" }}, + {"KeySpec.Representation nil", func(c *FetchCacheConfig) { c.KeySpec.Representation = nil }}, + {"KeySpec.Representation shape", func(c *FetchCacheConfig) { + c.KeySpec.Representation.Fields[0].Name = []byte("sku") + }}, + {"ProvidesData nil", func(c *FetchCacheConfig) { c.ProvidesData = nil }}, + {"ProvidesData shape", func(c *FetchCacheConfig) { + c.ProvidesData.Fields[0].Name = []byte("title") + }}, + } + for _, row := range mutations { + t.Run("differ in "+row.name, func(t *testing.T) { + mutated := fullFetchCacheConfig() + row.mutate(mutated) + assert.False(t, fullFetchCacheConfig().Equals(mutated)) + assert.False(t, mutated.Equals(fullFetchCacheConfig())) + }) + } +} + +// TestFetchConfigurationEqualsCacheClause covers the plan-dedup cache clause. +func TestFetchConfigurationEqualsCacheClause(t *testing.T) { + t.Run("[P1] both nil", func(t *testing.T) { + a := &FetchConfiguration{} + b := &FetchConfiguration{} + assert.True(t, a.Equals(b)) + }) + + t.Run("[P2] one nil", func(t *testing.T) { + a := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b := &FetchConfiguration{} + assert.False(t, a.Equals(b)) + assert.False(t, b.Equals(a)) + }) + + t.Run("[P3] both non-nil, equal", func(t *testing.T) { + a := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b := &FetchConfiguration{Cache: fullFetchCacheConfig()} + assert.True(t, a.Equals(b)) + }) + + t.Run("[P4] differ in one field", func(t *testing.T) { + a := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b.Cache.TTL = time.Minute + assert.False(t, a.Equals(b)) + }) + + t.Run("[P4] differ in the MaxTTL clamp", func(t *testing.T) { + a := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b.Cache.MaxTTL = time.Hour + assert.False(t, a.Equals(b)) + }) + + t.Run("[P5] differ in the representation shape", func(t *testing.T) { + a := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b := &FetchConfiguration{Cache: fullFetchCacheConfig()} + b.Cache.KeySpec.Representation.Fields[0].Name = []byte("sku") + assert.False(t, a.Equals(b)) + }) +} + +func TestFetchCacheConfigString(t *testing.T) { + t.Run("nil", func(t *testing.T) { + var cfg *FetchCacheConfig + assert.Equal(t, "", cfg.String()) + }) + + t.Run("populated", func(t *testing.T) { + assert.Equal(t, + "{l1:true l2:true subgraph:products ttl:30s maxTTL:2m0s negativeTTL:5s includeHeaders:true private:true partial:true partialBatch:true shadow:true hashAnalytics:true scope:Entity type:Product field:product representation:true providesData:true populateL2OnMutation:true mutationTTL:10s}", + fullFetchCacheConfig().String()) + }) + + t.Run("zero value", func(t *testing.T) { + assert.Equal(t, + "{l1:false l2:false subgraph: ttl:0s maxTTL:0s negativeTTL:0s includeHeaders:false private:false partial:false partialBatch:false shadow:false hashAnalytics:false scope:RootField type: field: representation:false providesData:false populateL2OnMutation:false mutationTTL:0s}", + (&FetchCacheConfig{}).String()) + }) +} + +func TestCacheScopeString(t *testing.T) { + assert.Equal(t, "RootField", CacheScopeRootField.String()) + assert.Equal(t, "Entity", CacheScopeEntity.String()) + assert.Equal(t, "CacheScope(7)", CacheScope(7).String()) +} diff --git a/v2/pkg/engine/resolve/cache_controller.go b/v2/pkg/engine/resolve/cache_controller.go new file mode 100644 index 0000000000..86cf07cacd --- /dev/null +++ b/v2/pkg/engine/resolve/cache_controller.go @@ -0,0 +1,303 @@ +package resolve + +import ( + "fmt" + "net/http" + "time" + + "github.com/wundergraph/astjson" +) + +// CacheController is the long-lived, integrator-supplied cache lifecycle port. +// The router sets one via Context.SetCacheController, exactly as it sets an +// Authorizer. A nil controller is the global NO-OP and is zero-cost: the loader +// never enters cache code, never allocates a handle, never takes a lock. +// NO-OP, L1-only, L2-only, and L1+L2 are not distinguished here; they are all +// distinguished only by the RequestCache the controller hands back. +type CacheController interface { + // BeginRequest is called once per request, lazily, under DataBuffer.Lock, the + // first time a cache-eligible fetch is prepared. It returns the request-lifetime + // shared working surface, which is then shared by reference across every + // per-defer-group Loader of this request. The returned value owns all + // per-request mutable state, so nothing mutable hangs on the long-lived + // controller and there is no cross-request sharing. + BeginRequest(ctx *Context) RequestCache +} + +// RequestCache is the ONE mode-blind working surface the loader talks to. Its +// PrepareFetch / OnFetchSkipped / OnFetchResult methods are invoked from +// resolveSingle with NO loader lock held; each one opens exactly ONE +// CacheTransaction (which acquires DataBuffer.Lock) for its whole arena +// sequence and releases it with Commit. EndRequest runs once, single-threaded, +// after the whole fetch tree (root + every defer group) has resolved, and +// needs no lock and no arena. +type RequestCache interface { + // PrepareFetch runs after the prepare phase, with no loader lock held. It + // renders each item's ONE key from the fetch's representation node, looks the + // cache up under it, runs the per-item coverage walk, and returns a Decision + // plus the opaque handle the merge step reads. A NO-OP returns DecisionFetch + // and a nil handle. + PrepareFetch(in PrepareFetchInput) (Decision, *FetchCacheHandle) + + // OnUncachedFetch runs BEFORE the load for every fetch the loader executes + // without a cache config — a fetch the cache neither reads nor writes. It + // carries no state and decides nothing: it reports that part of this + // response came from outside the cache, which bounds what the client may be + // told about the response as a whole. It is the one hook that can be the + // FIRST call of a request, so it begins the request surface like any other. + // It holds no lock and must not touch the arena. + OnUncachedFetch() + + // OnFetchSkipped runs after the merge phase when PrepareFetch returned + // DecisionSkipFullHit. It splices the cached values into the merge targets. + // The fetch did not hit the network, and a pure hit owes no writes: the read + // key IS the write key, so there is nothing left to populate. + OnFetchSkipped(h *FetchCacheHandle, in MergeInput) error + + // OnFetchResult runs after the merge phase following a real network fetch + // (DecisionFetch, DecisionFetchShadow, or DecisionFetchPartial — the + // partial arm splices the cached items and realigns + merges the fetched + // ones in this same hook). It applies the write gate + // (!FetchFailed && !HasErrors && ResponseData != nil && Type() != Null; + // EmptyEntity is the one non-failure that still writes the negative + // sentinel) and persists or defers one write per item. When h.Shadow it runs + // the shadow compare before the write-back. + OnFetchResult(h *FetchCacheHandle, in MergeInput) error + + // EndRequest runs once after the root tree AND every defer group have + // resolved, single-threaded. It flushes batched L2 writes and finalizes + // analytics/trace. It needs no lock and no arena — and it MUST NOT touch + // one: on the arena entry paths it runs via defer AFTER the request arena + // is released back to its pool, so dereferencing any arena-owned + // astjson.Value still held on a handle (ItemCacheState.Item / FromCache, + // ShadowStash values) reads reset or reused memory. Everything EndRequest + // consumes must be plain heap data (strings, durations, copied bytes). + EndRequest() +} + +// CacheTraceFlusher is the optional RequestCache extension that attaches the +// per-fetch cache traces AHEAD of EndRequest. The resolver calls it right +// before the response renders (only when the trace ships in the response +// extensions), because the trace extension serializes during Resolve while +// EndRequest runs after the response has been written. Idempotent per handle; +// EndRequest's own observation pass skips handles already flushed. Same +// no-arena contract as EndRequest. +type CacheTraceFlusher interface { + FlushTraces() +} + +// Decision is what PrepareFetch tells the loader to do. It is the ONLY cache +// concept the loader branches on. +type Decision uint8 + +const ( + // DecisionFetch: miss, or caching disabled for this fetch. loadPhase fetches + // normally; the handle may be nil. + DecisionFetch Decision = iota + + // DecisionSkipFullHit: every item is covered by a covering cache value. The + // loader skips the network load and OnFetchSkipped only splices — with one + // key per item a served hit owes no writes. + DecisionSkipFullHit + + // DecisionFetchPartial: some items covered, some not. Fetch only the missed + // subset, then splice the cached subset and realign. + DecisionFetchPartial + + // DecisionFetchShadow: shadow-mode L2 read hit. The loader treats it exactly + // like a miss — skipLoad stays false, full fetch, full merge; the only deltas + // live in the handle and the extra compare step inside OnFetchResult. + DecisionFetchShadow +) + +// String renders the Decision for logs and test assertions. +func (d Decision) String() string { + switch d { + case DecisionFetch: + return "Fetch" + case DecisionSkipFullHit: + return "SkipFullHit" + case DecisionFetchPartial: + return "FetchPartial" + case DecisionFetchShadow: + return "FetchShadow" + default: + return fmt.Sprintf("Decision(%d)", d) + } +} + +// PrepareFetchInput carries everything PrepareFetch needs to render the item +// keys, look the cache up, and decide. Input is the canonical pre-injection +// rendered bytes and HeaderHash the subgraph header hash — together the sole +// key material, so read and write keys derive from the same canonical form. +type PrepareFetchInput struct { + Ctx *Context + Item *FetchItem + Items []*astjson.Value + Config *FetchCacheConfig + BatchStats [][]*astjson.Value + Input []byte + HeaderHash uint64 + Arena TransactionBeginner +} + +// MergeInput carries the post-merge view of one fetch to OnFetchSkipped / +// OnFetchResult. It surfaces all five write-gate signals: FetchFailed +// (transport / empty body / parse failure), HasErrors, EmptyEntity, StatusCode, +// and ResponseData == nil. FetchFailed and HasErrors block ALL fetched-value +// writes; EmptyEntity is the one non-failure that still writes (the negative +// sentinel); ResponseData == nil is the structural backstop for the early +// failure paths. The gate can never reduce to !HasErrors alone: transport, +// empty-body, and parse failures reach the merge hook with HasErrors == false. +type MergeInput struct { + Item *FetchItem + Items []*astjson.Value + ResponseData *astjson.Value + BatchStats [][]*astjson.Value + // MergePath is the fetch's post-processing merge path, so entity/batch + // values splice at the correct target instead of silently at the item root. + MergePath []string + // ResponseHeaders are the subgraph HTTP response's headers, the runtime + // source of the fetch's Cache-Control. They are NOT cloned: the hook reads + // them synchronously and must retain nothing. nil when the fetch produced no + // HTTP response — a transport failure, a non-HTTP datasource, or a skipped + // load — and the storability decision then falls back to static + // configuration. + ResponseHeaders http.Header + HasErrors bool + FetchFailed bool + EmptyEntity bool + StatusCode int + Arena TransactionBeginner +} + +// CacheObserver is the optional analytics/trace/shadow-compare port. It is +// composed INSIDE a RequestCache implementation (the loader never calls it +// directly), so verbose observability evolves with zero impact on the +// lookup/write surface. A nil observer means no observability and is zero-cost. +type CacheObserver interface { + BeginRequest(ctx *Context) + EndRequest(ctx *Context) + // OnFetchObserved derives per-fetch trace + counters from the finished + // handle, so trace and analytics read the same opaque state the writer used. + OnFetchObserved(h *FetchCacheHandle) + // CompareShadow runs the shadow staleness probe; the writer calls it before + // overwriting L2, preserving compare -> write-L1 -> write-L2 order. It runs + // inside OnFetchResult's already-open CacheTransaction (it does not open its + // own). + CompareShadow(h *FetchCacheHandle, fresh *astjson.Value, tx *CacheTransaction) + // OnStoreError reports ONE failed store round trip: the op ("GetMany" / + // "SetMany"), the subgraph whose keys it carried (empty for the request-end + // flush, which spans every fetch), how many keys the call held, and the + // store's error. A failed read serves every one of its keys as a miss and a + // failed write is dropped, so the request itself is unaffected. + OnStoreError(op string, subgraph string, keyCount int, err error) + // OnUncacheablePrivate reports private data the store never received. The + // result stays in the request-lifetime layer (per-request is per-requester) + // but no shared entry materializes, which is otherwise an invisible cache + // miss. Emitted at most ONCE per fetch, with the reason naming the remedy: + // "response-private" — a statically-public fetch was answered with + // `Cache-Control: private`, so declare the scope statically; or + // "no-identity" — a statically-private fetch ran without a requester + // identity, so supply a PrivatePartitionProvider or key by subgraph headers. + OnUncacheablePrivate(subgraph string, reason string) + // OnScopeMismatch reports a stored entry whose recorded privacy scope + // ("public" or "private") is not the one the reading fetch derives its keys + // under — configuration drift between the writing and the reading + // deployment. The entry is discarded as a miss, never served. + OnScopeMismatch(subgraph string, storedScope string) + // OnEntity / OnFieldValue are the resolvable-walker observability hooks. + OnEntity(h *FetchCacheHandle, entity *astjson.Value) + OnFieldValue(coordinate GraphCoordinate, value FieldValue) +} + +// FetchCacheHandle is the per-fetch opaque two-level cache state, carried on +// preparedFetch. It is allocated by PrepareFetch only when the controller +// actually touches the fetch; the loader stores it, threads it back to the +// merge hook, and never reads a field beyond Decision. +type FetchCacheHandle struct { + Decision Decision // what PrepareFetch decided (drives the merge dispatch) + WasHit bool // a covering cache value was found + BatchEntityKey bool // batch-entity-key mode (one key per unique representation) + // BatchFetchKeep marks, per unique batch bucket, whether the NETWORK fetch + // must include its representation (DecisionFetchPartial: true = still + // missing, false = served from cache). The loader assembles the reduced + // input from the already-rendered representation segments BEFORE any bytes + // are parsed back — nil means "fetch all". + BatchFetchKeep []bool + // Trace is the fetch's ART trace destination (nil when tracing is off); + // the observer attaches the assembled CacheTrace to it at request end. + Trace *DataSourceLoadTrace + // HashAnalyticsKeys mirrors the policy knob so the observer hashes key + // material in trace output when set. + HashAnalyticsKeys bool + Shadow bool // shadow mode: run compare in OnFetchResult before write-back + ShadowStash map[int]ShadowCacheEntry // stashed L2 reads for the shadow compare, keyed by item index + Items []ItemCacheState // per-item payload, one per merge target + Analytics any // observer-owned accumulators; opaque even here +} + +// String renders a compact, nil-safe summary for logs and panics, e.g. +// {decision:SkipFullHit items:3 hits:3 shadow:false}. +func (h *FetchCacheHandle) String() string { + if h == nil { + return "" + } + hits := 0 + for i := range h.Items { + if h.Items[i].FromCache != nil { + hits++ + } + } + return fmt.Sprintf("{decision:%s items:%d hits:%d shadow:%t}", h.Decision, len(h.Items), hits, h.Shadow) +} + +// ItemCacheState is the per-item cache payload, one per merge target. +// PrepareFetch writes every field except NegativeHit (stamped in OnFetchResult +// from the fresh response); the merge hooks read it. +// Item and FromCache may be arena-owned: they are valid inside the fetch-phase +// hooks only and MUST NOT be dereferenced at EndRequest time (a nil-check is +// fine — see RequestCache.EndRequest). +type ItemCacheState struct { + Item *astjson.Value // splice target / write source + FromCache *astjson.Value // cached value; nil = miss, TypeNull = negative hit + + // RenderedKey is the item's L2 store key, derived from the fetch's + // representation node; "" when the item could not render one, or when the + // fetch does not use L2 (then no store key is derived at all). + RenderedKey string + // L1Key is the item's request-lifetime cache key: the raw, unhashed + // preimage the L2 key derives from, without the format version and without + // the header hash (nothing persists and the map is per-requester). "" when + // the item could not render one, or in root-field scope, which is L2-only. + L1Key string + // Tags are the invalidation tags the item's store entry is indexed under, + // derived from the same rendering as RenderedKey and therefore identical + // whether the item ends up written or served from the store. nil when the + // fetch does not use L2 — tags address store entries and nothing else. + Tags []string + + RemainingTTL time.Duration // remaining TTL of the cached value, for analytics/trace + // ServedFreshness is what is left of a served store entry's lifetime, taken + // from the entry's OWN freshness record rather than from what the store + // reports. It bounds the client cache answer; 0 when the item was not + // served from the store or when no client answer is being computed. + ServedFreshness time.Duration + // ServedFromLayer is "l1" or "l2" when FromCache was selected (trace only). + ServedFromLayer string + BatchIndex int // original batch position for realign + NegativeHit bool // subgraph-null sentinel routing +} + +// ShadowCacheEntry is one stashed L2 read kept for the shadow compare: the +// value that WOULD have been served, compared against the fresh fetch before +// the write-back. +type ShadowCacheEntry struct { + CachedValue *astjson.Value + CacheKey string + RemainingTTL time.Duration + // CacheTTL is the policy TTL the entry was written with, so the observer + // can derive the entry's age (CacheTTL - RemainingTTL) without re-deriving + // config. + CacheTTL time.Duration +} diff --git a/v2/pkg/engine/resolve/cache_controller_test.go b/v2/pkg/engine/resolve/cache_controller_test.go new file mode 100644 index 0000000000..2c3bbee938 --- /dev/null +++ b/v2/pkg/engine/resolve/cache_controller_test.go @@ -0,0 +1,51 @@ +package resolve + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + "github.com/wundergraph/astjson" +) + +func TestDecisionString(t *testing.T) { + assert.Equal(t, "Fetch", DecisionFetch.String()) + assert.Equal(t, "SkipFullHit", DecisionSkipFullHit.String()) + assert.Equal(t, "FetchPartial", DecisionFetchPartial.String()) + assert.Equal(t, "FetchShadow", DecisionFetchShadow.String()) + assert.Equal(t, "Decision(9)", Decision(9).String()) +} + +func TestFetchCacheHandleString(t *testing.T) { + t.Run("nil", func(t *testing.T) { + var h *FetchCacheHandle + assert.Equal(t, "", h.String()) + }) + + t.Run("zero value", func(t *testing.T) { + assert.Equal(t, "{decision:Fetch items:0 hits:0 shadow:false}", (&FetchCacheHandle{}).String()) + }) + + t.Run("populated", func(t *testing.T) { + cached := astjson.MustParseBytes([]byte(`{"__typename":"Product","upc":"1"}`)) + h := &FetchCacheHandle{ + Decision: DecisionSkipFullHit, + WasHit: true, + Items: []ItemCacheState{ + {FromCache: cached}, + {FromCache: cached}, + {}, + }, + } + assert.Equal(t, "{decision:SkipFullHit items:3 hits:2 shadow:false}", h.String()) + }) + + t.Run("shadow", func(t *testing.T) { + h := &FetchCacheHandle{ + Decision: DecisionFetchShadow, + Shadow: true, + Items: []ItemCacheState{{}}, + } + assert.Equal(t, "{decision:FetchShadow items:1 hits:0 shadow:true}", h.String()) + }) +} diff --git a/v2/pkg/engine/resolve/cache_fetch_test.go b/v2/pkg/engine/resolve/cache_fetch_test.go new file mode 100644 index 0000000000..da18961911 --- /dev/null +++ b/v2/pkg/engine/resolve/cache_fetch_test.go @@ -0,0 +1,63 @@ +package resolve + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +// TestFetchCachePolymorphism proves the Fetch interface cache accessors and +// shape predicates across ALL concrete fetch types, so caching code never +// needs a switch over concrete types. +func TestFetchCachePolymorphism(t *testing.T) { + cases := []struct { + name string + fetch Fetch + isEntityFetch bool + isBatchEntityFetch bool + }{ + { + name: "SingleFetch", + fetch: &SingleFetch{}, + isEntityFetch: false, + isBatchEntityFetch: false, + }, + { + name: "EntityFetch", + fetch: &EntityFetch{}, + isEntityFetch: true, + isBatchEntityFetch: false, + }, + { + name: "BatchEntityFetch", + fetch: &BatchEntityFetch{}, + isEntityFetch: false, + isBatchEntityFetch: true, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + assert.Nil(t, tc.fetch.CacheConfig()) + + cfg := &FetchCacheConfig{L2: true, SubgraphName: "products"} + tc.fetch.SetCacheConfig(cfg) + assert.Same(t, cfg, tc.fetch.CacheConfig()) + + tc.fetch.SetCacheConfig(nil) + assert.Nil(t, tc.fetch.CacheConfig()) + + assert.Equal(t, tc.isEntityFetch, tc.fetch.IsEntityFetch()) + assert.Equal(t, tc.isBatchEntityFetch, tc.fetch.IsBatchEntityFetch()) + }) + } +} + +// TestSingleFetchCacheConfigSharesFetchConfiguration pins that the SingleFetch +// accessor reads/writes the embedded FetchConfiguration.Cache field, which is +// what plan dedup compares. +func TestSingleFetchCacheConfigSharesFetchConfiguration(t *testing.T) { + f := &SingleFetch{} + cfg := &FetchCacheConfig{L1: true} + f.SetCacheConfig(cfg) + assert.Same(t, cfg, f.FetchConfiguration.Cache) +} diff --git a/v2/pkg/engine/resolve/cache_node_copy_test.go b/v2/pkg/engine/resolve/cache_node_copy_test.go new file mode 100644 index 0000000000..19d6b03d3a --- /dev/null +++ b/v2/pkg/engine/resolve/cache_node_copy_test.go @@ -0,0 +1,91 @@ +package resolve + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +// TestObjectCopyCarriesCacheMetadata pins that Object.Copy / Field.Copy carry +// the caching planner metadata (HasAliases, OriginalName, CacheArgs), so +// defer's response-tree copies never lose it. +func TestObjectCopyCarriesCacheMetadata(t *testing.T) { + original := &Object{ + Nullable: true, + Path: []string{"product"}, + HasAliases: true, + Fields: []*Field{ + { + Name: []byte("productName"), + OriginalName: []byte("name"), + Value: &String{ + Path: []string{"productName"}, + }, + }, + { + Name: []byte("price"), + CacheArgs: []CacheFieldArg{ + {Name: "currency", VariableName: "a"}, + {Name: "region", VariableName: "b"}, + }, + Value: &Float{ + Path: []string{"price"}, + }, + }, + }, + } + + copied := original.Copy() + + assert.Equal(t, &Object{ + Nullable: true, + Path: []string{"product"}, + HasAliases: true, + Fields: []*Field{ + { + Name: []byte("productName"), + OriginalName: []byte("name"), + Value: &String{ + Path: []string{"productName"}, + }, + }, + { + Name: []byte("price"), + CacheArgs: []CacheFieldArg{ + {Name: "currency", VariableName: "a"}, + {Name: "region", VariableName: "b"}, + }, + Value: &Float{ + Path: []string{"price"}, + }, + }, + }, + }, copied) + + // CacheArgs must be cloned, not aliased: mutating the copy must not reach + // the original. + copiedObject := copied.(*Object) + copiedObject.Fields[1].CacheArgs[0].VariableName = "mutated" + assert.Equal(t, "a", original.Fields[1].CacheArgs[0].VariableName) +} + +// TestGraphQLResponseCacheProvidesData pins the ProvidesData side-table +// accessors on the response. +func TestGraphQLResponseCacheProvidesData(t *testing.T) { + response := &GraphQLResponse{} + assert.Nil(t, response.CacheProvidesData()) + + info := &FetchInfo{DataSourceID: "products"} + providesData := map[*FetchInfo]*Object{ + info: { + Fields: []*Field{ + { + Name: []byte("name"), + Value: &String{Path: []string{"name"}}, + }, + }, + }, + } + response.SetCacheProvidesData(providesData) + assert.Equal(t, providesData, response.CacheProvidesData()) +} diff --git a/v2/pkg/engine/resolve/cache_noop_test.go b/v2/pkg/engine/resolve/cache_noop_test.go new file mode 100644 index 0000000000..ccb69c5129 --- /dev/null +++ b/v2/pkg/engine/resolve/cache_noop_test.go @@ -0,0 +1,153 @@ +package resolve + +import ( + "testing" + + "github.com/golang/mock/gomock" + "github.com/stretchr/testify/assert" + + "github.com/wundergraph/astjson" + + "github.com/wundergraph/graphql-go-tools/v2/pkg/fastjsonext" +) + +// countingCacheController records BeginRequest calls and hands out ONE counting +// request surface, so the no-op gates can be asserted observably: without a +// controller the loader must never reach cache code at all, and with one it +// must reach nothing beyond the uncached-fetch notification. +type countingCacheController struct { + beginRequestCalls int + request *countingRequestCache +} + +func (c *countingCacheController) BeginRequest(ctx *Context) RequestCache { + c.beginRequestCalls++ + if c.request == nil { + c.request = &countingRequestCache{} + } + return c.request +} + +// TestCacheNoOpGates proves the runtime no-op invariant of the loader seam: the +// loader output is byte-identical with no controller and with a controller over +// fetches none of which is cache-configured. +func TestCacheNoOpGates(t *testing.T) { + newResponse := func(ctrl *gomock.Controller) *GraphQLResponse { + ds := mockedDS(t, ctrl, + `{"method":"POST","url":"http://products","body":{"query":"query{topProducts{name}}"}}`, + `{"data":{"topProducts":[{"name":"Table"},{"name":"Couch"}]}}`) + return &GraphQLResponse{ + Fetches: Sequence( + Single(&SingleFetch{ + InputTemplate: InputTemplate{ + Segments: []TemplateSegment{ + { + Data: []byte(`{"method":"POST","url":"http://products","body":{"query":"query{topProducts{name}}"}}`), + SegmentType: StaticSegmentType, + }, + }, + }, + FetchConfiguration: FetchConfiguration{ + DataSource: ds, + PostProcessing: PostProcessingConfiguration{ + SelectResponseDataPath: []string{"data"}, + }, + }, + }), + ), + } + } + + load := func(t *testing.T, ctx *Context, response *GraphQLResponse) string { + t.Helper() + loader := &Loader{dataBuffer: &DataBuffer{data: astjson.ObjectValue(nil)}} + err := loader.LoadGraphQLResponseData(ctx, response) + assert.NoError(t, err) + return fastjsonext.PrintGraphQLResponse(loader.dataBuffer.Get(), loader.errors) + } + + expected := `{"data":{"topProducts":[{"name":"Table"},{"name":"Couch"}]}}` + + t.Run("no controller", func(t *testing.T) { + ctrl := gomock.NewController(t) + defer ctrl.Finish() + ctx := NewContext(t.Context()) + out := load(t, ctx, newResponse(ctrl)) + assert.Equal(t, expected, out) + assert.Nil(t, ctx.requestCache) + }) + + t.Run("controller set but no fetch is cache-configured", func(t *testing.T) { + ctrl := gomock.NewController(t) + defer ctrl.Finish() + controller := &countingCacheController{} + ctx := NewContext(t.Context()) + ctx.SetCacheController(controller) + out := load(t, ctx, newResponse(ctrl)) + assert.Equal(t, expected, out) + // The response is what the controller-free run produced. The one thing + // the controller hears is that the fetch ran outside the cache — the + // signal that keeps a response with uncached parts from being advertised + // as keepable — and no lookup, merge or write hook runs. + assert.Equal(t, 1, controller.beginRequestCalls) + assert.Equal(t, countingRequestCache{uncachedFetchCalls: 1}, *controller.request) + }) +} + +// TestEndCacheRequestIdempotent pins the request-end lifecycle: EndRequest runs +// once, the surface is reset, and calling endCacheRequest again is a no-op. +func TestEndCacheRequestIdempotent(t *testing.T) { + ctx := NewContext(t.Context()) + + // A Context that never used caching must no-op. + ctx.endCacheRequest() + assert.Nil(t, ctx.requestCache) + + rc := &countingRequestCache{} + ctx.requestCache = rc + ctx.endCacheRequest() + ctx.endCacheRequest() + assert.Equal(t, 1, rc.endRequestCalls) + assert.Nil(t, ctx.requestCache) +} + +// TestContextCloneResetsRequestCache pins subscription-event isolation: a +// cloned resolution keeps the controller port but builds its own per-request +// cache surface. +func TestContextCloneResetsRequestCache(t *testing.T) { + controller := &countingCacheController{} + ctx := NewContext(t.Context()) + ctx.SetCacheController(controller) + ctx.requestCache = &countingRequestCache{} + + cloned := ctx.clone(t.Context()) + assert.Nil(t, cloned.requestCache) + assert.Same(t, controller, cloned.cacheController) +} + +// countingRequestCache is a minimal RequestCache fake recording the hook calls +// the lifecycle and no-op rows assert on. +type countingRequestCache struct { + endRequestCalls int + uncachedFetchCalls int +} + +func (c *countingRequestCache) PrepareFetch(in PrepareFetchInput) (Decision, *FetchCacheHandle) { + return DecisionFetch, nil +} + +func (c *countingRequestCache) OnUncachedFetch() { + c.uncachedFetchCalls++ +} + +func (c *countingRequestCache) OnFetchSkipped(h *FetchCacheHandle, in MergeInput) error { + return nil +} + +func (c *countingRequestCache) OnFetchResult(h *FetchCacheHandle, in MergeInput) error { + return nil +} + +func (c *countingRequestCache) EndRequest() { + c.endRequestCalls++ +} diff --git a/v2/pkg/engine/resolve/cache_response.go b/v2/pkg/engine/resolve/cache_response.go new file mode 100644 index 0000000000..26d4ddba16 --- /dev/null +++ b/v2/pkg/engine/resolve/cache_response.go @@ -0,0 +1,45 @@ +package resolve + +import "time" + +// CacheResponseInfo is the ONE client-facing cache answer of a request: what +// the parts of the response allow a downstream cache — the client, a CDN — to +// do with it. The integrator reads it once, after resolution, and turns it into +// response headers; the engine itself never emits a header. +// +// Reading it: +// +// !HasPolicy the operation cached nothing at all — emit NO header +// NoStore some part of the response was not cacheable +// otherwise max-age is MaxAge, floored to seconds +// Private a part belongs to one requester: add the private token +// Tags the entries the response was built from, for a +// tag-purging CDN; empty unless tag emission is enabled +type CacheResponseInfo struct { + // HasPolicy reports that at least one cache-configured fetch contributed. + // It is false for an operation whose fetches are none of the cache's + // business — which is NOT the same as an operation that may not be stored. + HasPolicy bool + // MaxAge is the minimum remaining freshness over the contributing parts: a + // served entry contributes what is left of its lifetime, a freshly stored + // one the lifetime it was written under. Meaningless when NoStore. + MaxAge time.Duration + // Private marks a response with a part that belongs to one requester. + Private bool + // NoStore marks a response with a part that was not cacheable at all, which + // is the most restrictive answer and outranks MaxAge. + NoStore bool + // Tags is the union of the invalidation tags of every entry the response + // was built from, sorted, so one purge reaches the CDN copy and the store + // entries alike. + Tags []string +} + +// CacheResponseInfoSource is the per-request producer of the client cache +// answer, implemented by the caching controller's request surface and installed +// on the Context when it begins. It is deliberately separate from the +// RequestCache field: the answer is read AFTER EndRequest, which releases that +// one. +type CacheResponseInfoSource interface { + CacheResponseInfo() CacheResponseInfo +} diff --git a/v2/pkg/engine/resolve/cache_transaction.go b/v2/pkg/engine/resolve/cache_transaction.go new file mode 100644 index 0000000000..09b3605181 --- /dev/null +++ b/v2/pkg/engine/resolve/cache_transaction.go @@ -0,0 +1,113 @@ +package resolve + +import ( + "github.com/wundergraph/astjson" + "github.com/wundergraph/go-arena" +) + +// TransactionBeginner opens CacheTransactions over the loader's shared JSON +// arena. The loader hands one to every cache hook input; a hook opens exactly +// ONE transaction via Begin at the top of its arena work and releases it with +// Commit (via defer). A TransactionBeginner must never be retained past the +// hook it was handed to, and must never be used from the off-lock load phase. +type TransactionBeginner interface { + // Begin enters the locked merge region and returns the transaction through + // which all arena/parser ops run. It acquires DataBuffer.Lock once for the + // caller; the matching Commit releases it. + Begin() *CacheTransaction +} + +// CacheTransaction is the scoped, lock-held handle for one multi-op arena +// sequence (candidate parse -> merge synthesis -> reorder, then the splice or +// write). Every arena/parser op is a method ON the transaction, so the arena +// cannot be touched without a held transaction. One transaction per hook is +// one DataBuffer.Lock acquisition; Commit MUST be called (via defer) exactly +// once. +type CacheTransaction struct { + a arena.Arena + db *DataBuffer +} + +// ParseBytes parses b onto the transaction's arena (lazy candidate parse). +func (t *CacheTransaction) ParseBytes(b []byte) (*astjson.Value, error) { + return astjson.ParseBytesWithArena(t.a, b) +} + +// StructuralCopy deep-copies v onto the arena, avoiding merge aliasing +// corruption when the same cached value is spliced into multiple targets. +// Callers rely on VALUE isolation (mutating the source or the copy never +// affects the other) — in heap mode (nil arena, one production resolve entry +// runs this way) astjson.DeepCopy is an identity passthrough, so a real copy +// is forced via a marshal round-trip there. +func (t *CacheTransaction) StructuralCopy(v *astjson.Value) *astjson.Value { + if t.a != nil { + return astjson.DeepCopy(t.a, v) + } + if v == nil { + return nil + } + copied, err := astjson.ParseBytes(v.MarshalTo(nil)) + if err != nil { + return v + } + return copied +} + +// MergeValues merges src into dst on the arena. The underlying "changed" flag +// is intentionally discarded, matching how the defer merge path discards it. +func (t *CacheTransaction) MergeValues(dst, src *astjson.Value) (*astjson.Value, error) { + merged, _, err := astjson.MergeValues(t.a, dst, src) + return merged, err +} + +// MergeValuesWithPath merges src into dst at path on the arena. +func (t *CacheTransaction) MergeValuesWithPath(dst, src *astjson.Value, path ...string) (*astjson.Value, error) { + merged, _, err := astjson.MergeValuesWithPath(t.a, dst, src, path...) + return merged, err +} + +// NewObject allocates an empty object value on the arena. +func (t *CacheTransaction) NewObject() *astjson.Value { + return astjson.ObjectValue(t.a) +} + +// NewArray allocates an empty array value on the arena. +func (t *CacheTransaction) NewArray() *astjson.Value { + return astjson.ArrayValue(t.a) +} + +// String allocates a string value on the arena. +func (t *CacheTransaction) String(s string) *astjson.Value { + return astjson.StringValue(t.a, s) +} + +// Null returns the JSON null value. +func (t *CacheTransaction) Null() *astjson.Value { + return astjson.NullValue +} + +// Commit releases DataBuffer.Lock and ends the transaction; call via defer. +func (t *CacheTransaction) Commit() { + t.db.Unlock() +} + +// NewTransactionBeginner builds a TransactionBeginner over an arena and its +// DataBuffer guard. The loader wires its own internally; this constructor +// exists for cache-controller unit tests and out-of-loader tooling that must +// exercise the transaction contract directly. +func NewTransactionBeginner(a arena.Arena, db *DataBuffer) TransactionBeginner { + return cacheTransactionBeginner{a: a, db: db} +} + +// cacheTransactionBeginner is the loader-backed TransactionBeginner, bound to +// the request's shared jsonArena and its DataBuffer guard. It is built only +// when a cache hook actually runs, never on the no-op path. +type cacheTransactionBeginner struct { + a arena.Arena + db *DataBuffer +} + +func (b cacheTransactionBeginner) Begin() *CacheTransaction { + b.db.Lock() + return &CacheTransaction{a: b.a, db: b.db} +} diff --git a/v2/pkg/engine/resolve/context.go b/v2/pkg/engine/resolve/context.go index 76a5d1ca99..518d4ecbeb 100644 --- a/v2/pkg/engine/resolve/context.go +++ b/v2/pkg/engine/resolve/context.go @@ -43,6 +43,25 @@ type Context struct { rateLimiter RateLimiter fieldRenderer FieldValueRenderer + // cacheController is the long-lived caching port (see SetCacheController); + // requestCache is the per-request working surface it hands back, created + // lazily under DataBuffer.Lock and shared by reference across all + // per-defer-group Loaders of this request. + cacheController CacheController + requestCache RequestCache + // cacheResponseSource produces the client-facing cache answer of this + // request (see CacheResponseInfo). It is held separately from requestCache + // because it is read AFTER resolution, when endCacheRequest has already + // released that one. + cacheResponseSource CacheResponseInfoSource + // deferredResponse marks a resolution of a @defer plan. Parts of such a + // response resolve after the initial frame is on the wire, so no cache + // answer computed with it can describe the whole response. + deferredResponse bool + // privatePartitionProvider derives the requester identity private cache + // entries are partitioned by (see SetPrivatePartitionProvider). + privatePartitionProvider PrivatePartitionProvider + subgraphErrors map[string]error SubgraphHeadersBuilder SubgraphHeadersBuilder @@ -190,6 +209,91 @@ func (c *Context) SetAuthorizer(authorizer Authorizer) { c.authorizer = authorizer } +// SetCacheController wires the caching lifecycle port, mirroring SetAuthorizer. +// A nil controller (the default) keeps the loader on its cache-free path. +func (c *Context) SetCacheController(controller CacheController) { + c.cacheController = controller +} + +// SetCacheResponseInfoSource installs the producer of this request's client +// cache answer. The caching controller calls it when the request begins; it +// survives endCacheRequest so the answer stays readable at response time. +func (c *Context) SetCacheResponseInfoSource(source CacheResponseInfoSource) { + c.cacheResponseSource = source +} + +// CacheResponseInfo returns the request's client cache answer, read once +// resolution has completed. The zero value — no policy, no tags — is what a +// request without caching, with client emission switched off, or with a @defer +// plan reports, and it tells the integrator to emit no cache headers at all. +func (c *Context) CacheResponseInfo() CacheResponseInfo { + if c.cacheResponseSource == nil { + return CacheResponseInfo{} + } + return c.cacheResponseSource.CacheResponseInfo() +} + +// HasDeferredResponse reports whether this request resolves a @defer plan. The +// cache reads it to suppress the client cache answer: the response headers ship +// with the initial frame while the deferred parts are still being fetched. +func (c *Context) HasDeferredResponse() bool { + return c.deferredResponse +} + +// PrivatePartitionProvider derives the requester identity that private cache +// entries are partitioned by — a JWT subject, a tenant, whatever the integrator +// considers one audience. It is consulted at most once per subgraph per +// request, and only when a statically-private fetch actually reaches the store. +type PrivatePartitionProvider interface { + // PrivatePartition returns the requester identity for a subgraph's private + // entries. ok=false — and an empty value, which is treated the same — means + // the request carries NO identity: private-scoped fetches are then neither + // read from nor written to the store, and live in the request-lifetime + // layer alone. The returned value never reaches a key verbatim; it is + // hashed into the key's partition segment. + PrivatePartition(ctx *Context, subgraphName string) (value string, ok bool) +} + +// SetPrivatePartitionProvider wires the requester-identity port, mirroring +// SetCacheController. Without one, private entries can still be partitioned by +// the forwarded subgraph header hash where the configuration asks for it. +func (c *Context) SetPrivatePartitionProvider(provider PrivatePartitionProvider) { + c.privatePartitionProvider = provider +} + +// PrivatePartition asks the wired provider for this request's identity at a +// subgraph; ok=false when no provider is set or it identifies no requester. +func (c *Context) PrivatePartition(subgraphName string) (string, bool) { + if c.privatePartitionProvider == nil { + return "", false + } + return c.privatePartitionProvider.PrivatePartition(c, subgraphName) +} + +// endCacheRequest finalizes the per-request cache surface (flushing deferred +// writes) and resets it. It is idempotent and a no-op when caching was never +// used; deferred at every request entry function. +func (c *Context) endCacheRequest() { + if c.requestCache != nil { + c.requestCache.EndRequest() + c.requestCache = nil + } +} + +// flushCacheTraces asks the request cache to attach the per-fetch cache traces +// NOW instead of at EndRequest: the trace extension serializes DURING Resolve, +// while EndRequest runs after the response has been written, so a trace +// rendered with the response would otherwise never carry the cache sections. +// A no-op without a cache surface or when the surface doesn't support it. +func (c *Context) flushCacheTraces() { + if c.requestCache == nil { + return + } + if flusher, ok := c.requestCache.(CacheTraceFlusher); ok { + flusher.FlushTraces() + } +} + func (c *Context) SetEngineLoaderHooks(hooks LoaderHooks) { c.LoaderHooks = hooks } @@ -283,6 +387,12 @@ func (c *Context) WithContext(ctx context.Context) *Context { func (c *Context) clone(ctx context.Context) *Context { cpy := *c cpy.ctx = ctx + // A cloned resolution (e.g. a subscription event) is a separate request and + // must build its own per-request cache surface and its own client cache + // answer; the controller port itself is carried over by the value copy + // above. + cpy.requestCache = nil + cpy.cacheResponseSource = nil if c.Variables != nil { variablesData := c.Variables.MarshalTo(nil) cpy.Variables = astjson.MustParseBytes(variablesData) @@ -305,6 +415,9 @@ func (c *Context) clone(ctx context.Context) *Context { } func (c *Context) Free() { + // Defensive: the entry-function defers normally end the cache request; this + // covers a Context recycled without passing through one. + c.endCacheRequest() c.ctx = nil c.Variables = nil c.Files = nil @@ -315,6 +428,10 @@ func (c *Context) Free() { c.Extensions = nil c.subgraphErrors = nil c.authorizer = nil + c.cacheController = nil + c.cacheResponseSource = nil + c.deferredResponse = false + c.privatePartitionProvider = nil c.LoaderHooks = nil c.GetDeduplicationData = nil c.SetDeduplicationData = nil diff --git a/v2/pkg/engine/resolve/fetch.go b/v2/pkg/engine/resolve/fetch.go index 30854a48e9..cfa639beea 100644 --- a/v2/pkg/engine/resolve/fetch.go +++ b/v2/pkg/engine/resolve/fetch.go @@ -23,6 +23,40 @@ type Fetch interface { // FetchInfo returns additional fetch-related information. // Callers must treat FetchInfo as read-only after planning; it may be nil when disabled by planner options. FetchInfo() *FetchInfo + + // CacheConfig returns the per-fetch cache config; nil means "not cached". + // All caching code reads it through this method (never via a switch over + // concrete fetch types). + CacheConfig() *FetchCacheConfig + + // SetCacheConfig sets the per-fetch cache config; the caching planner passes + // call it after the concrete fetch types are created. + SetCacheConfig(cfg *FetchCacheConfig) + + // IsEntityFetch reports whether this is a single-entity fetch (an _entities + // fetch on an object field). + IsEntityFetch() bool + + // IsBatchEntityFetch reports whether this is a batched entity fetch (an + // _entities fetch over array items). + IsBatchEntityFetch() bool + + // RepresentationInputTemplate returns the input template holding the + // fetch's `representations` element — the ResolvableObjectVariable segment + // whose node IS the merged representation the fetch sends. It is nil for + // fetches that send no representation (plain single fetches). Caching reads + // it through this method (never via a switch over concrete fetch types). + RepresentationInputTemplate() *InputTemplate + + // LoadTrace returns the fetch's ART trace destination; nil when tracing is + // disabled for the request. Caching/observability code reads it through + // this method (never via a switch over concrete fetch types). + LoadTrace() *DataSourceLoadTrace + + // SetDataSource replaces the fetch's transport, e.g. to swap in an + // in-process fake; it exists so no caller needs a switch over concrete + // fetch types. + SetDataSource(ds DataSource) } type FetchItem struct { @@ -111,6 +145,33 @@ func (s *SingleFetch) FetchInfo() *FetchInfo { return s.Info } +func (s *SingleFetch) CacheConfig() *FetchCacheConfig { + return s.FetchConfiguration.Cache +} + +func (s *SingleFetch) SetCacheConfig(cfg *FetchCacheConfig) { + s.FetchConfiguration.Cache = cfg +} + +func (s *SingleFetch) IsEntityFetch() bool { + return false +} + +func (s *SingleFetch) IsBatchEntityFetch() bool { + return false +} + +// RepresentationInputTemplate returns nil: a plain single fetch sends no +// representations element (createConcreteSingleFetchTypes converts the ones +// that do into EntityFetch / BatchEntityFetch). +func (s *SingleFetch) RepresentationInputTemplate() *InputTemplate { + return nil +} + +func (s *SingleFetch) SetDataSource(ds DataSource) { + s.FetchConfiguration.DataSource = ds +} + // FetchDependencies holding current fetch id and ids of fetches that current fetch depends on // e.g. should be fetched only after all dependent fetches are fetched type FetchDependencies struct { @@ -156,6 +217,10 @@ func (ppc *PostProcessingConfiguration) Equals(other *PostProcessingConfiguratio return true } +func (f *SingleFetch) LoadTrace() *DataSourceLoadTrace { + return f.Trace +} + func (*SingleFetch) FetchKind() FetchKind { return FetchKindSingle } @@ -169,6 +234,7 @@ type BatchEntityFetch struct { Input BatchInput DataSource DataSource PostProcessing PostProcessingConfiguration + Cache *FetchCacheConfig DataSourceIdentifier []byte Trace *DataSourceLoadTrace Info *FetchInfo @@ -182,6 +248,35 @@ func (b *BatchEntityFetch) FetchInfo() *FetchInfo { return b.Info } +func (b *BatchEntityFetch) CacheConfig() *FetchCacheConfig { + return b.Cache +} + +func (b *BatchEntityFetch) SetCacheConfig(cfg *FetchCacheConfig) { + b.Cache = cfg +} + +func (b *BatchEntityFetch) IsEntityFetch() bool { + return false +} + +func (b *BatchEntityFetch) IsBatchEntityFetch() bool { + return true +} + +// RepresentationInputTemplate returns the batch's per-item template; every +// item renders the same representation node, so the first one identifies it. +func (b *BatchEntityFetch) RepresentationInputTemplate() *InputTemplate { + if len(b.Input.Items) == 0 { + return nil + } + return &b.Input.Items[0] +} + +func (b *BatchEntityFetch) SetDataSource(ds DataSource) { + b.DataSource = ds +} + type BatchInput struct { Header InputTemplate Items []InputTemplate @@ -197,6 +292,10 @@ type BatchInput struct { Footer InputTemplate } +func (f *BatchEntityFetch) LoadTrace() *DataSourceLoadTrace { + return f.Trace +} + func (*BatchEntityFetch) FetchKind() FetchKind { return FetchKindEntityBatch } @@ -209,6 +308,7 @@ type EntityFetch struct { Input EntityInput DataSource DataSource PostProcessing PostProcessingConfiguration + Cache *FetchCacheConfig DataSourceIdentifier []byte Trace *DataSourceLoadTrace Info *FetchInfo @@ -222,6 +322,31 @@ func (e *EntityFetch) FetchInfo() *FetchInfo { return e.Info } +func (e *EntityFetch) CacheConfig() *FetchCacheConfig { + return e.Cache +} + +func (e *EntityFetch) SetCacheConfig(cfg *FetchCacheConfig) { + e.Cache = cfg +} + +func (e *EntityFetch) IsEntityFetch() bool { + return true +} + +func (e *EntityFetch) IsBatchEntityFetch() bool { + return false +} + +// RepresentationInputTemplate returns the single-item representation template. +func (e *EntityFetch) RepresentationInputTemplate() *InputTemplate { + return &e.Input.Item +} + +func (e *EntityFetch) SetDataSource(ds DataSource) { + e.DataSource = ds +} + type EntityInput struct { Header InputTemplate Item InputTemplate @@ -229,6 +354,10 @@ type EntityInput struct { Footer InputTemplate } +func (f *EntityFetch) LoadTrace() *DataSourceLoadTrace { + return f.Trace +} + func (*EntityFetch) FetchKind() FetchKind { return FetchKindEntity } @@ -278,6 +407,10 @@ type FetchConfiguration struct { // OperationName is non-empty when the operation name is propagated to the upstream subgraph fetch. OperationName string + + // Cache is the per-fetch cache config; nil means "not cached". A pointer so + // most (uncached) fetches carry no inline struct. + Cache *FetchCacheConfig } func (fc *FetchConfiguration) Equals(other *FetchConfiguration) bool { @@ -304,6 +437,12 @@ func (fc *FetchConfiguration) Equals(other *FetchConfiguration) bool { if fc.SetTemplateOutputToNullOnVariableNull != other.SetTemplateOutputToNullOnVariableNull { return false } + if (fc.Cache == nil) != (other.Cache == nil) { + return false + } + if fc.Cache != nil && !fc.Cache.Equals(other.Cache) { + return false + } return true } @@ -391,9 +530,42 @@ type DataSourceLoadTrace struct { SingleFlightSharedResponse bool `json:"single_flight_shared_response"` LoadSkipped bool `json:"load_skipped"` LoadStats *LoadStats `json:"load_stats,omitempty"` + CacheTrace *CacheTrace `json:"cache,omitempty"` Path string `json:"-"` } +// CacheTrace is the per-fetch caching section of the ART trace output, +// assembled by the cache observer at request end from the opaque +// FetchCacheHandle — no caching internals leak onto the loader surface. +type CacheTrace struct { + Decision string `json:"decision"` + Hit bool `json:"hit"` + Shadow bool `json:"shadow,omitempty"` + Items []CacheItemTrace `json:"items,omitempty"` + ShadowCompares []CacheShadowCompareTrace `json:"shadow_compares,omitempty"` +} + +// CacheItemTrace traces one item (or batch bucket) of a cached fetch. +type CacheItemTrace struct { + // Key is the item's rendered cache key, shared by L1 and L2; hashed when the + // policy sets HashAnalyticsKeys, omitted when the key could not render (then + // the item is a plain miss with no write). + Key string `json:"key,omitempty"` + // ServedFrom is "l1" or "l2" when the item was served from cache. + ServedFrom string `json:"served_from,omitempty"` + Hit bool `json:"hit"` + NegativeHit bool `json:"negative_hit,omitempty"` + // RemainingTTLNano is the served value's remaining TTL (L2 hits). + RemainingTTLNano int64 `json:"remaining_ttl_nanoseconds,omitempty"` +} + +// CacheShadowCompareTrace is one shadow staleness probe result. +type CacheShadowCompareTrace struct { + Key string `json:"key,omitempty"` + IsFresh bool `json:"is_fresh"` + CacheAgeNano int64 `json:"cache_age_nanoseconds"` +} + type LoadStats struct { GetConn GetConnStats `json:"get_conn"` GotConn GotConnStats `json:"got_conn"` diff --git a/v2/pkg/engine/resolve/fetchtree.go b/v2/pkg/engine/resolve/fetchtree.go index 8aa5c09909..f7b3d7610f 100644 --- a/v2/pkg/engine/resolve/fetchtree.go +++ b/v2/pkg/engine/resolve/fetchtree.go @@ -160,6 +160,9 @@ type FetchTreeQueryPlan struct { Representations []Representation `json:"representations,omitempty"` Query string `json:"query,omitempty"` Dependencies []FetchDependency `json:"dependencies,omitempty"` + // Cache is the fetch's cache config in its canonical one-line form; empty + // when the fetch is uncached, so plans without caching are unchanged. + Cache string `json:"cache,omitempty"` } func (n *FetchTreeNode) QueryPlan() *FetchTreeQueryPlanNode { @@ -196,6 +199,14 @@ func (n *FetchTreeNode) queryPlan() *FetchTreeQueryPlanNode { } switch n.Kind { case FetchTreeNodeKindSingle: + defer func() { + // The cache config reads through the Fetch interface (never a + // switch over concrete fetch types); an uncached fetch leaves the + // field empty and the plan output unchanged. + if queryPlan.Fetch != nil && n.Item.Fetch.CacheConfig() != nil { + queryPlan.Fetch.Cache = n.Item.Fetch.CacheConfig().String() + } + }() switch f := n.Item.Fetch.(type) { case *SingleFetch: queryPlan.Fetch = &FetchTreeQueryPlan{ @@ -346,6 +357,9 @@ func (p *PlanPrinter) printFetchInfo(fetch *FetchTreeQueryPlan) { if fetch.Representations != nil { p.printRepresentations(fetch.Representations) } + if fetch.Cache != "" { + p.print(fmt.Sprintf("Cache: %s", fetch.Cache)) + } p.printQuery(fetch.Query) p.depth-- diff --git a/v2/pkg/engine/resolve/loader.go b/v2/pkg/engine/resolve/loader.go index 61c04f2109..42f9a2b149 100644 --- a/v2/pkg/engine/resolve/loader.go +++ b/v2/pkg/engine/resolve/loader.go @@ -110,10 +110,25 @@ type result struct { // [item1, item3], // merge response[1] into item1 and item3 // // ] - batchStats [][]*astjson.Value + batchStats [][]*astjson.Value + // cachePartial marks a DecisionFetchPartial fetch: mergeResult stops after + // response/error processing and leaves the data merge to the cache hook + // (the reduced response is positionally misaligned with batchStats). + cachePartial bool fetchSkipped bool nestedMergeItems []*result + // response / responseData / responseHasErrors surface what mergeResult + // already computes to the cache merge hook: the FULL parsed response (the + // input isEmptyEntityFetch needs), the data sub-path (what a cache would + // persist), and the GraphQL-errors flag. response is assigned only after a + // successful parse, so response == nil is the structural fetch-failed + // signal (transport / empty body / parse failure). All three are dead + // weight when caching is off (written, never read). + response *astjson.Value + responseData *astjson.Value + responseHasErrors bool + statusCode int err error // subgraphError is THIS fetch's own subgraph error (errors.Join of res.err and @@ -141,6 +156,17 @@ type result struct { tools *batchEntityTools } +// responseHeaders returns the subgraph HTTP response's headers WITHOUT cloning +// — unlike newResponseInfo, whose value escapes to integrator hooks. The cache +// merge hook reads Cache-Control from them synchronously and retains nothing. +// nil when the fetch produced no HTTP response. +func (r *result) responseHeaders() http.Header { + if r.httpResponseContext == nil || r.httpResponseContext.Response == nil { + return nil + } + return r.httpResponseContext.Response.Header +} + func (r *result) init(postProcessing PostProcessingConfiguration, info *FetchInfo) { r.postProcessing = postProcessing if info != nil { @@ -394,10 +420,27 @@ func (l *Loader) resolveSingle(ctx context.Context, item *FetchItem) error { if prepared == nil { return nil } + // The two cache hooks bracket the network load and run OUTSIDE the phase + // locks, so the controller's CacheTransaction is the single DataBuffer.Lock + // acquisition around its arena work. Both are no-ops when no cache + // controller is set. + l.cachePrepare(prepared) + if prepared.batchAssembly != nil && !prepared.skipLoad { + var keep []bool + if prepared.cacheHandle != nil { + keep = prepared.cacheHandle.BatchFetchKeep + } + if err := l.assembleBatchInput(prepared, keep); err != nil { + return errors.WithStack(err) + } + } if err := l.loadPhase(ctx, prepared); err != nil { return errors.WithStack(err) } - return l.mergePhase(prepared) + if err := l.mergePhase(prepared); err != nil { + return errors.WithStack(err) + } + return l.cacheMerge(prepared) } type preparedFetch struct { @@ -409,6 +452,161 @@ type preparedFetch struct { trace *DataSourceLoadTrace skipLoad bool batchFetch bool + // batchAssembly defers the batch input assembly until AFTER the cache + // decision: the final input is rendered exactly once, containing only the + // representations the network fetch still needs (no parse-back filtering). + batchAssembly *batchInputAssembly + // cacheHandle is the opaque per-fetch cache state returned by PrepareFetch, + // threaded to the merge hook; nil when the controller did not touch the fetch. + cacheHandle *FetchCacheHandle +} + +// assembleBatchInput renders the FINAL batch input (the assembly filtered by +// keep, nil = all buckets), then runs the tracing-skip branch and the +// pre-fetch validation that operate on the final bytes. +func (l *Loader) assembleBatchInput(prepared *preparedFetch, keep []bool) error { + fetchInput, err := prepared.batchAssembly.assemble(prepared.res.tools.a, keep) + if err != nil { + return errors.WithStack(err) + } + + if l.ctx.TracingOptions.Enable && prepared.res.fetchSkipped { + l.setTracingInput(prepared.item, fetchInput, prepared.trace) + prepared.skipLoad = true + return nil + } + + allowed, err := l.validatePreFetch(fetchInput, prepared.item.Fetch.FetchInfo(), prepared.res) + if err != nil { + return err + } + if !allowed { + prepared.skipLoad = true + return nil + } + prepared.input = fetchInput + return nil +} + +// cacheRequest lazily obtains the request-lifetime cache working surface. The +// once-create runs under DataBuffer.Lock so it is race-free across the +// parallel fetches of a group and across per-defer-group Loaders (there is +// exactly one DataBuffer per request). It does NOT hold the lock across the +// hook: PrepareFetch / OnFetch* open their own CacheTransaction for arena work. +func (l *Loader) cacheRequest() RequestCache { + if l.ctx.cacheController == nil { + return nil + } + l.dataBuffer.Lock() + defer l.dataBuffer.Unlock() + if l.ctx.requestCache == nil { + l.ctx.requestCache = l.ctx.cacheController.BeginRequest(l.ctx) + } + return l.ctx.requestCache +} + +// cachePrepare is the pre-load cache hook: lookup + coverage + decision. It +// early-returns on every render-skip (a fetch the loader already decided to +// skip is not a cache decision) and when the fetch carries no cache config, so +// the no-controller / no-config path costs nothing. +func (l *Loader) cachePrepare(prepared *preparedFetch) { + if prepared == nil || prepared.skipLoad { + return + } + cfg := prepared.item.Fetch.CacheConfig() + if cfg == nil || (!cfg.L1 && !cfg.L2) { + // A fetch no cache layer touches still shapes what the CLIENT may be + // told about the response, so the surface hears about it. Gated on the + // controller like every other hook, which keeps the no-controller path + // free of cache code. + if rc := l.cacheRequest(); rc != nil { + rc.OnUncachedFetch() + } + return + } + rc := l.cacheRequest() + if rc == nil { + return + } + _, hash := l.ctx.HeadersForSubgraphRequest(prepared.res.ds.Name) + decision, handle := rc.PrepareFetch(PrepareFetchInput{ + Ctx: l.ctx, + Item: prepared.item, + Items: prepared.items, + Config: cfg, + BatchStats: prepared.res.batchStats, + Input: prepared.input, + HeaderHash: hash, + Arena: l.cacheTransactions(), + }) + prepared.cacheHandle = handle + switch decision { + case DecisionSkipFullHit: + // Full hit: skip the network AND the merge. skipLoad makes loadPhase + // early-return; fetchSkipped reuses the existing mergeResult early-return + // so no spurious "failed to fetch" error is rendered for the empty res.out. + prepared.skipLoad = true + prepared.res.fetchSkipped = true + if prepared.trace != nil { + // The ART trace reports the skipped load like every other skip. + prepared.trace.LoadSkipped = true + } + case DecisionFetchPartial: + // Partial: the batch input assembly (which runs after this hook) + // includes only the buckets handle.BatchFetchKeep marks, and the + // loader's own positional data merge is skipped — OnFetchResult + // splices the cached items and realigns + merges the fetched ones in + // a single hook (one lock acquisition). Error/response processing in + // mergeResult still runs unchanged. + prepared.res.cachePartial = true + default: + // DecisionFetch / DecisionFetchShadow leave the load in place; the + // handle drives the merge dispatch. + } +} + +// cacheMerge is the post-merge cache hook: write / skip-splice / shadow. It is +// gated only on the handle, so it never fires for fetches the controller did +// not touch. +func (l *Loader) cacheMerge(prepared *preparedFetch) error { + h := prepared.cacheHandle + if h == nil { + return nil + } + res := prepared.res + in := MergeInput{ + Item: prepared.item, + Items: prepared.items, + ResponseData: res.responseData, + BatchStats: res.batchStats, + MergePath: res.postProcessing.MergePath, + ResponseHeaders: res.responseHeaders(), + HasErrors: res.responseHasErrors, + FetchFailed: res.err != nil || len(res.out) == 0 || res.response == nil, + StatusCode: res.statusCode, + Arena: l.cacheTransactions(), + } + if res.response != nil { + // Only meaningful (and only nil-safe) when a response actually parsed; + // on a full-hit skip res.response is nil and EmptyEntity is irrelevant + // because cacheMerge dispatches to OnFetchSkipped, which ignores it. + in.EmptyEntity = isEmptyEntityFetch(prepared.item, res.response) + } + rc := l.cacheRequest() // already created during cachePrepare; non-nil because h != nil + switch h.Decision { + case DecisionSkipFullHit: + return rc.OnFetchSkipped(h, in) + default: // DecisionFetch, DecisionFetchShadow, DecisionFetchPartial + // The partial arm lives in OnFetchResult too: one hook call splices + // the cached items AND realigns + merges + writes the fetched ones. + return rc.OnFetchResult(h, in) + } +} + +// cacheTransactions returns the TransactionBeginner bound to this request's +// shared jsonArena and DataBuffer guard. Built only when a cache hook runs. +func (l *Loader) cacheTransactions() TransactionBeginner { + return cacheTransactionBeginner{a: l.jsonArena, db: l.dataBuffer} } func (l *Loader) shouldSkipErroredDependencyLocked(item *FetchItem) bool { @@ -633,6 +831,7 @@ func (l *Loader) mergeResult(fetchItem *FetchItem, res *result, items []*astjson } return l.renderErrorsFailedToFetch(fetchItem, res, invalidGraphQLResponse) } + res.response = response if l.allowCustomExtensionProperties { extensions := response.Get("extensions") @@ -648,6 +847,7 @@ func (l *Loader) mergeResult(fetchItem *FetchItem, res *result, items []*astjson } else { responseData = response } + res.responseData = responseData hasErrors := false @@ -678,6 +878,7 @@ func (l *Loader) mergeResult(fetchItem *FetchItem, res *result, items []*astjson } } } + res.responseHasErrors = hasErrors // Check if data needs processing. if res.postProcessing.SelectResponseDataPath != nil && astjson.ValueIsNull(responseData) { @@ -711,6 +912,13 @@ func (l *Loader) mergeResult(fetchItem *FetchItem, res *result, items []*astjson return nil } + if res.cachePartial { + // Partial fetch: response and errors are fully processed above; the + // cache hook owns the data merge (splice + realign), so the positional + // merge below must not run against the REDUCED response. + return nil + } + if len(items) == 0 { // If the data is set, it must be an object according to GraphQL over HTTP spec if responseData.Type() != astjson.TypeObject { @@ -1604,7 +1812,7 @@ var ( batchEntityToolPool = _batchEntityToolPool{} ) -func (l *Loader) prepareBatchEntityFetch(fetchItem *FetchItem, fetch *BatchEntityFetch, items []*astjson.Value, res *result, prepared *preparedFetch) error { +func (l *Loader) prepareBatchEntityFetch(_ *FetchItem, fetch *BatchEntityFetch, items []*astjson.Value, res *result, prepared *preparedFetch) error { res.init(fetch.PostProcessing, fetch.Info) if l.ctx.TracingOptions.Enable { @@ -1618,8 +1826,11 @@ func (l *Loader) prepareBatchEntityFetch(fetchItem *FetchItem, fetch *BatchEntit } res.tools = batchEntityToolPool.Get(len(items)) - preparedInput := arena.NewArenaBuffer(res.tools.a) + headerInput := arena.NewArenaBuffer(res.tools.a) + separatorInput := arena.NewArenaBuffer(res.tools.a) + footerInput := arena.NewArenaBuffer(res.tools.a) itemInput := arena.NewArenaBuffer(res.tools.a) + segments := arena.AllocateSlice[[]byte](res.tools.a, 0, len(items)) batchStats := arena.AllocateSlice[[]*astjson.Value](res.tools.a, 0, len(items)) defer func() { // we need to clear the batchStats slice to avoid memory corruption @@ -1635,12 +1846,14 @@ func (l *Loader) prepareBatchEntityFetch(fetchItem *FetchItem, fetch *BatchEntit // I tried using arena here, but it only worsened the situation var undefinedVariables []string - err := fetch.Input.Header.RenderAndCollectUndefinedVariables(l.ctx, nil, preparedInput, &undefinedVariables) + err := fetch.Input.Header.RenderAndCollectUndefinedVariables(l.ctx, nil, headerInput, &undefinedVariables) if err != nil { return errors.WithStack(err) } + if err = fetch.Input.Separator.Render(l.ctx, nil, separatorInput); err != nil { + return errors.WithStack(err) + } batchItemIndex := 0 - addSeparator := false WithNextItem: for i, item := range items { @@ -1671,14 +1884,13 @@ WithNextItem: batchStats[existingIndex] = arena.SliceAppend(res.tools.a, batchStats[existingIndex], items[i]) continue WithNextItem } else { - if addSeparator { - err = fetch.Input.Separator.Render(l.ctx, nil, preparedInput) - if err != nil { - return errors.WithStack(err) - } - } - _, _ = itemInput.WriteTo(preparedInput) - // new unique representation + // New unique representation: keep its rendered SEGMENT — the + // final input assembles AFTER the cache decision, so a partial + // hit sends only the still-missing representations without + // ever parsing the input back. + segment := arena.AllocateSlice[byte](res.tools.a, itemInput.Len(), itemInput.Len()) + copy(segment, itemInput.Bytes()) + segments = arena.SliceAppend(res.tools.a, segments, segment) res.tools.batchHashToIndex[itemHash] = batchItemIndex // A new targets bucket for the unique index must be allocated on the arena: // a heap-allocated bucket would only be referenced from arena memory, @@ -1687,7 +1899,6 @@ WithNextItem: bucket[0] = items[i] batchStats = arena.SliceAppend(res.tools.a, batchStats, bucket) batchItemIndex++ - addSeparator = true } } } @@ -1703,17 +1914,11 @@ WithNextItem: } } - err = fetch.Input.Footer.RenderAndCollectUndefinedVariables(l.ctx, nil, preparedInput, &undefinedVariables) + err = fetch.Input.Footer.RenderAndCollectUndefinedVariables(l.ctx, nil, footerInput, &undefinedVariables) if err != nil { return errors.WithStack(err) } - err = SetInputUndefinedVariables(preparedInput, undefinedVariables) - if err != nil { - return errors.WithStack(err) - } - - fetchInput := preparedInput.Bytes() // it's important to copy the *astjson.Value's off the arena to avoid memory corruption res.batchStats = make([][]*astjson.Value, len(batchStats)) for i := range batchStats { @@ -1721,23 +1926,18 @@ WithNextItem: copy(res.batchStats[i], batchStats[i]) } - if l.ctx.TracingOptions.Enable && res.fetchSkipped { - l.setTracingInput(fetchItem, fetchInput, fetch.Trace) - prepared.skipLoad = true - return nil - } - - allowed, err := l.validatePreFetch(fetchInput, fetch.Info, res) - if err != nil { - return err - } - if !allowed { - prepared.skipLoad = true - return nil + // The final input assembles in resolveSingle AFTER the cache decision + // (assembleBatchInput), so a partial hit renders only the still-missing + // representations; undefined-variable post-processing and the pre-fetch + // validation run there, on the final bytes. + prepared.batchAssembly = &batchInputAssembly{ + header: headerInput.Bytes(), + separator: separatorInput.Bytes(), + footer: footerInput.Bytes(), + segments: segments, + undefinedVariables: undefinedVariables, } - prepared.source = fetch.DataSource - prepared.input = fetchInput prepared.trace = fetch.Trace return nil } diff --git a/v2/pkg/engine/resolve/node_object.go b/v2/pkg/engine/resolve/node_object.go index 37790ed4f6..b9df04ef2f 100644 --- a/v2/pkg/engine/resolve/node_object.go +++ b/v2/pkg/engine/resolve/node_object.go @@ -13,6 +13,12 @@ type Object struct { PossibleTypes map[string]struct{} `json:"-"` SourceName string `json:"-"` TypeName string `json:"-"` + + // HasAliases marks that somewhere below this object a field carries an + // OriginalName or CacheArgs, i.e. the cached (schema-named) form differs + // from the query's shape and needs denormalization on read. Set by the + // caching planner walk. + HasAliases bool `json:"-"` } func (o *Object) Copy() Node { @@ -21,9 +27,10 @@ func (o *Object) Copy() Node { fields[i] = f.Copy() } return &Object{ - Nullable: o.Nullable, - Path: o.Path, - Fields: fields, + Nullable: o.Nullable, + Path: o.Path, + Fields: fields, + HasAliases: o.HasAliases, } } @@ -109,6 +116,28 @@ type Field struct { OnTypeNames [][]byte ParentOnTypeNames []ParentOnTypeNames Info *FieldInfo + + // OriginalName is the schema field name when Name is an alias; nil when the + // field is not aliased. The cache normalizes to OriginalName on write and + // denormalizes back to Name on read. Set by the caching planner walk. + OriginalName []byte `json:"-"` + + // CacheArgs are the field's arguments relevant to cache identity, used to + // build argument-suffix cache keys. Set by the caching planner walk. + CacheArgs []CacheFieldArg `json:"-"` + + // CacheEntityKeyField marks a representation-node field that came from the + // entity's `@key` selection set rather than a `@requires` one. The cache + // derives its per-entity invalidation tag from the key subset alone, so every + // variant of one entity shares that tag. Set by the representation-node + // builder; never set on response-tree fields. + CacheEntityKeyField bool `json:"-"` +} + +// CacheFieldArg names one field argument and the operation variable it is +// bound to, so the cache can render argument-suffix keys per request. +type CacheFieldArg struct { + Name, VariableName string } type ParentOnTypeNames struct { @@ -123,14 +152,51 @@ func (f *Field) Copy() *Field { deferField = &cp } return &Field{ - Name: f.Name, - Value: f.Value.Copy(), - Position: f.Position, - Defer: deferField, - Stream: f.Stream, - OnTypeNames: f.OnTypeNames, - Info: f.Info, + Name: f.Name, + Value: f.Value.Copy(), + Position: f.Position, + Defer: deferField, + Stream: f.Stream, + OnTypeNames: f.OnTypeNames, + ParentOnTypeNames: f.ParentOnTypeNames, + Info: f.Info, + OriginalName: f.OriginalName, + CacheArgs: slices.Clone(f.CacheArgs), + CacheEntityKeyField: f.CacheEntityKeyField, + } +} + +// ComputeHasAliases recursively checks whether any field below obj carries an +// OriginalName or CacheArgs (i.e. the cached, schema-named form differs from +// the query's shape) and sets HasAliases on EVERY object along the way, so the +// runtime denormalization has a per-object fast path. +func ComputeHasAliases(obj *Object) bool { + if obj == nil { + return false } + hasAliases := false + for _, field := range obj.Fields { + if field.OriginalName != nil || len(field.CacheArgs) > 0 { + hasAliases = true + } + if computeNodeHasAliases(field.Value) { + hasAliases = true + } + } + obj.HasAliases = hasAliases + return hasAliases +} + +func computeNodeHasAliases(node Node) bool { + switch n := node.(type) { + case *Object: + return ComputeHasAliases(n) + case *Array: + if n != nil && n.Item != nil { + return computeNodeHasAliases(n.Item) + } + } + return false } func (f *Field) Equals(n *Field) bool { diff --git a/v2/pkg/engine/resolve/resolve.go b/v2/pkg/engine/resolve/resolve.go index b51ff7b3b2..a38de8eb4c 100644 --- a/v2/pkg/engine/resolve/resolve.go +++ b/v2/pkg/engine/resolve/resolve.go @@ -360,6 +360,8 @@ type GraphQLResolveInfo struct { } func (r *Resolver) ResolveGraphQLResponse(ctx *Context, response *GraphQLResponse, data []byte, writer io.Writer) (*GraphQLResolveInfo, error) { + defer ctx.endCacheRequest() + resp := &GraphQLResolveInfo{} start := time.Now() @@ -393,6 +395,12 @@ func (r *Resolver) ResolveGraphQLResponse(ctx *Context, response *GraphQLRespons resolvable.skipValueCompletion = loader.skipValueCompletion } + if ctx.TracingOptions.Enable && ctx.TracingOptions.IncludeTraceOutputInResponseExtensions { + // The trace extension renders inside Resolve, before EndRequest can + // run — attach the cache traces now so it carries the cache sections. + ctx.flushCacheTraces() + } + responseResolveStart := time.Now() err = resolvable.Resolve(ctx.ctx, response.Data, response.Fetches, writer) resp.ResponseResolveStartTime = responseResolveStart @@ -407,6 +415,11 @@ func (r *Resolver) ResolveGraphQLResponse(ctx *Context, response *GraphQLRespons } func (r *Resolver) ArenaResolveGraphQLResponse(ctx *Context, response *GraphQLResponse, writer io.Writer) (*GraphQLResolveInfo, error) { + // Deferred BEFORE the arena acquire below, so EndRequest runs AFTER the + // arena is released — safe because EndRequest is arena-free by contract + // (see RequestCache.EndRequest). + defer ctx.endCacheRequest() + resp := &GraphQLResolveInfo{} inflight, err := r.inboundRequestSingleFlight.GetOrCreate(ctx, response) @@ -463,6 +476,13 @@ func (r *Resolver) ArenaResolveGraphQLResponse(ctx *Context, response *GraphQLRe resolvable.skipValueCompletion = loader.skipValueCompletion } + if ctx.TracingOptions.Enable && ctx.TracingOptions.IncludeTraceOutputInResponseExtensions { + // The trace extension renders inside Resolve, before EndRequest can + // run — attach the cache traces now so it carries the cache sections. + // FlushTraces shares EndRequest's no-arena contract. + ctx.flushCacheTraces() + } + // only when loading is done, acquire an arena for the response buffer responseArena := r.responseBufferPool.Acquire(ctx.Request.ID) buf := arena.NewArenaBuffer(responseArena.Arena) @@ -506,6 +526,15 @@ func (r *Resolver) ArenaResolveGraphQLResponse(ctx *Context, response *GraphQLRe } func (r *Resolver) ResolveGraphQLDeferResponse(ctx *Context, response *GraphQLDeferResponse, writer DeferResponseWriter) (*GraphQLResolveInfo, error) { + // EndRequest runs after the request arenas are released; it is arena-free + // by contract (see RequestCache.EndRequest). + defer ctx.endCacheRequest() + + // Marked before the first fetch, which is what lazily begins the request's + // cache surface: parts of this response resolve after the initial frame is + // written, so no client cache answer may be computed for it. + ctx.deferredResponse = true + resolveInfo := &GraphQLResolveInfo{} start := time.Now() @@ -920,6 +949,9 @@ func (r *Resolver) executeSubscriptionUpdate(resolveCtx *Context, sub *subscript defer cancel() resolveCtx = resolveCtx.WithContext(ctx) + // EndRequest runs after resolveArena is released back to the pool below; + // it is arena-free by contract (see RequestCache.EndRequest). + defer resolveCtx.endCacheRequest() // Copy the input. input := make([]byte, len(sharedInput)) diff --git a/v2/pkg/engine/resolve/response.go b/v2/pkg/engine/resolve/response.go index fb4b8db60b..bc43f4bf98 100644 --- a/v2/pkg/engine/resolve/response.go +++ b/v2/pkg/engine/resolve/response.go @@ -41,6 +41,24 @@ type GraphQLResponse struct { Info *GraphQLResponseInfo DataSources []DataSourceInfo + + // cacheProvidesData is the ProvidesData side-table the caching planner walk + // produces: per fetch (keyed by its *FetchInfo identity), the field tree the + // fetch returns. Kept OFF the response tree so defer's response-tree Copy + // never touches it; consumed by the caching postprocess passes. + cacheProvidesData map[*FetchInfo]*Object +} + +// SetCacheProvidesData attaches the caching planner walk's ProvidesData +// side-table to the response. +func (g *GraphQLResponse) SetCacheProvidesData(m map[*FetchInfo]*Object) { + g.cacheProvidesData = m +} + +// CacheProvidesData returns the ProvidesData side-table; nil when caching is +// not configured. +func (g *GraphQLResponse) CacheProvidesData() map[*FetchInfo]*Object { + return g.cacheProvidesData } func (g *GraphQLResponse) SingleFlightAllowed() bool { diff --git a/v2/pkg/engine/resolve/subgraph_request_singleflight_test.go b/v2/pkg/engine/resolve/subgraph_request_singleflight_test.go index b0b952e1ca..3757342511 100644 --- a/v2/pkg/engine/resolve/subgraph_request_singleflight_test.go +++ b/v2/pkg/engine/resolve/subgraph_request_singleflight_test.go @@ -23,6 +23,20 @@ func (s *stubFetch) FetchInfo() *FetchInfo { return s.info } +func (s *stubFetch) CacheConfig() *FetchCacheConfig { return nil } + +func (s *stubFetch) SetCacheConfig(*FetchCacheConfig) {} + +func (s *stubFetch) IsEntityFetch() bool { return false } + +func (s *stubFetch) IsBatchEntityFetch() bool { return false } + +func (s *stubFetch) RepresentationInputTemplate() *InputTemplate { return nil } + +func (s *stubFetch) SetDataSource(DataSource) {} + +func (s *stubFetch) LoadTrace() *DataSourceLoadTrace { return nil } + type nilInfoFetch struct{} func (n *nilInfoFetch) FetchKind() FetchKind { @@ -37,6 +51,20 @@ func (n *nilInfoFetch) FetchInfo() *FetchInfo { return nil } +func (n *nilInfoFetch) CacheConfig() *FetchCacheConfig { return nil } + +func (n *nilInfoFetch) SetCacheConfig(*FetchCacheConfig) {} + +func (n *nilInfoFetch) IsEntityFetch() bool { return false } + +func (n *nilInfoFetch) IsBatchEntityFetch() bool { return false } + +func (n *nilInfoFetch) RepresentationInputTemplate() *InputTemplate { return nil } + +func (n *nilInfoFetch) SetDataSource(DataSource) {} + +func (n *nilInfoFetch) LoadTrace() *DataSourceLoadTrace { return nil } + func newFetchItem(info *FetchInfo) *FetchItem { return &FetchItem{ Fetch: &stubFetch{ diff --git a/v2/pkg/engine/resolve/tainted_objects_test.go b/v2/pkg/engine/resolve/tainted_objects_test.go index a3948a7713..2b95769b03 100644 --- a/v2/pkg/engine/resolve/tainted_objects_test.go +++ b/v2/pkg/engine/resolve/tainted_objects_test.go @@ -353,3 +353,17 @@ func (m *mockFetchWithInfo) FetchKind() FetchKind { func (m *mockFetchWithInfo) Dependencies() *FetchDependencies { return nil } + +func (m *mockFetchWithInfo) LoadTrace() *DataSourceLoadTrace { return nil } + +func (m *mockFetchWithInfo) CacheConfig() *FetchCacheConfig { return nil } + +func (m *mockFetchWithInfo) SetCacheConfig(*FetchCacheConfig) {} + +func (m *mockFetchWithInfo) IsEntityFetch() bool { return false } + +func (m *mockFetchWithInfo) IsBatchEntityFetch() bool { return false } + +func (m *mockFetchWithInfo) RepresentationInputTemplate() *InputTemplate { return nil } + +func (m *mockFetchWithInfo) SetDataSource(DataSource) {} From 34cfc148b13871a66d33d4aeeeeab422d631e75a Mon Sep 17 00:00:00 2001 From: spetrunin Date: Tue, 11 Aug 2026 13:50:25 +0300 Subject: [PATCH 2/3] docs: record the selection-thrash and TTL-churn issues with the per-shape key direction Co-Authored-By: Claude Fable 5 --- docs/caching/6-open-issues.md | 56 ++++++++++++++++++++++++++++++++--- 1 file changed, 52 insertions(+), 4 deletions(-) diff --git a/docs/caching/6-open-issues.md b/docs/caching/6-open-issues.md index 6635ce5e56..a281021fce 100644 --- a/docs/caching/6-open-issues.md +++ b/docs/caching/6-open-issues.md @@ -20,6 +20,54 @@ 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. +## 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. +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): @@ -33,9 +81,9 @@ Belongs to the router/composition layer; the tag vocabulary already supports it. 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 v1 (`docs/caching/specs/2026-08-06-header-driven-caching.md` §4.1): 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 §10 client-header aggregation. +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 @@ -55,7 +103,7 @@ 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 per-policy CacheName usually separates them anyway), but decide and document. + 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` From bfded9e5472f6f16ff115d19ad6d595f069777dc Mon Sep 17 00:00:00 2001 From: spetrunin Date: Tue, 11 Aug 2026 13:52:48 +0300 Subject: [PATCH 3/3] docs: point the live-testing report at the suite's setup README Co-Authored-By: Claude Fable 5 --- docs/caching/5-testing-on-js-subgraphs.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/caching/5-testing-on-js-subgraphs.md b/docs/caching/5-testing-on-js-subgraphs.md index 0b5f37b416..dbb69c934d 100644 --- a/docs/caching/5-testing-on-js-subgraphs.md +++ b/docs/caching/5-testing-on-js-subgraphs.md @@ -9,6 +9,8 @@ including an independent rerun reproducing the correctness bug. - 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`),