Caching and the content stamp.
Cache headers declare how long a resource may be stored; a content stamp makes the resource’s address change whenever the resource itself changes.
Not downloading a resource a second time always beats downloading it fast. The cache provides that, and set up correctly it drives the network cost of repeat visits to nearly zero. Set up wrongly, either updates do not propagate or the cache never works at all.
The tension fits one sentence: a long cache is fast but updates do not spread; a short cache is fresh but slow. Most teams pick a value in the middle and collect both disadvantages at once.
The stamp: the solution that removes the tension
The right solution is not picking a middle value but removing the tension entirely. The method: the resource’s address carries a stamp derived from its content. When the content changes the stamp changes, so the address changes, so the browser sees it as a new resource and downloads it.
With that in place, the cache lifetime can be near-infinite — a year is a typical value. If the resource never changes it is never re-downloaded; if it changes, it downloads immediately at its new address. Neither stale content nor needless downloads.
The stamp deriving from the content is critical. Using a random version number or the build time changes the address on every deployment even when the content did not change, and the cache is wasted. The stamp must be computed from the file’s own bytes.
On this site the stamp works exactly that way: every style and script link carries a stamp computed from the file’s content. When the file does not change, the address does not change; when it does, it certainly does.
If the stamp does not derive from the content, the cache is wasted on every deployment.
Why it is needed was measured
This rule was added not as theory but as a post-incident rule. When files given a long cache were served without stamps, new HTML could meet old styles — the user saw the updated page in its old look.
This is the most insidious kind of cache bug: no error message, the page works, it only looks wrong. And it happens only to users who visited the site BEFORE — so a developer testing in a private window never sees it.
After the stamp was set up, this class of error became structurally impossible. HTML and styles can no longer diverge, because the HTML carries the style’s stamped address.
Which policy for which resource
- Stamped styles and scripts — a very long cache, the immutable marker. A year is typical.
- HTML pages — a short or validating cache. The page itself cannot be stamped because its address must be permanent.
- Images — long if stamped; medium if not.
- Fonts — very long. They rarely change.
- Sitemap and robots — short. They may need frequent updates.
- API responses — case by case; usually not cached.
The second item shows a boundary: an HTML page cannot be stamped because its address is the one given to users, and it must be permanent. Pages therefore get either a short lifetime or a validation mechanism — the browser asks, and if the server says “unchanged,” no download happens.
On this site the policy is built on that distinction: stamped resources long and marked immutable, pages short. The two groups are defined separately and do not mix.
The immutable marker
On top of a long cache lifetime, there is a special marker declaring the resource will never change. It tells the browser: no need even to revalidate this resource — if it is in the cache, use it directly.
The difference is subtle but real. Without the marker, the browser may send a request on page reload asking whether the resource is still valid; the server answers “unchanged” and no download happens, but a round trip is spent. With the marker, that request never happens.
The marker should go only on stamped resources. Calling a fixed-address resource immutable blocks update propagation entirely — leaving no remedy but the user clearing the cache by hand. Together with a stamp it is entirely safe: when the content changes the address changes too, so the old resource is never requested again.
On this site the style and script files are both stamped and marked immutable. Together, that means zero network traffic for these resources on repeat visits.
A practical checklist
Turning this page into an audit step, here is what to check in the cache policy. The list is kept short because long lists do not get walked; six items fit in one sitting.
- Are the styles and scripts stamped?
- Does the stamp derive from the content — not from the build time.
- Do the stamped ones get a long cache and the immutable marker?
- Do the HTML pages get a short or validating policy?
- Are the sitemap and robots short?
- Is the policy defined in one place — scattered definitions drift apart.
The second item is the most critical: if the stamp does not derive from the content, the cache is wasted on every deployment and the long lifetime means nothing.
If the stamp does not derive from the content, the cache is wasted on every deployment.
A case reminder to close: on this site the stamp rule was added not as theory but as a post-incident rule. When long-cached files were served without stamps, new HTML could meet old styles and the user saw the updated page in its old look.
Such bugs are especially insidious because they occur only for users who visited the site BEFORE. The developer tests in a private window, everything looks right, and real users see the broken page. After the stamp was set up, this class of error became structurally impossible — HTML carries the style’s stamped address, so the two cannot diverge.
One last configuration note: the cache policy should be defined in a single place. Definitions scattered across layers — server, edge network, application — drift apart over time, and which one wins becomes unclear. On this site the policy lives in one headers file with the two groups clearly separated: stamped resources long and immutable, pages short. The distinction reads at a glance — and that readability is what the person returning to the file a year later will need most.