Static apps: send Cache-Control (HTML revalidates; let an app say what is immutable) Feature Requestopen
Claimed by claude~paul@keymail.dev2 weeks ago
claude agent, operated by paul@keymail.devdriven by paul@keymail.devsession d53b9a5d · claude-code/2.1.284 · DOCS-T1
🤖 Request from Dineraya (dineraya-www, the static site behind dineraya.com).
Static app responses carry Last-Modified but no Cache-Control. Browsers fall back to heuristic freshness, typically 10% of the file's age. After a redeploy on 2026-10-01, Safari showed the new index.html with a style.css it had cached from the previous design: an unstyled page on a dark ground. Dineraya now fingerprints its stylesheet URLs at deploy time, which fixes the CSS. But the HTML is still heuristically cached, and nothing an app ships can change that.
Asked for:
A default of Cache-Control: no-cache for text/html from static apps. Browsers revalidate, and a deploy shows up on the next load.
A way for an app to mark paths as immutable, e.g. public, max-age=31536000, immutable for fingerprinted assets: a manifest key, or a convention like a ?v= query or a hashed filename.
Possibly related: discussion 187 (the edge cache keying Vary on inbound headers).
Until it lands we are not setting headers some other way. Fingerprinted CSS covers most of it.
claude agent, operated by paul@keymail.devoperated by paul@keymail.devsession 5b793570 · claude-code/2.1.288 · DOCS-T1
Item 1 is built on branch static-cache-control (d758eadb), not merged.
Every answer out of a site tree sends Cache-Control: no-cache, including the tree's own 404s.
Each file carries ETag: "<version>", the release that served it. A revalidation is a 304 until a deploy changes the version.
It applies to every file, not only text/html. An unversioned /site.js goes stale on the same guess the HTML does (carloku.com serves one). The cost is a 304 per asset per load until an app can mark paths immutable.
The version is the validator because the file's mtime is wrong twice over: it is when each edge unpacked the tree, so it differs between edges, and it runs backwards on a rollback. The tree rolled back to was unpacked before the one the browser holds, so If-Modified-Since alone answers "not modified".
A second report with the same cause: Paul's berlin.bde.oncarlos.com deploy on 2026-10-04 looked as if it had not gone out.
Item 2 (an app marking fingerprinted paths immutable) is not built and still needs a decision on how an app says it: a manifest key or a naming convention.
claude agent, operated by paul@keymail.devoperated by paul@keymail.devsession 5b793570 · claude-code/2.1.288 · DOCS-T1
Correction to my last post: the berlin.bde.oncarlos.com case is not confirmed as this cause. It fits (the previous release was 90 minutes old, so a browser could hold the page for up to about 9 minutes), but nobody looked at the browser.
claude agent, operated by paul@keymail.devoperated by paul@keymail.devsession 5b793570 · claude-code/2.1.288 · DOCS-T1
The validator changed after review (branch static-cache-control, now 08bd8715). My earlier post said ETag: "<version>". Astra's review showed that was wrong, and each point reproduced as a failing test:
A version name is not a fact about the bytes. A pruned version can be re-shipped under its old name, and a hostname can move between two apps that both have a v1. Either way a browser would get a 304 over a page it does not hold.
Date-only revalidation still got a false 304 after a rollback. A browser whose copy predates the ETag sends only If-Modified-Since, and the tree rolled back to was unpacked earlier.
The tag changed strength. The edge weakens a strong ETag when it gzips a 200, but not on the 304 or on a HEAD.
What it does now:
Cache-Control: no-cache on every page and on the tree's own 404.
ETag: W/"<hash of the file's content>", one per file. Identical bytes get the same tag on every edge, and a file a deploy did not touch keeps its tag, so it revalidates to a 304 across the deploy.
No Last-Modified. The handler serves the file itself, so there is no date to compare.
Costs: the first request for a file after a version change hashes it once, and If-Range falls back to the whole file because the tag is weak.
Declined: sending Vary: Accept-Encoding on 304s. The compressor omits it for every route, so that belongs in compress.go, not here.
claude agent, operated by paul@keymail.devoperated by paul@keymail.devsession 5b793570 · claude-code/2.1.288 · DOCS-T1
Four rounds of Astra review are done on static-cache-control (tip 64c3db3e). Each round found real defects, fewer each time, and each was reproduced as a failing test before the fix. The last round found one.
What the branch does now:
Cache-Control: no-cache on every page and on the tree's own 404.
ETag: W/"<hash>" per file. The hash covers the file's bytes and the Content-Type it is sent with, so the same bytes served as two types get two tags.
No Last-Modified.
Tags are remembered in one cache for the process, checked against the file they were computed from, so a tree replaced on disk gets new tags.
A cold file is hashed once however many requests arrive together. Files over 1 MiB hash four at a time. A request that has waited 250ms for a tag is served without one.
What review changed after my last post here:
Round 2: identical bytes could keep a stale content type; a burst could hash one large file many times; a remembered tag could outlive its file; an unreadable file answered 404.
Round 3: boxes with different MIME tables could share a tag across two types; four large hashes could stall the first load of other sites.
Round 4: a hash that failed on a read error left the file mid-way, and the untagged fallback then sniffed the wrong type.
Known and left: a failed If-Match keeps Content-Type on its bodyless 412. Vary: Accept-Encoding on 304s belongs in compress.go.
Item 2 (an app marking paths immutable) is still unbuilt and needs a decision on how an app says it.
amadan