CSE Roadmap

Core tier · about 3 hours · 8 parts

Part 5 of 8 · 2 min read

The cache key

What makes two requests the same request, and how one mistake splits a file into many copies.

Think of a coat check. The ticket number decides which coat is returned. If the clerk wrote a different number on each visit for the same coat, the coat could never be found again.

A cache stores each copy under a key and looks it up by the same key.

Cache key

A cache key is the set of values that must match for two requests to share one saved copy. By default it is the host name plus the path plus the query string.

Example: GET /logo.png on shop.example.com and GET /logo.png?x=1 on the same host have different keys by default, so they are two copies.

A worked example of a bad key. A marketing team adds tracking to links: /banner.jpg?utm=mail, /banner.jpg?utm=ad, /banner.jpg?utm=app, and so on, 50 variants in all.

  • The picture is the same. The keys are 50 different strings.
  • Each edge stores up to 50 copies, and each variant misses once at each edge.
  • With 200 edges: up to 200 × 50 = 10,000 misses for one file, against 200 with a clean key.
  • The hit ratio drops, and the origin sees 50 times the misses for this file.

The cure is to drop the parameters that do not change the file from the key. The query string is ignored, or only named parameters are kept.

Other values can enter the key on purpose.

  • Content encoding. A browser may accept compressed replies (gzip or Brotli), and another may not. The edge keeps a version for each, or compresses on the way out. The request header Accept-Encoding shows which.
  • Language. A page in English and a page in Hindi share a path. A header or a path prefix such as /hi/ separates them.
  • Device type. A mobile and desktop version of the same path, if the server sends different bytes.
  • Cookies. If cookies are part of the key, almost every user has a different cookie, so almost every request misses. Keep cookies out of the key for static files. Remove them from requests for static paths.

Vary

The Vary header lists the request headers that change the reply. A cache must treat requests with different values of those headers as different keys.

Example: Vary: Accept-Encoding tells caches to keep separate copies for gzip and for plain replies.

The rule: put in the key everything that changes the bytes, and nothing that does not.

Read it as

Too few things in the key, and users get the wrong file. Too many, and the cache never gets a hit.

Check yourself:

  • Why do tracking parameters hurt the hit ratio?
  • Why should a CDN not include a login cookie in the key for images?