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-store means don’t store it at all.
  • private means only private caches may store it. Shared caches also refuse responses to requests with Authorization unless public, s-maxage or must-revalidate allows 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), then max-age, then Expires - Date, then a heuristic. A common heuristic is 10% of the time since Last-Modified.
  • current_age is the response’s age when it arrived (which accounts for the Age header and network delay) plus the time it has sat in the cache. Caches send it to clients in the Age header.

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-Match with the ETag, or If-Modified-Since with Last-Modified.
    • 304 Not Modified means reuse the stored body and update its headers.
    • 200 means replace the stored response.
  • no-cache means the response may be stored but must be revalidated every time.
  • must-revalidate / proxy-revalidate mean 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-Location URIs when they’re on the same origin.

Cache-Control quick reference

DirectiveDirectionMeaning
max-age=Nbothfresh for N seconds (in a request: the oldest age the client will accept)
s-maxage=Nresponseoverrides max-age for shared caches
no-cachebothstore, but revalidate before every use
no-storebothdon’t store at all
private / publicresponseprivate caches only / any cache may store
must-revalidateresponsenever serve stale
no-transformbothintermediaries must not modify the body
max-stale, min-fresh, only-if-cachedrequestclient’s tolerance for stale or fresh responses, or cache-only
immutable, stale-while-revalidate, stale-if-errorresponseextensions 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-cache with an ETag. A 304 is cheap.
  • For a CDN-specific TTL, use s-maxage and keep browser max-age short.
  • If you forget Vary (for example Accept-Encoding), a cache can serve the wrong representation of a response.