JS-250 · Lesson 6 of 12 · 28 min
Caching and HTTP
▶ Video coming soon A video version of this lesson is on the way.
On Thursday, September 7, Gareth opens the laptop to the Network panel of the home page with the cache switched back on and reloads it twice. The first load transfers the same bytes as before. The second load transfers almost exactly the same bytes again. The photos, the stylesheet, the fonts and the scripts are fetched afresh on every visit, as if the browser had never seen them, and the cause is one line of configuration on Theo's server that nobody had looked at since the site launched. Today's lesson is about the HTTP cache: how browsers decide whether they can reuse something they downloaded before, and how a site tells them.
Why caching matters so much
Most of a site's visitors are not on their first visit. Volunteers open the portal several times a week, and people come back to the recipe pages again and again. For a returning visitor, the fastest request is the one never made, and the second fastest is a short question to the server that gets the answer 'what you have is still current'. Good caching rules can make a repeat visit transfer a few kilobytes instead of a few megabytes, and they reduce the load on Theo's server at the same time.
There are several caches between a visitor and the server. The browser has a private cache for the person using it. A shared cache, such as a content delivery network or a caching proxy run by a company or a school, stores responses for many people. And from lesson 8 on, a service worker can keep its own cache under the page's control. The HTTP cache rules, defined in RFC 9111, apply to the first two.
Cache-Control
A response tells caches what they may do with it in the Cache-Control header, a comma-separated list of directives. The ones below cover almost every case a site needs.
| Directive | Meaning |
|---|---|
| max-age=N | The response is fresh for N seconds after it was generated |
| s-maxage=N | Like max-age, but only for shared caches, which use it instead of max-age |
| no-cache | May be stored, but must be revalidated with the server before every use |
| no-store | Must not be stored at all |
| private | Only the visitor's own browser may store it, not a shared cache |
| public | Shared caches may store it, even for a request that carried credentials |
| immutable | Will never change while fresh, so the browser need not revalidate it even on reload |
| stale-while-revalidate=N | After it goes stale, may be used for N more seconds while a fresh copy is fetched in the background |
| must-revalidate | Once stale, must not be used without revalidating, even if the server cannot be reached |
The names are confusing in one well-known way: no-cache does not mean do not cache. It means store it, but check with the server before using it. The directive that forbids storing is no-store. The Food Hub's server had been sending no-cache, no-store, must-revalidate on everything, a combination copied from an old answer on a forum years ago, which is why nothing was ever reused.
Mira starts with a parser, because the studio's monitoring will need to read these headers and so will her tests.
// Parse a Cache-Control header into an object of directives.
function parseCacheControl(header) {
const out = {};
for (const part of header.split(',')) {
const [rawName, rawValue] = part.trim().split('=');
if (!rawName) continue;
const name = rawName.toLowerCase();
out[name] = rawValue === undefined ? true : Number(rawValue.replace(/"/g, ''));
}
return out;
}
for (const h of [
'public, max-age=31536000, immutable',
'no-cache',
'max-age=300, stale-while-revalidate=86400',
'no-cache, no-store, must-revalidate',
'private, max-age="600"',
]) console.log(h.padEnd(44), JSON.stringify(parseCacheControl(h)));public, max-age=31536000, immutable {"public":true,"max-age":31536000,"immutable":true}
no-cache {"no-cache":true}
max-age=300, stale-while-revalidate=86400 {"max-age":300,"stale-while-revalidate":86400}
no-cache, no-store, must-revalidate {"no-cache":true,"no-store":true,"must-revalidate":true}
private, max-age="600" {"private":true,"max-age":600}What this code does
Each directive is separated by a comma, and a directive with a value has an equals sign, so splitting on both gives a name and an optional value. Directives without a value become true and numeric values become numbers, with any quotes removed because some servers quote them. Names are lowercased because directive names are not case-sensitive.
Fresh, stale and revalidated
A cached response is fresh for its freshness lifetime, usually its max-age. Its age is how long ago the origin server generated it, which a shared cache reports in the Age header. While it is fresh, the browser uses it without asking anyone. Once its age passes the lifetime, it is stale, and the browser must revalidate it before use, unless a directive such as stale-while-revalidate allows it to be used for a little longer while a fresh copy is fetched in the background.
If a response has no explicit lifetime at all, caches may guess one. The usual rule of thumb, which RFC 9111 suggests, is a tenth of the time since the file was last modified, using the Last-Modified header. A stylesheet last changed 50 days ago would be treated as fresh for five days, which is how a site with no caching headers at all can end up showing an old design to returning visitors after an update.
// Decide what a cache does with a stored response. Times in seconds.
function decide(stored, now) {
const cc = stored.cacheControl;
if (cc['no-store']) return 'not stored';
const age = now - stored.date + (stored.age ?? 0);
let lifetime = cc['max-age'];
let how = 'max-age';
if (lifetime === undefined && stored.lastModified !== undefined) {
lifetime = Math.floor((stored.date - stored.lastModified) / 10);
how = 'heuristic';
}
lifetime ??= 0;
if (cc['no-cache']) return `revalidate first (age ${age} s)`;
if (age < lifetime) return `fresh: use it (age ${age} s of ${lifetime} s, ${how})`;
const swr = cc['stale-while-revalidate'] ?? 0;
if (age < lifetime + swr) return `stale: use it and revalidate in the background (age ${age} s)`;
return `stale: revalidate before use (age ${age} s)`;
}
const DAY = 86400, now = 100 * DAY;
const cases = [
['hashed CSS', { date: now - 40 * DAY, cacheControl: { 'max-age': 365 * DAY, immutable: true } }],
['home page HTML', { date: now - 60, cacheControl: { 'no-cache': true } }],
['news list', { date: now - 400, cacheControl: { 'max-age': 300, 'stale-while-revalidate': DAY } }],
['old logo, no headers', { date: now - 6 * DAY, lastModified: now - 56 * DAY, cacheControl: {} }],
['recipe JSON', { date: now - 900, age: 120, cacheControl: { 'max-age': 600 } }],
];
for (const [name, stored] of cases) console.log(name.padEnd(21), decide(stored, now));hashed CSS fresh: use it (age 3456000 s of 31536000 s, max-age) home page HTML revalidate first (age 60 s) news list stale: use it and revalidate in the background (age 400 s) old logo, no headers stale: revalidate before use (age 518400 s) recipe JSON stale: revalidate before use (age 1020 s)
What this code does
The age is the time since the response was generated plus any Age the shared cache reported, and the lifetime comes from max-age or, failing that, a tenth of the time since the last modification. A response younger than its lifetime is used as it is; an older one may still be used for the stale-while-revalidate window while a fresh copy is fetched. The recipe JSON is 900 seconds old plus 120 seconds of Age from a shared cache, which is past its 600-second lifetime.
Validators and 304 Not Modified
Revalidating does not mean downloading again. When the browser revalidates, it sends a conditional request that carries a validator from the stored response. If the stored copy is still current, the server answers 304 Not Modified with no body, and the browser uses what it has. Only if the resource has changed does the server send a full 200 response.
| Validator in the response | Sent back in the request | Compared by |
|---|---|---|
| ETag: "DZi2AA7Cr8BJfC6G" | If-None-Match: "DZi2AA7Cr8BJfC6G" | Exact tag (or weak comparison, see below) |
| Last-Modified: Tue, 29 Aug 2028 14:02:11 GMT | If-Modified-Since: Tue, 29 Aug 2028 14:02:11 GMT | Date, to the second |
An ETag is an opaque tag for one version of a resource, often a hash of its content. A tag that starts with W/ is a weak ETag, which promises only that the two versions are equivalent for display, not identical byte for byte; servers that compress on the fly often weaken their tags for that reason. When a browser sends If-None-Match, the server compares tags using weak comparison, which ignores the W/ prefix, because the question is only whether the browser's copy is good enough to show.
// Answer a conditional GET: 304 if any tag in If-None-Match matches the current ETag.
function weakEqual(a, b) {
return a.replace(/^W\//, '') === b.replace(/^W\//, '');
}
function answer(currentEtag, ifNoneMatch) {
if (!ifNoneMatch) return '200 OK (full body)';
if (ifNoneMatch.trim() === '*') return '304 Not Modified';
const tags = ifNoneMatch.split(',').map((t) => t.trim());
return tags.some((t) => weakEqual(t, currentEtag)) ? '304 Not Modified' : '200 OK (full body)';
}
const current = 'W/"news-2028-09-07-3"';
for (const h of [undefined, '"news-2028-09-07-3"', 'W/"news-2028-09-07-3"', '"news-2028-09-06-1", W/"news-2028-09-07-3"', '"news-2028-09-06-1"']) {
console.log(String(h).padEnd(44), '->', answer(current, h));
}undefined -> 200 OK (full body) "news-2028-09-07-3" -> 304 Not Modified W/"news-2028-09-07-3" -> 304 Not Modified "news-2028-09-06-1", W/"news-2028-09-07-3" -> 304 Not Modified "news-2028-09-06-1" -> 200 OK (full body)
What this code does
weakEqual() strips a leading W/ from both tags before comparing, which is the weak comparison that If-None-Match uses. answer() checks every tag in the header, because a browser may send several, and treats the special value * as matching any current version. A request without the header always gets the full body.
Gareth asks Mira to try the real thing. The server below applies the studio's new caching rules to two files, and the session after it uses curl, a command-line HTTP client, to make a first request, a conditional request and a request for the hashed stylesheet.
// server.mjs: serve the home page and a hashed stylesheet with the studio's caching rules.
import http from 'node:http';
import { createHash } from 'node:crypto';
const files = {
'/': { type: 'text/html', body: '<!doctype html><title>Food Hub</title><link rel="stylesheet" href="/css/site-4f1c2a.css">' },
'/css/site-4f1c2a.css': { type: 'text/css', body: 'body { font-family: system-ui, sans-serif; }' },
};
const server = http.createServer((req, res) => {
const file = files[req.url];
if (!file) { res.writeHead(404).end(); return; }
const etag = '"' + createHash('sha256').update(file.body).digest('base64url').slice(0, 16) + '"';
const cacheControl = req.url === '/'
? 'no-cache' // HTML: always check with the server first
: 'public, max-age=31536000, immutable'; // hashed files never change
if (req.headers['if-none-match'] === etag) {
res.writeHead(304, { etag, 'cache-control': cacheControl }).end();
return;
}
res.writeHead(200, { 'content-type': file.type, etag, 'cache-control': cacheControl });
res.end(file.body);
});
server.listen(8250, () => console.log('listening on http://localhost:8250'));What this code does
Every response gets an ETag made from a hash of its body, so the tag changes exactly when the content does. The HTML is sent with no-cache, so browsers keep it but check it every time, and the hashed stylesheet is sent with a one-year lifetime and immutable. When a request's If-None-Match matches the current tag, the server answers 304 with no body.
$ curl -s -D - -o /dev/null http://localhost:8250/ | grep -iE "^(HTTP|etag|cache-control)"
HTTP/1.1 200 OK
etag: "DZi2AA7Cr8BJfC6G"
cache-control: no-cache
$ curl -s -D - -o /dev/null -H 'If-None-Match: "DZi2AA7Cr8BJfC6G"' http://localhost:8250/ | grep -iE "^(HTTP|etag|cache-control)"
HTTP/1.1 304 Not Modified
etag: "DZi2AA7Cr8BJfC6G"
cache-control: no-cache
$ curl -s -D - -o /dev/null http://localhost:8250/css/site-4f1c2a.css | grep -iE "^(HTTP|cache-control)"
HTTP/1.1 200 OK
cache-control: public, max-age=31536000, immutableWhat this code does
curl prints the response headers because of -D -, discards the body, and grep keeps only the status line and the caching headers. The second request sends the tag from the first response back in If-None-Match, so the server answers 304 Not Modified and sends no body. The stylesheet comes with a one-year lifetime and immutable, so a browser will not ask for it again for a year.
Cache busting with hashed file names
Long lifetimes and updates seem to conflict. If the stylesheet is cached for a year, how does a returning visitor get the new version when Sana changes a colour? The answer is to never change a file that has been published, only to publish new files under new names. The build puts a short hash of each file's content in its name, such as site-4f1c2a.css, and rewrites the HTML to refer to the new name. A changed stylesheet gets a new hash, so it is a new URL that no cache has seen, while the HTML, which is revalidated on every visit, points visitors to it at once.
// Name a built file after a hash of its content, as the build does.
async function hashedName(path, content) {
const bytes = new TextEncoder().encode(content);
const digest = await crypto.subtle.digest('SHA-256', bytes);
const hex = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
const dot = path.lastIndexOf('.');
return `${path.slice(0, dot)}-${hex.slice(0, 8)}${path.slice(dot)}`;
}
const before = 'a { color: #8a5a00; }';
const after = 'a { color: #7a4f00; }';
console.log(await hashedName('css/site.css', before));
console.log(await hashedName('css/site.css', before));
console.log(await hashedName('css/site.css', after));css/site-de390979.css css/site-de390979.css css/site-04327ada.css
What this code does
The content is turned into bytes with TextEncoder and hashed with SHA-256 using the Web Crypto API, and the first eight hexadecimal characters of the digest are put before the file's extension. The same content always produces the same name, so unchanged files keep their cache entries between releases. One changed colour gives a completely different name, which is a new URL to every cache.
| What | Cache-Control | Why |
|---|---|---|
| HTML pages | no-cache | Always checked, so visitors see updates and new asset names at once |
| Hashed CSS, JS, fonts and images | public, max-age=31536000, immutable | A new version is a new URL, so the old one can be kept forever |
| Photos uploaded through the news editor | public, max-age=604800 | Not hashed, but rarely change; a week is a fair compromise |
| News and recipe JSON from Theo's API | max-age=60, stale-while-revalidate=600 | Fast for repeat views, updated within minutes |
| Portal pages and API responses with personal data | private, no-cache | Never in a shared cache, always checked |
| Sign-in responses and tokens | no-store | Never stored anywhere |
The rules have one more subtlety for the portal. Responses that differ depending on a request header, such as a page that is compressed differently for different Accept-Encoding values, must say so with the Vary header, so that a shared cache does not hand a Brotli response to a browser that asked for gzip. Theo's server already sends Vary: Accept-Encoding on compressed responses. Personal data should simply never reach a shared cache, which is what private is for.
Connections and protocols
Caching saves requests; the protocol decides how expensive the remaining requests are. HTTP/1.1 sends one request at a time on each connection, so browsers open up to six connections to each server and requests queue behind each other. HTTP/2, which Theo's server uses, sends many requests at once over a single connection, which is why combining files into a few large bundles matters much less than it once did. HTTP/3 runs HTTP over QUIC, a transport built on UDP that sets up the connection and the encryption together in fewer round trips and is not held up when a single packet is lost, which particularly helps on unreliable mobile and Wi-Fi networks. All major browsers support HTTP/3, and servers advertise it with the Alt-Svc response header or a DNS record so the browser can switch on a later request.
- Reuse connections. Serving fonts, images and scripts from the site's own origin avoids extra DNS lookups and TLS handshakes.
- Avoid redirects on the main page. Each redirect, such as from http to https and then to www, costs at least one round trip before the HTML even starts.
- Keep cookies small. Cookies are sent with every request to their site, including every image, so a large cookie adds bytes to every request.
The back/forward cache
One more browser cache is worth knowing because it makes navigation instant. When a visitor goes back to the previous page, browsers can restore it from the back/forward cache, a snapshot of the whole page, its JavaScript state included, kept in memory for a short time. A page restored this way appears immediately, with no network requests and no scripts re-running. Browsers decline to keep a page in this cache if it does things that make a snapshot unsafe, and a few are common on real sites.
- unload event handlers. A handler for unload makes many browsers skip the cache. Use pagehide or visibilitychange instead; Chrome is gradually phasing out the unload event.
- Open connections. A page with an open WebSocket or, in some browsers, an active server-sent events connection may not be cached; close them on pagehide and reopen them on pageshow.
- Cache-Control: no-store on the HTML. Pages sent with no-store have usually been excluded, although Chrome has begun allowing some of them when it is safe.
The volunteer portal had both of the first two: an unload handler that saved a draft, and the order board's event stream from JS-240 on the kitchen staff's admin page. Mira moves the draft saving to pagehide and closes the stream when the page is hidden, and Chrome's Application panel, which can test whether a page is eligible, now reports that the page can be restored.
Worked problem
What a repeat visit costs
Before the fix, every visit to the home page transferred about 2,400 kB once images had been resized. After the fix, a returning visitor's browser revalidates the HTML (a 304 of about 0.3 kB) and the news JSON (a 304 of about 0.3 kB), and everything else is fresh in the cache. On the phone profile, each revalidation costs one 300 ms round trip, and the two can run in parallel after the HTML. Roughly how long does the network part of a repeat visit take now, and how many kilobytes move?
Show solution
- Transferred: 0.3 + 0.3 = 0.6 kB instead of 2,400 kB.
- The HTML revalidation needs one round trip: 300 ms (the connection may also need setting up if it was closed).
- The news JSON is requested after the HTML has been read: another round trip, 300 ms.
- Network time: about 300 + 300 = 600 ms, plus connection setup if needed.
Answer: About 0.6 kB and roughly 0.6 seconds of round trips, instead of 2,400 kB, which took about 12 seconds on the same connection.
Common mistakes
MistakeUsing no-cache to stop caching.
InsteadUse no-store to forbid storing; no-cache means store but revalidate.
MistakeGiving unhashed files long lifetimes.
InsteadUse long lifetimes and immutable only for files whose names change when their content does.
MistakeCaching HTML for a long time.
InsteadSend HTML with no-cache or a short lifetime so visitors see updates and new asset names.
MistakeLetting personal pages into shared caches.
InsteadMark them private, and use no-store for sign-in responses and tokens.
MistakeSaving data in an unload handler.
InsteadUse pagehide or visibilitychange, which also keeps the page eligible for the back/forward cache.
Summary and key terms
- The HTTP cache lets browsers and shared caches reuse responses.
- Cache-Control directives set how long a response is fresh (max-age, s-maxage), whether it may be stored (no-store) or shared (private, public), and how it may be used when stale (no-cache, must-revalidate, stale-while-revalidate); no-cache means revalidate, not do not store.
- Without a lifetime, caches may use a heuristic of a tenth of the time since Last-Modified.
- Revalidation uses ETag with If-None-Match, compared weakly, or Last-Modified with If-Modified-Since, and an unchanged resource gets a 304 with no body.
- Content-hashed file names allow year-long immutable caching while HTML is revalidated.
- Vary declares which request headers change a response.
- HTTP/2 and HTTP/3 make requests cheaper, and the back/forward cache restores whole pages instantly unless something such as an unload handler prevents it.
- HTTP cache
- The browser's and shared caches' store of responses, governed by the rules in RFC 9111.
- Freshness lifetime
- How long a stored response may be used without checking with the server.
- Revalidation
- Asking the server, with a conditional request, whether a stored response is still current.
- ETag
- A response header carrying an opaque identifier for one version of a resource.
- 304 Not Modified
- The response to a conditional request when the stored copy is still current; it has no body.
- Cache busting
- Giving a changed file a new URL, usually with a content hash in its name, so caches fetch it.
- Vary
- A response header naming request headers that change the response, so caches keep separate copies.
- Back/forward cache
- An in-memory snapshot of a page that lets the browser restore it instantly on back and forward.
Practice problems
Work each problem on paper first, then reveal the answer to check.
What is the difference between no-cache and no-store?
Show answer
no-cache allows storing but requires revalidation before each use; no-store forbids storing the response at all.
A stylesheet with no Cache-Control was last modified 30 days before it was fetched. Under the usual heuristic, how long is it fresh?
Show answer
About 3 days, a tenth of the time since it was last modified.
Why can the hashed stylesheet be cached for a year?
Show answer
Its name changes whenever its content does, so the old URL will never need to show different content.
Why does an unload handler slow down going back to a page?
Show answer
It makes browsers skip the back/forward cache, so the page must be loaded again instead of restored.
Try it yourself
Parse Cache-Control
Complete parseCacheControl(header) so that it returns an object with one key per directive, in lowercase. Directives without a value are true; directives with a value are numbers. Ignore empty parts, such as the one after a trailing comma.
The program prints the parsed form of three headers.
function parseCacheControl(header) {
return {};
}
console.log(JSON.stringify(parseCacheControl('public, max-age=31536000, immutable')));
console.log(JSON.stringify(parseCacheControl('No-Cache, ')));
console.log(JSON.stringify(parseCacheControl('max-age=60, stale-while-revalidate=600')));Try it yourself
Fresh or stale
Complete state(age, maxAge, swr) so that it returns 'fresh' if age is less than maxAge, 'stale, revalidate in background' if age is less than maxAge + swr, and otherwise 'stale, revalidate first'.
All values are in seconds, and swr may be 0.
function state(age, maxAge, swr) {
return 'fresh';
}
console.log(state(30, 60, 600));
console.log(state(60, 60, 600));
console.log(state(659, 60, 600));
console.log(state(660, 60, 600));
console.log(state(61, 60, 0));Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.