Persisted Queries and CDN Caching

The Caching Problem Hiding in the POST Body

CDNs and browser caches are URL machines: they key on method and URL, store the body, and replay it. GraphQL violates both halves of that contract — nearly everything is a POST, and the document that determines the response lives in the request body, invisible to the cache key. The result is one endpoint that is uncacheable no matter how much infrastructure you put in front of it.

The obvious fix — send GET requests with the full query in the URL — fails three ways: URLs blow past proxy limits at a few kilobytes, query text leaks into access logs and Referer headers, and every distinct document string becomes a distinct cache key, so anyone can generate unlimited URLs and churn your cache.

Automatic persisted queries (APQ) fix the key problem by splitting the document from its identity. The client sends only a SHA-256 hash; the server looks it up:

GET /graphql?variables={"id":"p1"}
            &extensions={"persistedQuery":{"version":1,"sha256Hash":"9b4a..."}}

server: hash unknown
→ 200 { "errors": [{ "message": "PersistedQueryNotFound",
                     "extensions": { "code": "PersistedQueryNotFound" } }] }

client: retries with the full document attached
GET /graphql?query=query%20P(%24id%3A%20ID!)%7Bproduct(id%3A%24id)%7Bname%7D%7D
            &variables={"id":"p1"}
            &extensions={"persistedQuery":{"version":1,"sha256Hash":"9b4a..."}}

server: sha256(document) === 9b4a... → execute → 200 { "data": { ... } }

After the first exchange the hash is cached server-side, so steady-state traffic carries a few hundred bytes instead of the document, and the URL is short, stable, and identical for every execution of that operation. If the body arrives with a hash that does not match it, the server answers PersistedQueryMismatch and refuses to execute — a client bug or a tampered request, never a silent divergence.

From Automatic to Allowlisted

Here is the trap: APQ lets any client register any document by simply sending hash and body together. It saves bandwidth and it does nothing about an attacker submitting a 40KB document with its own hash. For safelisting you need the closed version of the same protocol — the server executes only hashes it already knows.

client sends hash only, server has no entry
→ PersistedQueryNotFound
   (strict mode: the server never asks for the body,
    so the operation simply does not exist)

The manifest is a build artifact, generated from the queries your clients actually ship:

import { createHash } from 'node:crypto';
import { readdirSync, readFileSync } from 'node:fs';

const manifest = {};
for (const file of readdirSync('./registered-queries')) {
  const doc = readFileSync('./registered-queries/' + file, 'utf8');
  const hash = createHash('sha256').update(doc).digest('hex');
  manifest[hash] = { document: doc, operationName: file.replace(/\.graphql$/, '') };
}
// deploy manifest with the server; clients keep only the hash + variables

Two rules make this survivable:

1. The hash must be computed over identical bytes on both sides. Normalize once (strip comments, collapse whitespace, pin field order) and normalize identically in CI and in the client build, or you will debug "hash never matches" for a day.
2. Ship the manifest before the client. A client sending hash-only requests to a server without the entry gets PersistedQueryNotFound on every call — the failure mode is total, not partial, so the ordering is release-order significant.

The payoff is bigger than security: a hash identifies an immutable document, so the URL for ProductPage never changes. That is what makes the next chapter work.

Cache Keys That Actually Hit

With hash-only GET requests, a CDN can finally store GraphQL responses. Getting a high hit ratio requires fixing the parts of the key that still vary:

Canonicalize variables before the URL reaches the CDN. JSON object key order is not stable across clients: {"a":1,"b":2} and {"b":2,"a":1} are one string apart in the URL and therefore two cache entries for one resource. Sort keys at the client (or at an edge worker) so the same logical request always produces the same URL.

Then decide what is shareable. A response containing me or recommendations is identity-dependent. The naive fix Vary: Authorization looks correct and destroys the cache, because the CDN now keeps one copy per token. The correct fix is in the response headers themselves:

• Public, identical for everyone: Cache-Control: public, max-age=600 — store it.
• Identity-dependent: Cache-Control: private, no-store — never store it, do not fragment the cache trying.

Only cache successful, data-bearing responses. A response with entries in errors[], a 200 with nulls after a subgraph timeout, or a cost rejection must not be replayed for its TTL — cache poisoning by error is the classic GraphQL CDN incident, and it is why Set-Cookie on a cacheable GraphQL response is an automatic disqualifier.

None of this applies to mutations, and subscriptions ride a different transport entirely — an SSE or WebSocket event has no URL to cache against, which is why realtime paths need their own delivery guarantees rather than cache headers. Deploy the same discipline across layers: the derivation rules in response caching strategy decide what a response's headers say; this topic decides which request URLs the CDN is allowed to store them under.