RFC 9111: HTTP Caching (summary)
Full text: https://www.rfc-editor.org/rfc/rfc9111.html (replaces RFC 7234). The full clipping is in .trash/ if you want it back.
Related: Cache, Caching Basics & Mechanics, HTTP, REST, API
Core idea
- A cache stores responses and reuses them for later requests so it doesn’t have to go back to the origin.
- Private caches (browser) are for one user. Shared caches (CDN, proxy) serve many users, so the rules for them are stricter.
- The cache key is the request method + target URI, plus any request headers named in
Vary.
When a response can be stored
- The method must be cacheable (in practice usually GET) and the status code must be understood.
Cache-Control: no-storemeans don’t store it at all.privatemeans only private caches may store it. Shared caches also refuse responses to requests withAuthorizationunlesspublic,s-maxageormust-revalidateallows it.- It also needs freshness info (
max-age,Expires), or a status code that is cacheable by default (heuristic freshness).
Freshness
- fresh means
current_age < freshness_lifetime, and the response can be served without contacting the origin. - freshness_lifetime comes from, in priority order:
s-maxage(shared caches only), thenmax-age, thenExpires - Date, then a heuristic. A common heuristic is 10% of the time sinceLast-Modified. - current_age is the response’s age when it arrived (which accounts for the
Ageheader and network delay) plus the time it has sat in the cache. Caches send it to clients in theAgeheader.
Stale responses and validation
- A stale response normally has to be revalidated before reuse. The exception is when the client allows it (
max-stale) or the origin can’t be reached and nothing forbids serving stale. - Conditional requests:
If-None-Matchwith theETag, orIf-Modified-SincewithLast-Modified.304 Not Modifiedmeans reuse the stored body and update its headers.200means replace the stored response.
no-cachemeans the response may be stored but must be revalidated every time.must-revalidate/proxy-revalidatemean never serve it stale once it has expired.
Invalidation
- A successful unsafe request (POST, PUT, DELETE…) invalidates the stored responses for that URI, and for its
Location/Content-LocationURIs when they’re on the same origin.
Cache-Control quick reference
| Directive | Direction | Meaning |
|---|---|---|
max-age=N | both | fresh for N seconds (in a request: the oldest age the client will accept) |
s-maxage=N | response | overrides max-age for shared caches |
no-cache | both | store, but revalidate before every use |
no-store | both | don’t store at all |
private / public | response | private caches only / any cache may store |
must-revalidate | response | never serve stale |
no-transform | both | intermediaries must not modify the body |
max-stale, min-fresh, only-if-cached | request | client’s tolerance for stale or fresh responses, or cache-only |
immutable, stale-while-revalidate, stale-if-error | response | extensions defined in other RFCs, widely supported by CDNs |
Interview takeaways
- To cache static assets forever, use versioned file names with
max-age=31536000, immutable. - For HTML or API responses that should always be checked, use
no-cachewith anETag. A304is cheap. - For a CDN-specific TTL, use
s-maxageand keep browsermax-ageshort. - If you forget
Vary(for exampleAccept-Encoding), a cache can serve the wrong representation of a response.