Network & PerformanceBaseline · Widely

CDN Edge Cache Keys & Vary

Mental Model

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%.

Interactive Simulator

Edge Cache Key: Unnormalized vs Normalized

Compare naive full-URL + Vary: User-Agent keys against normalized CDN edge cache keys.

Lines of Code
Before
4
After
4
Reflows / Browser Cost
Before
8% Edge Hit Ratio
After
94% Edge Hit Ratio
BeforeFragmented Key (Low Hit Ratio)
// 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 edge
Lines: 4Reflows: 8% Edge Hit RatioDependencies: Origin flooded on traffic spikes

Thousands of User-Agent permutations create redundant origin fetches.

After (Native)Normalized Edge Key (High Hit Ratio)
// Strip tracking params & normalize Vary
Key = host + path + sortParams(allow=['page','sort'])
Vary: Accept-Encoding
Cache-Control: public, s-maxage=3600, stale-while-revalidate=60
Lines: 4Reflows: 94% Edge Hit RatioDependencies: Origin shielded at PoP

Shared 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.

  1. The edge node strips or sorts non-semantic query parameters (utm_*, gclid) before computing the lookup hash.
  2. It reads Vary headers (Accept-Encoding, Origin) to partition variants, crucial for Brotli & Compression Dictionaries.
  3. s-maxage overrides max-age exclusively for shared CDN caches, while stale-while-revalidate serves the expired entry immediately and refreshes asynchronously.
HTTP
Cache-Control: public, max-age=0, s-maxage=3600, stale-while-revalidate=86400
Vary: Accept-Encoding
CDN-Cache-Control: max-age=3600

Problem 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 over Cache-Control.

Production Pitfalls

Production Pitfall
  • Vary: User-Agent or Vary: Cookie: Explodes key cardinality across thousands of browser versions and session IDs, effectively disabling edge caching.
  • Caching personalized responses: Emitting s-maxage on a route that reads Cookie leaks one user's HTML to the next visitor at the same PoP.
When Not to Use
  • 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