Build a CDN (13 scenes)
Scene 08

Cache key and Vary — when 'same URL' isn't

The cache key defaults to method + URL; the Vary response header adds request-header values to the key, multiplying entries per URL — and Vary: User-Agent shatters one cacheable response into thousands of near-duplicates.

Previously

Purge invalidates entries — but what determines which entries are matches in the first place? The cache key, and the Vary header that quietly multiplies it.

Scene 08

Cache key and Vary — when 'same URL' isn't

  1. Watch
  2. Try it
  3. Predict
  4. Capture
Vary:Encoding×3LanguageUser-AgentCookie/index.html1 URLENTRIES PER URL3distinct cached entries→CACHED ENTRIES · 2D KEY SPACEshowing 3 of 3gzipbridentityHIT RATIO95%0%100%MEMORY USED0.15 MB0cap 256 MB
Vary: Accept-Encoding — entries per URL = 3.
cache key = method + URLVary axes multiply the key1 URL → 3 entrieshit ratio · 95%memory used
What to watch for

Vary: Accept-Encoding only. Three entries per URL (gzip / br / identity). As requests pour in, the hit-ratio gauge climbs and memory stays low — every browser's encoding lands on one of the three cached entries.

Continue unlocks when the animation finishes.
Implementation

Highlighted lines are the ones running in the diagram right now.

Edge.compute_cache_key
URL is the default; Vary axes append request-header values
def compute_cache_key(req, vary):
    # the default identity: method + full URL
    key = req.method + ' ' + req.url
    # Vary tells the cache to also key on these headers
    for axis in vary:
        v = req.headers.get(axis, '')
        key += '|' + axis + '=' + v
    return hash(key)
Edge.vary_axes_for(url)
the axes the origin asked the cache to key on
def vary_axes_for(url):
    resp = cache.peek_response(url)
    # parsed from the origin's `Vary:` response header
    return resp.headers.get('Vary', '').split(',')
    # e.g. ['Accept-Encoding']            -> 3 entries
    #      ['Accept-Encoding','Accept-Language']  -> 24
    #      [...,'User-Agent']             -> ~5000+
Sources

Where this sits in Build a CDN

Scene 08 of 13, in the Control act — Purge flavors, the cache key, and the Vary footgun.. The cache key defaults to method + URL; Vary multiplies it by request-header values — Vary: User-Agent shatters one URL into thousands.

Up next. Even with a perfect cache key, a popular object expiring across hundreds of POPs at once stampedes origin — unless we put one POP between them.

All 13 scenes in Build a CDN · Every curriculum

Designs that use this

Built with Arqly
Every scene in Build a CDN builds on the one before it.All 13 Build a CDN scenes