Network & PerformanceBaseline · Widely

HTTP Caching Directives

Mental Model

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.

Interactive Simulator

HTTP Cache Freshness & Revalidation

Trace how the browser cache evaluates max-age, no-cache, ETag revalidation, and immutable assets.

Step 1 / 3: 1. Cache Key Lookup

Browser hashes URL + Vary headers + top-level site partition key to check the disk cache.

Cache-Control: public, max-age=31536000, immutable
Internal State / Memory
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.

  1. Before opening a stream over HTTP/2 & HTTP/3, the network stack computes a partitioned cache key (top-level-site + url + Vary).
  2. If the entry is fresh (age < max-age), the engine returns bytes from disk with zero network round-trips; immutable skips even user-triggered reload checks.
  3. If stale or marked no-cache, the client sends If-None-Match: "<etag>" and receives either 304 Not Modified (0 body bytes) or a fresh 200.
HTTP
# 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, immutable

Problem Genealogy

  • 1997 (HTTP/1.0 Expires & Pragma): Relied on absolute wall-clock timestamps, breaking whenever client clocks drifted.
  • 1999 (RFC 2616 Cache-Control): Introduced relative max-age and ETag validation, though developers routinely confused no-cache with no-store.
  • 2017+ (immutable & Partitioned Caches): Eliminated unnecessary 304 checks on reloads and isolated third-party cache keys per top-level site to block cross-site tracking.

Production Pitfalls

Production Pitfall
  • no-cache vs no-store confusion: no-cache still caches the response and revalidates; no-store forbids all storage and kills bfcache site-wide.
  • Missing Vary on content negotiation: Serving WebP and JPEG at the same URL without Vary: Accept poisons CDN Edge Cache Keys for unsupported browsers.
When Not to Use
  • When not to use immutable: Never attach immutable to unhashed URLs like /app.js or /avatar.png, users stay stuck on stale bytes until they clear site data.

Connections & Logical Next Steps

Seen in Architecture Autopsies

Mechanical Comparisons