🚀 Deployment & Ops · Chapter 3

Cache-Control — the header that decides if users see your fix

Caching is the fastest optimisation there is and the most expensive mistake. The difference is one header, decided once, at deploy time.

Study this lesson free in the app →

The basics

Cache-Control is the HTTP response header that tells every cache between your server and the user — browser, CDN, proxy — whether it may keep a copy of a file, and for how long it may use that copy without asking again.

The problem it solves: downloading the same CSS on every page view is slow and wasteful, so caches keep copies. But a copy that's kept too long means users don't see your fix — sometimes for a year, with no way for you to reach them.

The mental model: a cache is keyed by URL. Either the URL changes whenever the content changes (a hash in the filename) — then cache it forever — or the URL stays the same, and the cache must revalidate each time: ask "still the same?" and get a tiny 304 Not Modified back if so. Anything in between is where stale-site bugs live.

Explained

You fix a bug. You deploy. You refresh — still broken.

Not because the deploy failed. Because a machine between you and the server was told, in writing, that the old file was good for a year. And it believed you.

A cache is anything that keeps a copy so it does not have to ask again. Between your server and a user there are usually four:

1. The browser's disk cache
2. The service worker, if the app installed one
3. The CDN edge node nearest the user
4. Any proxy in between

Cache-Control is how the server tells all of them what they are allowed to do. Get it right and the site is fast and correct. Get it wrong in one direction and it is slow; wrong in the other and users are stuck on a broken version with no way to recover.

The directives worth knowing

max-age=N — fresh for N seconds. During that window the cache does not even ask.

no-cache — badly named. It does not mean don't cache; it means cache it, but revalidate before every use. The check is cheap: the browser sends the ETag and gets back 304 Not Modified with no body if nothing changed.

no-store — genuinely do not keep a copy. For anything sensitive.

must-revalidate — once stale, you must check; never serve stale on a network error.

immutable — this will never change, do not even revalidate on refresh. Only safe with a content hash in the filename.

public / private — may a shared cache (a CDN) store it, or only the user's own browser? Anything user-specific must be private.

Standard advice is to cache assets for a year. This project deliberately does not — and the reason is a property of this codebase.

The usual pattern relies on content hashing: a build tool renames app.css to app.9f2b1c.css, so a changed file is a different URL and can safely be cached forever.

This app has no build step. assets/css/app.css is always assets/css/app.css. So caching it for a year would mean a phone that loaded the old CSS would never get a fix — and there would be no way to force it short of changing the filename by hand.

must-revalidate costs one cheap conditional request per file per visit and returns a bodyless 304 when nothing changed. The right cache policy is a consequence of whether your filenames change.

That trade-off flips completely once volume goes up.

At a few hundred visits a day, a revalidation request per asset is invisible. At ten million, it is ten million round trips to your origin that produce nothing but 304s.

At that scale you do the work to earn long caching:

• Hash the filenames at build time, then max-age=31536000, immutable on every asset
• Keep must-revalidate on the HTML entry point only — it is small, and it is what names the hashed files
• Push the TTL to the CDN edge so revalidations terminate there instead of at your origin

The pattern is the same everywhere in systems work: the cheap correct thing until the volume justifies the expensive fast thing.

The service worker is a fifth cache you wrote yourself

Cache-Control does not govern a service worker — your own code does. This app is network-first, which is why a new lesson appears without any cache-busting:

fetch(e.request)
  .then((res) => {
    const copy = res.clone();
    caches.open(CACHE).then((c) => c.put(e.request, copy));
    return res;                       // fresh wins whenever the network works
  })
  .catch(() => caches.match(e.request));  // offline falls back to the copy

The opposite choice, cache-first, is faster and is how you strand users on a broken build. If you pick it, you need a versioned cache name and an activate handler that deletes the old one — which is exactly what the CACHE constant in sw.js is for.

Thinking no-cache means no caching. It means revalidate every time. no-store is the one that means no copy.

immutable without a content hash. You have now made a file uneditable for its entire max-age, for every user who loaded it.

public on a user-specific response. A shared CDN caches one user's data and serves it to the next. This is a real, recurring, serious bug.

Testing with a hard refresh. ⇧⌘R bypasses caches, so it tells you nothing about what a normal visitor sees. Test in a private window, or with curl -I.

Forgetting the service worker exists. It sits in front of everything and obeys none of these headers.

Cache forever, or revalidate every time. The middle is where the bugs live.

Hashed filename → immutable, cache for a year. Stable filename → must-revalidate.

no-cache means check first. no-store means do not keep it.

Words to know

In two minutes

• Cache-Control tells browsers, CDNs and proxies whether to keep a copy and how long to trust it without asking.
• Caches are keyed by URL, so the safe strategies are: change the URL on every change, or revalidate every time.
• Hashed filenames get max-age=31536000, immutable; the HTML entry point gets no-cache or max-age=0, must-revalidate.
• no-cache means revalidate before use; no-store means keep nothing.
• Revalidation costs one round trip and a bodyless 304 — cheap at low traffic, worth eliminating at millions of visits.
• User-specific responses must be private, or a CDN can hand one user's data to another.
• A service worker is a cache you wrote yourself; it ignores these headers and needs its own versioning.

Test yourself

There are 8 questions, 3 puzzles and 5 recall cards for this lesson in the app — the recall cards come back on later days, just before you would forget.