Web and networkingDive 05 of 12
HTTP caching, down to the disk
Open a news article twice. Follow its HTML, JavaScript, logo and comments through freshness checks, validators, service workers and the back/forward cache to see which requests ever reach a server.
- Levels
- 9
- Reading
- 38 min
- Depth
- Idea to System
- Published
One article. Two visits. Which requests leave your device?
On the return visit, the bundle and logo stop locally. The article checks for edits. Comments appear immediately while a refresh runs behind them.
First visit · empty caches
/articles/cache/app.3f9c2a.js/logo.svg/api/comments?article=4245 seconds later · worker controls the page
/articles/cache/app.3f9c2a.js/logo.svg/api/comments?article=42Computed by the strategy model in level 7. Public CDN entries are initially empty; the article is private. Lanes show decisions, not elapsed time.
Four resources, four promises
You open a news article on the train. The headline arrives, the logo appears, the JavaScript makes the comments box work, and a JSON request brings in the latest conversation. A minute later you open the same article again. You want the same logo and program without paying to download them twice. You also want a correction to the headline and the comment posted ten seconds ago. Use the cache
is too vague a requirement: these four resources need four different promises.
Downloading fewer bytes saves bandwidth, but the larger win is often avoiding a round trip. Even a tiny request has to reach another machine and bring an answer back. On a mobile connection that can dominate the time spent transferring its body. A local copy can remove both costs; a conditional request removes most body bytes but keeps the round trip. At the publisher, reusing one public comments response for many readers also reduces database work and origin traffic.
A A stored response that may satisfy a later request under rules about identity, age and permission. is useful only if you can answer three questions. Does it belong to this request? Is reuse permitted? If so, can you trust it without asking anyone? HTTP separates those questions into keys, storage rules and freshness. A service worker adds your own program before the HTTP decision. A history restore can bypass the whole loading process.
Here is the policy for our news site. The article can contain a reader’s personal subscription controls, so a shared cache must not store it. The public comments endpoint contains the same moderated comments for every reader, with no personal fields. Posting a comment uses a separate authenticated request. That distinction makes the comments policy safe to share.
/articles/cacheCache-Control: private, no-cacheKeep a private copy; validate before using it again.
/app.3f9c2a.jsCache-Control: public, max-age=31536000, immutableA new deployment gets a new hashed filename; this URL stays unchanged for a year.
/logo.svgCache-Control: public, max-age=86400Reuse for one day; after that, validate with an ETag.
/api/comments?article=42Cache-Control: public, max-age=30, stale-while-revalidate=20, stale-if-error=60Reuse for 30 seconds; allow a short background refresh and a longer outage fallback.
There is more than one place to stop
A browser may retain resource objects in memory, including decoded images. Its HTTP cache may retain responses in memory or on disk. Your worker can keep a different copy in Cache Storage. Outside the device, a CDN can answer without contacting the origin. These are separate stores with different owners. The phrase from cache
does not tell you which one answered.
The figure below is an ownership map. It is not a mandatory pipeline: an active worker gets a fetch event and can return a response from Cache Storage; when it calls fetch(), the browser’s HTTP machinery runs beneath that call. A renderer’s reuse optimisations can avoid some lower-layer work. Memory and disk are often two tiers of the same HTTP cache, rather than two independent HTTP policies.
Document / renderer
Memory resources
Decoded images, resource objects and reusable bytes; implementation-specific lifetime and partitioning.
Your worker
Cache Storage
Storage key + named Cache + request URL; GET matching and the stored response’s Vary, unless explicitly ignored.
Browser network stack
HTTP cache
Network partition + method + target URI, then Vary selects the stored representation. Memory and disk are storage tiers.
Shared infrastructure
CDN / proxy
Configured host, path, query and variant inputs. It applies shared-cache rules, including s-maxage and private.
Publisher
Origin
Generates or retrieves the current article, bundle, logo and comments. Validators describe its selected representation.
Privacy changes the key
A browser once could reuse a third-party library downloaded by an unrelated site. That saved bandwidth but also created a history probe: a tracker could measure whether a resource was already cached. Network partitioning separates those copies by browsing context. Loading the same logo URL under two different top-level sites need not reuse one HTTP entry.
Chrome introduced HTTP cache partitioning in Chrome 86, with top-level site and current-frame site added to the key. Firefox 85, released in January 2021, partitioned network caches by top-level site. WebKit’s cache-partitioning work dates to 2013, earlier than those rollouts. The exact storage and network partition keys are browser policy; do not design a cross-site optimisation around a single global browser cache.
For our first-party article, all four URLs share one top-level site. Partitioning does not stop reuse between its own page loads. It changes what already downloaded
means when another site or embedded frame is involved. The Fetch Standard’s network partition key deliberately leaves part of that policy to implementations.
A cache hit is permission to reuse a particular stored representation in a particular context. The location of the bytes is only half the story.
How old is this response?
The logo’s promise says max-age=86400. For a day, the publisher allows a cache to reuse it without asking whether it changed. That period is the The period during which a stored response may be reused without validation, subject to other request and response constraints.. It begins with the response’s age, not with the instant you happen to save the file to disk. If a CDN already held a response for twenty seconds, the browser does not get a fresh twenty seconds for free.
RFC 9111 §4.2.1 chooses an explicit lifetime in order. A shared cache uses s-maxage if present. Otherwise it uses max-age. Otherwise Expires − Date gives an absolute expiration converted into a duration. A private browser cache ignores s-maxage. An explicit lifetime wins over a heuristic; max-age=0 does not invite the cache to invent a longer one.
Date is the message’s origination timestamp. Expires names an expiration date. Both are HTTP dates, such as Sun, 15 Nov 2026 10:00:00 GMT. Age is a nonnegative number of seconds estimating how long ago the response was generated or successfully validated. It accumulates through caches. It is not the file’s modification time and it is not the time spent on this device alone.
Missing and invalid dates need different handling from an omitted caching policy. Under RFC 9110 §6.6.1, a recipient with a clock that caches or forwards a response without Date must add a Date corresponding to receipt time. It may replace an invalid Date with receipt time as well; the calculator chooses that permitted policy. This supplies the date used for age and expiration arithmetic.
An invalid Expires value, including the literal header Expires: 0, means already expired under RFC 9111 §5.3. It is not an absent field and does not open the door to a heuristic lifetime. This matters only when Expires determines freshness: max-age still takes precedence, as does s-maxage in a shared cache. In the calculator, valid dates use relative numeric timestamps; the invalid-header option represents malformed wire values such as that literal zero.
Add the time already spent in transit
A browser knows when it sent the request, when it received the response and what time it is now. The origin and browser may disagree about the clock, so age cannot simply be now − Date. RFC 9111 §4.2.3 computes an apparent age from Date and an age estimate corrected for the request’s elapsed time. The conservative calculation takes their maximum, then adds the time resident in this cache. The RFC also permits using corrected_age_value directly when the response path’s caches implement HTTP/1.1 or later. Our calculator uses the conservative form.
agecurrent = ageinitial + tnow − tresponse
Valid header dates are represented as seconds relative to the request starting at t = 0. Choose missing or invalid header states to exercise recovery rules; a numeric time of 0 represents a parsed timestamp, not the literal header value "0".
With the starting values, the origin’s Date is twenty seconds before our request. The response arrives two seconds after it. Apparent age is 22 seconds; the corrected Age estimate is 5 + 2 = 7 seconds. Use the larger value, then add forty seconds resident time. The result is 62 seconds, so a private cache sees a stale response despite having stored it only forty seconds ago. A shared cache with s-maxage=120 can still consider it fresh.
A future Date makes apparent age zero, never negative. Network delay still counts through the corrected Age estimate. Freshness is a duration comparison with a strict inequality: lifetime must be greater than current age. No part of that arithmetic guarantees the entry exists; eviction, manual clearing and storage limits can remove a response before it expires.
When the publisher says nothing
A cache may estimate a lifetime only when explicit expiration is absent and the response is eligible for heuristic caching. Under RFC 9111 §4.2.2, eligibility requires a status defined as heuristically cacheable or an explicit cacheability permission, such as public. Other storage and reuse restrictions still apply. An unqualified private also permits a private cache to store a response that would not otherwise be heuristically cacheable; it grants no such permission to a shared cache.
RFC 9110 §15.1 lists 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 and 501 as heuristically cacheable status codes. An otherwise eligible GET response with status 200 or 404 can therefore receive a heuristic lifetime without an explicit expiration. An unmarked 500 cannot; public supplies explicit cacheability permission, subject to the remaining rules. A Last-Modified header alone does not grant that permission.
For eligible responses, RFC 9111 suggests a fraction of the interval since Last-Modified, with 10% as a typical setting. If a logo was last changed ten days before Date, that policy gives it roughly one day of freshness. Ten percent is a policy choice, not an interoperable promise. The calculator uses that policy and lets you compare 200, 404 and 500 with the same timestamps.
For our article, heuristics are irrelevant because no-cache requires validation. For the bundle, the explicit year wins. For the comments, thirty seconds wins even if the database row has not changed in a week. Set intentional headers instead of hoping an omitted policy produces the behavior you want. An invalid or repeated freshness directive can instead make a cache treat the response as stale; the lab chooses that conservative handling.
The cache spends one shared freshness budget, including upstream storage, response delay and local residence.
Read the promise, not the name
Freshness answers whether a response is young enough. Cache-Control answers whether storage and reuse are allowed at all. Its directive names are easy to misread. Our article’s no-cache permits storing a copy and asks for validation before reuse. no-store tells an HTTP cache not to store the message. A stored article plus an ETag can save the whole body transfer on the next visit even though its name contains no-cache
.
Request and response directives occupy the same header field but speak for different parties. A request’s max-age=0 limits the age the client is willing to accept. A response’s max-age=30 defines its freshness lifetime. A request’s no-cache asks for successful validation; a response’s no-cache imposes that requirement on subsequent reuse. Do not copy a response policy into a request and expect every directive to retain its meaning.
The field value is a list, not a string to split blindly on commas. Directive names are case-insensitive tokens. Arguments can be tokens or quoted strings; a quoted comma stays inside its argument, and a backslash can escape a quoted-string character. no-cache="Set-Cookie, X-User" is one directive with a two-field argument, not three directives. Repeated field lines are combined with a comma before parsing. The syntax comes from RFC 9110 §5.6.1 and §5.6.4; directive semantics live in RFC 9111 §5.2.
| Directive | Request | Response |
|---|---|---|
max-age=N | Maximum acceptable age | Freshness lifetime |
max-stale[=N] | Accept stale within a limit, subject to restrictions | Not defined |
min-fresh=N | Require N seconds of freshness remaining | Not defined |
only-if-cached | Use a stored response; otherwise cache returns 504 | Not defined |
no-cache | Validate before reuse | Validate before reuse; optional quoted field list |
no-store | Do not store request or response | Do not store response |
no-transform | Intermediaries must not transform content | Same prohibition |
public / private | Not defined | Explicit shared-storage permission / restriction |
s-maxage=N | Not defined | Shared-cache lifetime; implies proxy-revalidate |
must-revalidate | Not defined | Stale reuse requires successful validation |
proxy-revalidate | Not defined | The same stale restriction for shared caches |
must-understand | Not defined | Storage depends on understanding status-code requirements |
immutable | Not defined | No expected change while fresh; RFC 8246 |
stale-while-revalidate=N | Not defined | Extra window for background validation; RFC 5861 |
stale-if-error=N | Accept stale on specified errors | Allow stale on specified errors; RFC 5861 |
Permission is not a command to keep
public explicitly permits shared caching, including certain cases involving Authorization that would otherwise be restricted. It does not itself override no-store or force a CDN to allocate space; must-understand has its own specific override described below. private prevents shared storage of the response; the unqualified form still permits a private browser cache. Cookies alone are not a universal HTTP rule that forbids caching. The application must prevent a personalised representation from being served to another reader, and a CDN’s defaults may impose additional safeguards.
Qualified private="X-User" permits shared storage with the named fields excluded. Qualified no-cache="X-User" permits reuse of other parts without validation while restricting those fields. These forms are defined, but support is uneven. Our article uses the unqualified forms so that its body is private and every reuse validates. Removing a personal header would not make a personalised body safe to share.
must-revalidate matters after freshness expires. Until then it does not add a round trip. Once stale, the cache cannot choose an offline copy instead of successful validation; a disconnected cache returns an error, commonly 504. proxy-revalidate applies this rule only to shared caches. s-maxage also carries that shared stale-reuse restriction. These rules matter when you combine directives: an extension window does not erase a prohibition on stale reuse.
immutable, defined in RFC 8246, makes the bundle’s content-addressed URL useful: while fresh, the representation is not expected to change. Deploy app.7bd412.js when bytes change and update the article’s reference. Overwriting app.3f9c2a.js breaks your own promise. Reload and force-reload behavior also depends on browser policy and request cache mode; immutable is not permanent immunity from the network.
no-transform restricts intermediaries’ changes to the representation, such as image recompression; it does not set a lifetime. must-understand limits storage to caches that understand and implement the response status code’s caching requirements. It is normally paired with no-store: a cache implementing must-understand should ignore no-store when it has that status-code understanding, while no-store remains the fallback for caches lacking it. Unknown extension directives are ignored rather than guessed from their names.
Ask whether the bytes changed
Our private article is stored, but it cannot be reused without validation. The browser asks the origin a smaller question than send the article
: is this still the representation I have?
If the answer is yes, a 304 Not Modified carries metadata and no representation body. The browser keeps the stored body and updates the applicable fields. The request still used the network.
An An opaque entity-tag generated by the server to distinguish representations. Its content is meaningful only to the server that assigns it. is an opaque quoted value such as "article-v2". It need not be a hash, timestamp or revision number, though any of those might help a server generate it. Clients must not interpret the inside. A strong tag promises representation-data identity for strong comparison. A weak tag, prefixed with uppercase W/, can group representations the server considers semantically equivalent despite byte differences.
Weak tags work for cache validation: if the publisher considers today’s whitespace-only HTML rewrite equivalent, it can retain a weak tag. They cannot safely stitch together byte ranges, because offsets into different byte sequences do not identify the same data. Content coding matters too: a gzip and an identity representation need distinct strong tags when their representation data differs. RFC 9110 §8.8.3 defines both comparison functions.
| Tag A | Tag B | Weak comparison | Strong comparison |
|---|---|---|---|
"v2" | "v2" | Match | Match |
W/"v2" | "v2" | Match | No match |
W/"v2" | W/"v2" | Match | No match |
"V2" | "v2" | No match | No match |
Last-Modified provides a date validator at one-second resolution. The client sends it as If-Modified-Since. If the selected representation has not changed since that time, GET or HEAD can receive 304. Rapid edits within one second, clock issues and dynamically assembled pages make dates less expressive than server-chosen tags. Recipients ignore invalid date conditions; the simulator uses numeric second timestamps so that you can focus on ordering without typing date strings.
The browser can send both validators. They are not combined as two equal votes. If-None-Match takes precedence over If-Modified-Since: if the tag differs, the server does normal processing even when the date would have said unchanged. Before either, an origin evaluates If-Match and, when If-Match is absent, If-Unmodified-Since. Those preconditions protect writes against lost updates. RFC 9110 §13.2.2 gives the order.
GET /articles/cache HTTP/1.1
Host: news.example
If-None-Match: "article-v2"
If-Modified-Since: Sun, 15 Nov 2026 10:00:00 GMT
HTTP/1.1 304 Not Modified
Date: Sun, 15 Nov 2026 10:01:00 GMT
ETag: "article-v2"
Cache-Control: private, no-cache
Vary: Accept-EncodingOrigin simulator: normal handling would succeed, no previously completed write, one selected representation, a satisfiable Range, and Last-Modified usable as a strong date validator for If-Range.
Stored article: ETag "article-v2", Date 10:00:00 GMT, Cache-Control private, no-cache, 24,000 body bytes. A 304 uses the origin ETag above and Date 10:01:00 GMT.
Why the method changes the answer
If-Match uses strong comparison. A false condition normally produces 412 Precondition Failed, protecting a PUT from overwriting a newer edit. If-Match suppresses If-Unmodified-Since because the tag is the more precise condition. If neither blocks the request, If-None-Match uses weak comparison. A match produces 304 for GET or HEAD, but 412 for other methods. The wildcard * tests existence: If-None-Match: * is useful for create only if absent
.
Only after those preconditions pass does an eligible GET evaluate Range and If-Range. If-Range is permission to send a requested partial body only if the representation still matches. Its entity-tag comparison must be strong; its date comparison is exact and requires a usable strong date validator. If it fails, send the entire representation, not 412. The simulator assumes a satisfiable range and ordinary successful processing; real servers first handle redirects, authentication and ordinary request errors, and can recognise an already completed write.
A 304 updates a representation, not every file with that URL
When the cache receives 304, it identifies the eligible stored responses according to RFC 9111 §4.3.4. A strong validator can identify all corresponding stored responses; a weak validator identifies the most recent matching one. Without validators, the narrow validator-free single-entry case applies. A 304 with a strong validator that matches none of the candidates must not freshen an unrelated stored body.
For an identified response, §3.2 adds supplied header fields and replaces their stored values, with exceptions for fields excluded from storage, fields that would break the stored response’s interpretation, automatically removed fields and Content-Length. Date, Cache-Control, ETag and Vary can therefore refresh the cache’s metadata. Fields absent from the 304 are generally retained. Age is recalculated using the validation exchange; it is not blindly reset by changing a file’s timestamp.
Our article’s new metadata can still say no-cache, so validation permits this reuse without granting sixty seconds of unconditional reuse. DevTools may show 304 for the wire transaction while JavaScript receives a normal response containing the stored body. That difference is the cache doing its job, not a missing body. If the origin instead returns 200, the new body answers the request and may replace the entry under the normal storage rules.
Validation saves the body transfer. Freshness saves the request. Preconditions decide when either promise can be trusted.
The URL is only part of the key
You have permission to reuse the logo and its age is within one day. There is one remaining question: which logo? A URL can produce several representations. A CDN might return Brotli to one browser and gzip to another. An article might negotiate language. Reusing the wrong variant is a correctness bug even when every timestamp is perfect.
RFC 9111 §2 describes a cache key that includes at least the method and target URI; common GET caches use the URI as their primary lookup. Vary tells the cache which request fields selected the representation. With Vary: Accept-Encoding, the request that stored a gzip article and the later request must agree on the selecting field under the field’s permitted normalisation rules.
Vary: * always fails a reuse comparison. A cache cannot infer the selection criteria from a finite list of fields, so it cannot decide that a later request matches. A missing selecting field matches another missing field, not any value. Header names are case-insensitive; header values are only equivalent where that field’s own syntax permits it. Accept-Language: en is not interchangeable with fr just because both are text.
Normalise carefully. Header field names can be lowercased, and some field whitespace or list order can be normalised without changing meaning. Query parameter order, case-sensitive path segments, percent-encoded path bytes and duplicated parameters may change an application’s meaning. A CDN that drops a query from its key while forwarding it to the origin can serve one reader’s response to another request. The cache key and the origin’s selection logic must agree.
Cache Storage query against a GET for https://news.example/logo.svg?v=1, stored with Accept-Language: en. The named Cache is already selected.
This matcher is the Cache Storage API query used later by our worker. Its Vary comparison uses the stored request’s header value and the new request’s value after Fetch’s header normalisation: leading and trailing HTTP whitespace is stripped, and duplicate field values are combined with a comma and space. It does not automatically perform every semantic normalisation an HTTP cache may use: en and EN still compare as different values in this query. ignoreVary: true deliberately skips the variant check. That can be correct for an application-controlled key, but it can also turn a French response into an English reader’s offline fallback.
Similarly, ignoreSearch ignores the whole query, not merely an analytics parameter you dislike. Enabling it for our comments URL could make article 42 receive article 43’s comments. ignoreMethod skips the request-method guard; it does not make storing POST entries with Cache.put valid. These options change a query against an existing cache, not the fundamental put rules.
A CDN has its own key and its own eviction controls
Shared caches often let operators configure additional key inputs or a custom key. Include scheme, host and the inputs that actually affect the response. Avoid Vary: Cookie as a casual solution: whole Cookie values create huge variant sets, and omitting the right private distinction can leak data. For our article, the simple policy is to keep it private. The public comments representation deliberately excludes authentication state.
A An operator-defined tag that groups several CDN entries for invalidation. It is not the HTTP request’s primary cache key. groups entries for purge. Tag the article’s public fragments and related comment entries with a story identifier and invalidate that group on moderation. A purge tag does not decide which representation answers a request. Its header names, limits and propagation guarantees are CDN-specific. Purging the CDN also does not reach back into every reader’s browser, where a fresh response can still be reused.
That is why hashed bundle URLs work so well. Deployment publishes a new key rather than trying to find and erase every old copy. The article’s validation brings in the new reference, and the old bundle can expire naturally. Retain old assets long enough for open pages and older workers that still refer to them; deleting last deployment’s bundle immediately can break a reader whose HTML outlives your release.
Clear the store you intend to clear
Clear-Site-Data is a response header for asking a supporting browser to clear categories of site data. Its quoted "cache" and "storage" types address different categories: storage includes service-worker registrations and application storage. Exact supported types and scope vary by browser. It is not a CDN purge protocol, and receiving it is itself a network event.
A worker can delete a named cache with caches.delete(), but that does not clear HTTP cache entries. Unregistering a worker does not automatically delete all its Cache Storage. Logging out therefore needs an explicit application policy for private offline data, active clients and server authentication. The news site avoids writing personalised article bodies to a long-lived shared device cache unless that offline behavior is intentional.
Every input that changes a response must be reflected in selection or excluded from shared caching. Purge tags and URL keys solve different problems.
Spend a little staleness
The comments API has a different bargain. A reader can tolerate comments that are a few seconds old, but a slow origin should not hold the whole conversation panel blank. Its header gives thirty seconds of freshness, twenty additional seconds of stale-while-revalidate and sixty additional seconds of stale-if-error. The two extra windows both start at the freshness boundary; they are not added end to end.
RFC 5861 §3 permits a cache to serve a stale response during the stale-while-revalidate window while it attempts validation asynchronously. A request at age 35 can get the existing comments immediately and trigger a refresh. If that refresh completes at age 39, subsequent requests use the validated response with an age calculated from that exchange. If no reader asks during the window, nothing has to refresh in the background.
Once the allowed background window is over, an incoming request must wait for ordinary validation or another applicable policy. Stale-while-revalidate is not a periodic polling instruction and it does not guarantee that no one ever waits. A low-traffic story can sit untouched for ten minutes and make its next reader pay the round trip. Under load, caches often collapse concurrent requests for one entry so that a single validation serves the waiting readers.
RFC 5861 §4 addresses a different failure: an attempted request gets a qualifying error. It allows reuse within the stale-if-error allowance. The specified HTTP error statuses are 500, 502, 503 and 504; network failures such as DNS or connection trouble can lead to those error situations. A 404 is not a licence to serve the deleted story indefinitely. Successful revalidation ends the outage fallback by making a usable response current again.
Comments · max-age=30, stale-while-revalidate=20, stale-if-error=60
- Fresh
- Background validation
- Blocking validation
- Error
- Stale after error
Linear 0–180 s axis. A filled band marks the 503 outage; each tick is an arriving request. Concurrent validations are collapsed for this one cache key. No timer refreshes an idle entry.
Count staleness from the same boundary
Our comments entry becomes stale at age 30. Its background allowance runs through age 50. Its error allowance runs through age 90. At age 70, it cannot be served merely to hide an ordinary slow success, but it can be served after a qualifying failed validation. At age 91, the error allowance is exhausted, so the error reaches the reader. The UI can show a retry affordance and retain already displayed content as application state, but that is a separate choice from HTTP reuse.
The timeline starts with a validated entry at t = 0. It tracks a single cache key, one in-flight validation and a configurable origin response delay. The validating origin timestamps at request arrival, so the response delay counts toward its initial age. Request arrivals are fixed on the 0–180 second time axis. The cache collapses work for this model; RFC 5861 does not require a particular request-collapsing implementation. Responses are unchanged, so each successful validation refreshes metadata instead of introducing a new comments version.
A long origin delay can run beyond the background allowance. Requests inside the window can receive stale immediately; later arrivals wait on the pending validation. If that validation fails, stale-if-error is checked against the age when the error becomes known. This is why a latency control changes availability as well as speed: a response can age out while a request is still in flight.
Stale permission still has limits
RFC 9111 §4.2.4 prohibits stale reuse where another applicable directive forbids it, including no-cache, must-revalidate and, in shared caches, proxy-revalidate or s-maxage’s implied restriction. Do not attach an optimistic stale window to an incompatible policy and assume the window wins. The comments policy deliberately has no such prohibition.
Support and operational policy still matter. A cache may ignore an unknown extension; an operator can choose a smaller stale allowance. A CDN may implement background refresh and error fallback differently from a browser. The headers state permission and limits, not a promise that every implementation will exercise all permitted behavior. Observe your actual edge and browser rather than treating one trace as a universal rule.
Stale responses also retain age information. A cache must not make old data look freshly generated simply because it decided to serve it again. RFC 5861’s historical examples include Warning fields under the older caching specification; RFC 9111 obsoleted Warning. Modern traces should be read using the current Age and caching rules, without copying obsolete Warning requirements into new implementations.
Background refresh spends staleness to hide latency. Error fallback spends staleness to preserve availability. Both allowances have an end.
Put a program in the request path
HTTP gives the publisher a declarative contract. A service worker lets the application run code when a controlled client makes a request. It can return an offline article, synthesise a response, consult Cache Storage or call Fetch. The worker runs in an event-driven context that the browser can terminate between events; its global variables are not a durable database.
The critical distinction is that cache.match() and fetch() address different systems. Cache Storage holds explicit Request/Response pairs that your program writes. Its match operation does not enforce Cache-Control freshness or automatically expire a response after max-age. Fetch invokes HTTP caching beneath the worker, so a network-first
strategy can call fetch and still receive a fresh HTTP cache entry without sending a packet.
For the news site, we choose network-first for article navigation, cache-first for the hashed bundle, cache-first for the logo and worker stale-while-revalidate for comments. The article’s offline fallback is an explicit product decision and must exclude private subscription content in a real deployment. The bundle never changes at its hashed URL. The logo can become old in Cache Storage unless our worker expires or versions its copy. Comments update on every worker fetch event even when the HTTP entry underneath is fresh.
Blocking delay · linear 0–3000 ms
Simulated GETs in same-origin mode, with cacheable 200s and an unchanged validator. 120 ms normal or 3000 ms slow fetch; offline rejects at 120 ms. No timeout race. Comments also apply their HTTP stale windows. Worker SWR always calls fetch, including when the HTTP entry is fresh.
Cache Storage is a programmable response store
caches.open("news-v2") selects a named cache in the application’s storage context. cache.match(request) normally requires GET, matches URL including query, ignores the fragment and honours the stored response’s Vary fields. It does not ignore Vary by default. The matcher in level 5 exposes the three query options rather than hiding them behind a library.
Cache.put() accepts suitable HTTP(S) GET request keys and a response; it rejects a 206 response, Vary: * and unusable bodies, among other invalid inputs. It does not reject a response merely because Cache-Control says no-store. An opaque response can be stored with put, while add/addAll require a successful response and have their own checks. Opaque responses cannot be inspected like same-origin responses, which complicates error and quota handling.
Request and response bodies are streams. Returning a response and saving it usually requires a clone before either consumer drains the body. Storage can fail from quota or eviction. A successful network response should still reach the reader when an offline-copy write fails. Conversely, fetch rejects on network failure but resolves for HTTP 404 or 503; a strategy that falls back only in catch will return those HTTP errors. Our strategy simulator’s offline switch models a rejection, not an HTTP 503. The HTTP stale timeline models the latter.
A fetch handler must call event.respondWith() synchronously during event dispatch, passing a promise if the answer will arrive later. Extend background work with event.waitUntil(); do not assume a fire-and-forget promise keeps the worker alive. Always settle the response promise, catch expected failures, and define what happens when neither store nor network can answer. The following network-first skeleton awaits its cache write so the work remains within the response lifetime.
// A GET-only, same-origin network-first handler.
self.addEventListener("fetch", (event) => {
const request = event.request;
if (request.method !== "GET") return;
if (new URL(request.url).origin !== self.location.origin) return;
const response = (async () => {
const cache = await caches.open("news-v2").catch((error) => {
console.warn("Offline storage unavailable", error);
return null;
});
try {
const fresh = await fetch(request);
if (fresh.ok && cache) {
try {
await cache.put(request, fresh.clone());
} catch (error) {
// Storage failure must not discard a usable network response.
console.warn("Offline copy could not be saved", error);
}
}
return fresh;
} catch (error) {
const fallback = cache
? await cache.match(request).catch(() => undefined)
: undefined;
if (fallback) return fallback;
throw error;
}
})();
event.respondWith(response);
});| Fetch cache mode | HTTP entry lookup | Network and storage |
|---|---|---|
default | Reuse fresh; use applicable stale permission | Otherwise validate or fetch; store eligible responses |
no-cache | Find a validation candidate | Validate even if fresh; update entry |
reload | Bypass lookup | Fetch and update eligible entry |
no-store | Bypass lookup | Fetch without HTTP cache storage |
force-cache | Reuse a matching entry without regard to staleness | Fetch and store on miss |
only-if-cached | Reuse a matching entry without regard to staleness | Network error on miss; requires same-origin mode |
These are the Fetch Standard’s request cache modes, not all literal Cache-Control field values. In particular, Fetch’s only-if-cached miss is a network error, while the HTTP request directive describes a cache-generated 504. None of these modes asks your service worker to bypass its own Cache Storage lookup; your handler must decide what to do with the request.
Installing a worker is not replacing the running page
Registration associates a script with a scope. A new worker installs, waits and then activates. Installation’s waitUntil promise can prepare offline assets; rejecting it prevents the new worker from becoming the successful replacement. An update normally waits while clients still use the old registration’s active worker. This prevents an old article from unexpectedly talking to a new worker with an incompatible data format.
Version A controls one article. A second page in scope was loaded before registration and is still uncontrolled. Version B has new script bytes.
Install B to start the update.
skipWaiting() lets a waiting worker proceed to activation while existing clients use the registration. Those clients can switch controller; their already loaded HTML and JavaScript do not magically change. clients.claim() lets an active worker take control of eligible uncontrolled clients within scope. It does not reload their resources. Treat both as version-coordination decisions, not mandatory boilerplate.
The browser checks worker scripts for updates and compares relevant script bytes. A new response with identical bytes does not create a new worker merely because its Date changed. updateViaCache controls HTTP cache use for script update fetches: the default imports allows cache use for imports while checking the top-level script; all allows it for both and none forces validation for both. The update algorithm also forces revalidation when a registration is stale, defined as more than 86,400 seconds since its last update check. This is not a guaranteed background poll every twenty-four hours; a check still needs a trigger. See the Service Worker Update algorithm.
Navigation preload can start a navigation’s fetch while the browser starts the worker, overlapping the startup cost. The handler consumes event.preloadResponse rather than issuing a duplicate request. Preload uses the network stack and its cache rules; it is not an additional persistent store. A server can recognise its preload header and choose an appropriate response, taking care that any selection difference has a correct Vary policy.
Bring the entire page back
You follow a link from the article to another story, then press Back. Sometimes the page returns instantly with the comments expanded, the text selection intact and JavaScript variables unchanged. No sequence of 304 responses reconstructs that state. The browser has retained the entire document in the A browser-managed snapshot of a live page, including DOM and JavaScript heap, suspended for possible history restoration., usually shortened to bfcache.
An HTTP cache stores responses. The bfcache preserves a page’s execution state in memory and pauses it. Restoring it resumes that document rather than loading a new HTML response and rerunning its scripts. The bundle, decoded logo and existing comments can remain part of that retained page. Ordinary initial loading and pressing Reload still take different paths; not every history navigation is eligible or retained.
The distinction matters for correctness. A comments panel that was current when you left may be old when you return. Startup code does not rerun on a restore. Listen for pageshow and inspect event.persisted. Reconcile time-sensitive UI and authentication state there, using the same server-side access checks you need on every request. A restored document is not proof that the user is still signed in.
Eligibility is a browser policy
Pages can be ineligible because they hold resources or use APIs the browser cannot safely suspend. Retention can also end under memory pressure. Avoid unload handlers: they are unreliable lifecycle signals and can block bfcache in browser-dependent circumstances. Use pagehide and visibility changes for appropriate lifecycle work, and use beforeunload only when there are unsaved changes that actually need a prompt. A permanent handler is a cost paid by every reader.
The old advice that Cache-Control: no-store always blocks bfcache is no longer a correct Chrome rule. Chrome’s documented 2025 rollout permits eligible no-store pages under additional safeguards. Cookie or other authentication changes can evict them, and use of WebSocket, WebTransport or WebRTC adds restrictions. A no-store response to fetch or XHR can also evict a no-store page. Its documented retention limit is three minutes, compared with ten minutes for pages without that main-resource directive. An enterprise policy can opt out.
Chrome policy explorer · documented rollout in March–April 2025
These are selected no-store policy conditions, not a complete eligibility test. Browser memory pressure and other blockers can still prevent a restore.
These are Chrome’s documented conditions, not a cross-browser contract or a guarantee about every November 2026 build. Firefox and Safari have their own eligibility decisions. The correct test is a real history navigation in the browsers you support, with the APIs your page actually uses. Do not use no-store as a portable mechanism to control the lifetime of an entire document in memory; use it for its HTTP storage meaning.
The NotRestoredReasons API exposes diagnostics on a navigation timing entry where supported. A result can describe a tree of frames and reasons, including masked cross-origin details. Feature-detect it; null does not mean you have a complete certificate of eligibility. Chrome DevTools’ Application panel can exercise a back/forward trip and report blockers, which is more useful than guessing from a request list alone.
window.addEventListener("pageshow", (event) => {
if (event.persisted) {
// The DOM and heap survived. Reconcile time-sensitive UI here.
refreshVisibleComments();
}
});
const navigation = performance.getEntriesByType("navigation")[0];
if (navigation && "notRestoredReasons" in navigation) {
console.log(navigation.notRestoredReasons);
}For the news site, a bfcache restore gives a fifth outcome for the same four resources: their initial request path does not run at all. Your pageshow handler may then request comments to reconcile live data. That new request is again subject to the worker and HTTP decisions you have already explored. Back did not use the network
and the page refreshed its comments after Back
can both be true.
Keep history diagnostics separate from HTTP hit ratios. A retained page did not answer four requests from a disk cache; it avoided reconstructing the document. Likewise a failed restore does not imply a full download of every body. The new document navigation may validate the article, reuse the bundle and logo, and fetch or revalidate comments. Knowing which mechanism acted makes performance traces much easier to read.
The bfcache saves the running page. HTTP caching saves responses. Restoring one does not renew the other’s freshness budget.
A cache hit still moves bytes
Suppose the browser has to reconstruct the article, and the bundle is still fresh in its HTTP disk cache. We have reached the bottom of the policy stack. Somewhere a browser process must find an entry, read metadata, confirm the key and obtain the bytes. A cache hit removes a trip to the publisher; it does not make 180,000 bytes of JavaScript appear inside the renderer without work.
Chromium’s network stack owns HTTP transactions and cache coordination. The renderer communicates with browser infrastructure across process boundaries, and disk operations are scheduled off the page’s JavaScript thread. An in-memory index can identify a likely entry without first scanning every file. The backend then reads and verifies the candidate. Operating-system page cache may make that disk
read come from RAM, which is another reason DevTools labels are not physical-device measurements.
Chromium has had multiple disk-cache backends. Its Simple Cache stores entry data in separate files with an index, rather than treating a large blockfile as its own miniature filesystem. The current source is more informative than the early Very Simple Backend
proposal: a normal entry can contain several streams, and a combined stream file does not simply place HTTP headers first and the body second. The diagram follows simple_entry_format.h as inspected for this dive.
In-memory index
Entry hash → entry informationFind a candidate, schedule I/O, verify the full key, read metadata, then stream the body.
Chromium Simple Cache · combined stream 0/1 file · file order
- File headerMagic, format version, key length, key hash
- Full cache keyThe original key is checked; a filename hash alone is insufficient
- Stream 1Response body, such as the bytes of app.3f9c2a.js
- Stream 1 footerEnd marker and integrity information
- Stream 0Serialized HTTP response metadata
- Optional key SHA-256Allows key verification when reading the metadata from the tail
- Stream 0 footerStream size, flags and integrity information
Structural diagram, not byte lengths. Based on simple_entry_format.h as inspected in November 2026. Other streams, sparse entries and backend choices need additional files.
The file has a format header and the full key, body stream data and its footer, then metadata stream data, an optional SHA-256 of the key and another footer. The index and hashed filename narrow the search; stored key checks prevent a hash collision from silently selecting the wrong URL. The optional key SHA-256 supports checking the key while reading the tail metadata. It is not a content-addressed URL and it does not replace the HTTP ETag.
Footers and integrity fields help the cache detect incomplete or corrupt entries. A failed integrity check can discard the candidate and fall back to fetching; cache files are disposable copies rather than the publisher’s authoritative database. Additional streams, sparse responses, index persistence and recovery add details beyond this normal combined-file layout. Platform configuration and Chromium revisions can change backend choices and file formats, so these are implementation details to inspect, not an API for applications to parse.
Firefox’s cache2
Firefox’s cache2 implementation similarly distinguishes memory and disk storage and exposes asynchronous entry operations. Load-context information, including origin attributes and private-browsing context, separates stores that must not overlap. Its documentation describes intermediate memory caching and an index used to manage disk entries. The code lives under netwerk/cache2; exact file encoding and process ownership can evolve independently of the HTTP semantics.
In either browser, memory retention can mean several things: an HTTP entry buffered in RAM, an operating-system cached file page, a renderer’s resource object, a decoded image or a compiled-code cache. The logo might avoid decoding as well as downloading, while the bundle might still need parsing or compilation after its response bytes are reused. These caches have related inputs but different eviction and lifetime rules. Memory cache
in a network panel is not a promise that the document’s JavaScript heap survived.
Why the hit still takes time
A hit can pay for task scheduling, IPC, index lookup, opening a file, reading and checking metadata, moving the body between processes and decoding the representation. A cold storage device or a busy I/O queue makes some of those costs larger; an already buffered entry makes them smaller. No fixed disk hit equals 2 ms
rule survives across devices, response sizes and load. Measure the actual critical path rather than attributing every local delay to the network.
Separate transfer, loading and execution when reading a trace. A 304 can have a tiny transferred body count while waiting on a slow origin. A fresh 180 kB bundle can have zero network transfer while still costing CPU to execute. A bfcache restoration can avoid that initial execution but retain old application state. If you report only bytes saved, you miss latency; if you report only network requests, you miss work performed after the response arrives.
The four news resources now have a complete route. The article’s private copy waits for a validator. The hashed bundle spends a long explicit lifetime and can also have an application-managed offline copy. The logo has a shorter HTTP lifetime and a separate worker expiration problem. Comments trade a bounded amount of freshness for latency and availability, while their worker strategy has a different clock. Back may restore the whole document and skip their initial loading entirely. At every stop, the decisive question is the same: which identity, which permission and which clock authorise these bytes to answer this request?
At the bottom, reuse still means finding, checking and moving bytes. The policy stack decides when that local work can replace a network exchange.
End of HTTP caching · 9 levels, Idea to System
Where to next
Next in Web and networking · 06 of 12
CORS, at the browser’s boundary
Your app can reach the API. Why can’t it read the reply? Follow one JSON order through origins, preflights, cookies and the browser’s response filter, down to HTTP/2 frames.
Practical notes
Cache-Control recipes that actually work
Choose response directives by whether data is public, how long staleness is acceptable, and whether a stored response may be reused without validation.
CORS: a practical response-header checklist
Diagnose a blocked browser fetch by checking the origin, preflight response and credential policy. CORS controls what scripts can read; it does not authenticate a request.