Vary and Cache Keys

## The problem it solves An HTTP cache stores a response and later replays it instead of contacting the origin. To know which stored response answers which request it needs a key. The default — the **primary cache key** — is the request method plus the target URL. That is enough only when a URL always produces the same bytes. Content negotiation breaks that. The same URL can legitimately return different representations depending on request headers: a gzip-compressed body for a client that sent `Accept-Encoding: gzip` and an uncompressed one otherwise; a German body for `Accept-Language: de`; JSON or XML depending on `Accept`. If the cache keyed only on the URL it would store whichever variant it saw first and hand it to everyone — compressed bytes to a client that cannot decompress them, German to an English speaker. ## Vary is the secondary cache key `Vary` is a **response** header carrying a comma-separated list of **request** header field names that the server consulted when selecting or generating this response. RFC 9111 calls those fields the secondary cache key. - **On store:** the cache saves the response plus the values those named headers had in the request that produced it. - **On lookup:** for a new request with the same primary key, the cache walks its stored variants. A variant is usable only if, for every field name in that variant's `Vary`, the new request's value matches the stored one. Matching is field-specific in theory; in practice most caches normalize whitespace and case and then compare bytes, which is why unnormalized values fragment the cache. - **On miss:** the request goes to the origin, and the new response may be stored as an additional variant under the same URL. `Vary: *` is special: it means selection depended on something not expressible as a header, so no stored response may ever be reused for a later request. ## Who sets it, who enforces it The origin server (or the reverse proxy/CDN acting for it) emits `Vary`. Every cache along the path enforces it: the browser's private cache, a corporate forward proxy, a shared CDN edge, a reverse proxy such as nginx or Varnish. It is not a request header — a client cannot ask a cache to vary on something — and it is advisory only in the sense that a broken intermediary may ignore it, which is one reason `no-store` rather than `Vary` is the tool for genuinely private data. ## Typical values `Accept-Encoding` (compression — the canonical case), `Accept-Language`, `Accept`, `Origin` (CORS reflection), `X-Device-Type` or similar normalized device buckets. Dangerous values are ones with huge cardinality — `User-Agent` and `Cookie` — because they approach a unique key per client. ## The cost model Every header added to `Vary` multiplies the number of stored variants for that URL: two encodings times three languages is six objects to fill, each with its own miss to the origin. Hit rate falls roughly with the product of the cardinalities. So the rule is: vary on exactly the headers that actually change the bytes, and normalize those headers to the smallest set of distinct values you can (for example, collapse any `Accept-Encoding` mentioning gzip to the single token `gzip`). ## Revalidation and 304 When a stored variant goes stale, the cache revalidates using a conditional request that carries the same varying headers as the original, so the origin selects the same variant. A `304 Not Modified` then refreshes that specific variant. Servers should send `Vary` on the 304 as well, and if the `Vary` value itself changes, caches treat previously stored variants as no longer matching. ## What it does not do `Vary` says nothing about *how long* something may be cached or *whether* it may be cached at all — that is the job of the freshness directives. `Vary` only decides *which* stored copy may answer *which* request.