A hands-on reference for response caching in GraphOS Router v2.19, covering GraphQL subgraphs and Apollo Connectors (REST). Each feature is a runnable scenario that prints PASS/FAIL, so you can use the repo as a live demo, a learning path, or a regression check before a Router upgrade.
docker compose up -d --build # everything runs in Docker
./scripts/run-all.sh # 12 scenarios, ~2.5 minutes
flowchart LR
C[Client app<br/>Apollo Client :5173] -->|GET / POST| R
S[Sandbox +<br/>cache debugger] --> R
R[GraphOS Router v2.19<br/>:4000 · invalidation :4005] <-->|response cache| Redis[(Redis)]
R --> SG[Subgraphs :4001<br/>products · inventory · reviews · accounts]
R -->|Apollo Connectors| REST[REST API :4010<br/>/brands · /promotions · /prices]
R -->|/metrics| P[Prometheus] --> G[Grafana :3000]
| Origin | Caching behavior it demonstrates |
|---|---|
products subgraph |
root fields (60s), entities (300s), @cacheTag, no-store field, error field, mutation that invalidates |
inventory subgraph |
short-lived entity data (10s): lowest TTL wins |
reviews subgraph |
Cache-Control: public without max-age → Router fallback TTL (45s) |
accounts subgraph |
PRIVATE data cached per user via private_id |
catalog connector |
REST TTL from headers, no-header fallback, entity connector, cache_key_headers, scoped invalidation |
Prerequisites: Docker, curl, jq, and a GraphOS graph API key (response caching is a GraphOS Router feature; Free and Developer plans work, with rate limits).
cp .env.example .env # add APOLLO_KEY, APOLLO_GRAPH_REF and two invalidation secrets
docker compose up -d --build
curl -s localhost:8088/health # {"status":"UP"}
./scripts/run-all.sh| URL | What |
|---|---|
| http://localhost:4000 | Apollo Sandbox (enable the cache debugger in settings) |
| http://localhost:5173 | Client app: which cache layer answered |
| http://localhost:3000 | Grafana "Response Cache" dashboard |
| http://localhost:5540 | RedisInsight: browse demo:* keys (connect to redis:6379) |
| http://localhost:4001/__stats | Subgraph call counters |
| http://localhost:4010/__stats | REST API call counters |
| # | Scenario | Shows |
|---|---|---|
| 01 | Root field caching | root fields cached as a unit; keyed by query + variables |
| 02 | Entity caching | per-entity reuse and partial hits (plus an operation-name gotcha) |
| 03 | Mixed TTLs | parts expire independently; the client gets the lowest TTL |
| 04 | Fallback TTL | where TTLs come from when the origin gives no max-age |
| 05 | Never cached | no-store, errors, mutations, Apollo Server defaults |
| 06 | Private data | scope: PRIVATE + private_id, per-user entries |
| 07 | Client cache control | client Cache-Control, Cache-Tag for CDNs, GET requests |
| 08 | Cache debugger | Sandbox debugger and the apollo-cache-debugging header |
| 09 | Invalidation | by tag, type and subgraph; mutation-driven invalidation |
| 10 | Connector caching | REST TTLs from headers, entity connectors, no-header fallback |
| 11 | Connector cache keys | cache_key_headers, connector invalidation scope and key |
| 12 | Observability | metrics, Prometheus queries, Grafana dashboard |
Run one: ./scenarios/03-mixed-ttls/run.sh
TTL
- Subgraphs: the
max-agefromCache-Control(Apollo Server derives it from@cacheControl). Nomax-age→ the configuredttl. No header at all → not cached. - Connectors: the REST API's
Cache-Control. No header at all → cached forttl, but the client getsno-store. - Client response: the lowest remaining TTL of every part. Any
privatepart →private. Any uncacheable part →no-store.
Cache keys
- Root fields: the full subgraph query + variables (+ private id, + custom key context).
- Entities: per representation, plus the subgraph query, which includes the generated operation name (scenario 02).
- Connectors: also the values of the headers in
cache_key_headers.
Never cached: mutations, responses with errors, no-store / max-age=0, private data without a private_id.
Invalidation: POST :4005/invalidation with kind = cache_tag | type | subgraph (subgraphs) or cache_tag (sources) | type (source) | connector (connectors). Separate shared keys per scope.
router/
router.yaml every response_cache setting, commented by scenario
supergraph.yaml composition config (federation 2.14, connect v0.4)
supergraph.graphql composed schema (committed, regenerate with scripts/compose-supergraph.sh)
rhai/main.rhai private_id from x-user-id + x-response-cache headers
subgraphs/ 4 Apollo Server 5 subgraphs in one Node process, with /__stats
connectors/catalog.graphql Apollo Connectors schema over rest-api/
rest-api/ Express REST mock with per-endpoint Cache-Control, with /__stats
client/ Vite + React + Apollo Client 4
observability/ Prometheus scrape config + provisioned Grafana dashboard
scenarios/NN-*/ README.md + run.sh per scenario
scripts/ lib.sh (helpers), run-all.sh, compose-supergraph.sh
- Schema change: edit the schema, run
./scripts/compose-supergraph.sh(needs Rover), thendocker compose up -d --build subgraphs. The Router hot-reloads the new supergraph. - Router config or Rhai: edit
router/. The Router hot-reloads. - Router version: change the image tag in
docker-compose.yamland run./scripts/run-all.shto catch behavior changes.
- Entity entries are scoped to the operation name (Router v2.19). Subgraph operations are named
<ClientOp>__<subgraph>__<n>, and that text is part of the entity cache key, so differently named client operations don't share entity entries. See scenario 02. - Apollo Server object fields default to
maxAge: 0. One un-hinted object field (Product.brand) made every product queryno-store. Fix:@cacheControl(inheritMaxAge: true). - Entity contributions need a type-level hint (
type Product @key(...) @cacheControl(maxAge: 10)), because_entitiesreturns a union. x-response-cache(Rhai) can't see connectors. Use the debugger or metrics for connector sources.- GET requests need
apollo-require-preflight(or another non-simple header). Otherwise the Router's CSRF protection returns 400.
-
debug: false - Invalidation endpoint on an internal network only; strong secrets from a secret manager
-
private_idfrom a verified JWT claim, not a header -
cache_key_headersreviewed for every connector source that forwards headers - Explicit
max-ageon everything you want cached;ttlas an upper bound - Redis sized and monitored (
fetch_timeout,insert_timeout,pool_size,required_to_start) - Hit-ratio and Redis-latency alerts (see the Grafana dashboard)