CDN Edge Cache Keys & Vary
A CDN edge cache is a giant hash map keyed by scheme, host, path, query string, and Vary headers. Leave tracking parameters (?utm_*, ?fbclid=) or Vary: User-Agent in the key, and your 95% cache hit ratio quietly collapses to 8%.
Edge Cache Key: Unnormalized vs Normalized
Compare naive full-URL + Vary: User-Agent keys against normalized CDN edge cache keys.
// Default CDN key includes raw query + broad Vary
Key = host + path + "?utm_campaign=fall&fbclid=xyz99"
Vary: Accept-Encoding, User-Agent, Cookie
// Every user-agent string & ad click misses edgeThousands of User-Agent permutations create redundant origin fetches.
// Strip tracking params & normalize Vary
Key = host + path + sortParams(allow=['page','sort'])
Vary: Accept-Encoding
Cache-Control: public, s-maxage=3600, stale-while-revalidate=60Shared edge entry serves all visitors within milliseconds from nearest PoP.
Under the Hood
An edge PoP operates like a coat check with strict ticket numbers: if two visitors ask for /pricing and /pricing?utm_source=x, the default hash produces two different tickets and sends the second visitor to the origin server. Tuning HTTP Caching Directives at the edge means controlling both key cardinality and revalidation.
- The edge node strips or sorts non-semantic query parameters (
utm_*,gclid) before computing the lookup hash. - It reads
Varyheaders (Accept-Encoding,Origin) to partition variants, crucial for Brotli & Compression Dictionaries. s-maxageoverridesmax-ageexclusively for shared CDN caches, whilestale-while-revalidateserves the expired entry immediately and refreshes asynchronously.
Cache-Control: public, max-age=0, s-maxage=3600, stale-while-revalidate=86400
Vary: Accept-Encoding
CDN-Cache-Control: max-age=3600Problem Genealogy
- 2000s (Origin-Centric CDNs): Cached only
/images/*and/css/*by exact URL; dynamic HTML always hit origin. - 2014 (
Surrogate-Control&s-maxage): Separated browser TTL (max-age=0) from CDN TTL (s-maxage=3600) for instant invalidation. - 2022+ (RFC 9211
Cache-Status&CDN-Cache-Control): Standardized per-hop cache headers so origin, CDN, and browser stop fighting overCache-Control.
Production Pitfalls
Vary: User-AgentorVary: Cookie: Explodes key cardinality across thousands of browser versions and session IDs, effectively disabling edge caching.- Caching personalized responses: Emitting
s-maxageon a route that readsCookieleaks one user's HTML to the next visitor at the same PoP.
- When not to use edge caching: Never cache user-specific mutations, authenticated JSON endpoints, or CSRF-token HTML shells in shared CDN storage.
Connections & Logical Next Steps
Edge caches store rendered HTML and RSC payloads keyed by URL, Vary headers, and surrogate cache tags.
Shared edge caches obey s-maxage, stale-while-revalidate, and Vary directives.
Vary: Accept-Encoding prevents serving a Brotli or dictionary payload to incompatible clients.
Cache-Control, s-maxage, and Vary headers govern how CDN surrogates compute and partition edge cache keys.