HTTP Caching Directives
Cache-Control governs whether the browser reuses a stored response directly, revalidates it with ETag for a 304 Not Modified, or skips storage entirely. Pair no-cache on HTML entrypoints with max-age=31536000, immutable on content-hashed static assets.
HTTP Cache Freshness & Revalidation
Trace how the browser cache evaluates max-age, no-cache, ETag revalidation, and immutable assets.
Browser hashes URL + Vary headers + top-level site partition key to check the disk cache.
Cache-Control: public, max-age=31536000, immutable- cacheEntryFound
- true
- networkPartition
- same-site
- requestSent
- false
Under the Hood
The HTTP disk cache works like a warehouse inventory ledger: every stored response carries an expiration timestamp (max-age) and a content fingerprint (ETag). Unlike bfcache, which snapshots live JS heaps in RAM, the HTTP cache only stores raw response bytes on disk.
- Before opening a stream over HTTP/2 & HTTP/3, the network stack computes a partitioned cache key (
top-level-site + url + Vary). - If the entry is fresh (
age < max-age), the engine returns bytes from disk with zero network round-trips;immutableskips even user-triggered reload checks. - If stale or marked
no-cache, the client sendsIf-None-Match: "<etag>"and receives either304 Not Modified(0 body bytes) or a fresh200.
# HTML document: store locally, always revalidate before reuse
Cache-Control: no-cache
ETag: "doc-8812a"
# Content-hashed bundle: never revalidate for 1 year
Cache-Control: public, max-age=31536000, immutableProblem Genealogy
- 1997 (HTTP/1.0
Expires&Pragma): Relied on absolute wall-clock timestamps, breaking whenever client clocks drifted. - 1999 (RFC 2616
Cache-Control): Introduced relativemax-ageandETagvalidation, though developers routinely confusedno-cachewithno-store. - 2017+ (
immutable& Partitioned Caches): Eliminated unnecessary304checks on reloads and isolated third-party cache keys per top-level site to block cross-site tracking.
Production Pitfalls
no-cachevsno-storeconfusion:no-cachestill caches the response and revalidates;no-storeforbids all storage and kills bfcache site-wide.- Missing
Varyon content negotiation: Serving WebP and JPEG at the same URL withoutVary: Acceptpoisons CDN Edge Cache Keys for unsupported browsers.
- When not to use
immutable: Never attachimmutableto unhashed URLs like/app.jsor/avatar.png, users stay stuck on stale bytes until they clear site data.
Connections & Logical Next Steps
Shared edge caches obey s-maxage, stale-while-revalidate, and Vary directives.
Shared dictionaries reuse cached HTTP responses and require Cache-Control + Vary headers.
ISR relies on s-maxage and stale-while-revalidate directives to serve cached HTML during background regeneration.
Client cache machines mirror HTTP Cache-Control stale-while-revalidate semantics in JavaScript heap memory.
sw.js itself must be served with no-cache so browser update checks detect new worker bytes.
Conditional 304 revalidations travel as lightweight header frames over multiplexed streams.
Cache-Control, s-maxage, and Vary headers govern how CDN surrogates compute and partition edge cache keys.
Disk cache stores raw HTTP bytes; no-store disables both disk cache and in-memory bfcache.