Feed pages can now show a snapshot newer than the build

The first part of moving feeds off the build gave them a home: a FEEDS KV namespace and an endpoint that serves the newest snapshot. This part puts those snapshots on the pages people and crawlers actually read.

What the Worker does now

Three pages show feeds: the home page and the work page show social posts, and the community page shows the latest Mello Zone articles. When one of them is requested and KV holds a valid snapshot of its feed, the Worker streams the built page through HTMLRewriter and replaces the contents of each feed container with cards rendered from that snapshot. The cards come from the same shared renderer the build uses, so a snapshot looks exactly as it would have if the site had been rebuilt around it. On the work page the “Latest post · feed checked” line is updated too.

The cards are in the HTML itself, not added by a script afterwards, so crawlers and visitors without JavaScript see the current feed.

When KV holds nothing for a page’s feeds, or only a snapshot that fails the build’s rules, the page is served exactly as built. Until the pollers start writing snapshots, that is every request.

Keeping browsers honest

Every page is revalidated on each visit, and until now its ETag came from the built file alone. A page with a newer snapshot rendered into it is a different document, so its ETag is the built one with a tag for the snapshot appended. A browser holding the plain built page, or a page with an older snapshot, no longer matches and is sent the current one.

The subtle part is the request to the built page itself. If the Worker passed a browser’s If-None-Match through, the asset layer would compare it with the built file, find a match and answer 304, even though the feed inside the page had since moved on, and a returning visitor would keep the old feed indefinitely. The Worker therefore always asks for the full built page, then compares the browser’s ETag with the combined one itself. A matching 304 keeps the page’s indexable robots policy.

Testing it where it runs

HTMLRewriter exists only in the Workers runtime, not in Node, so the new check, tools/test-feed-pages.mjs, bundles the Worker the way Wrangler does and runs it in Miniflare against the built pages. Its stand-in for the asset layer answers conditional requests the way the real one does, so forwarding a browser’s If-None-Match would be caught. A deliberate mutation that did exactly that made the check fail.

Verification

• tools/test-feed-pages.mjs, new in npm run test:built, passes seven checks in Miniflare: the shared renderer reproduces what the build put in the pages; with an empty KV every page is byte-identical to the build with its own ETag; a social snapshot reaches the home and work pages and nothing else; a community snapshot with images linked from Mello Zone reaches the community page; a snapshot that fails validation changes nothing; different snapshots give different ETags, a matching one gets a 304 that keeps the indexable robots policy, and the plain built ETag gets the new page rather than a stale 304; HEAD carries the combined ETag and no body.
• npm run test:delivery 190 of 190, npm run build 41 pages, npm run test:worker 84 of 84, npm run test:built 306 of 306, the release audit across 40 canonical pages, npm run check:feeds, and npx wrangler deploy --dry-run.
• Against npm run preview with local KV: with nothing stored, each page carried its plain built ETag; with retitled snapshots stored, the home and work pages showed the new social card, the community page showed the new article with its Mello Zone image, /about/ was untouched, and each feed page’s ETag gained the snapshot tag; the new ETag revalidated with 304 and the old built one got a 200. With the packaged snapshots stored, so every feed page went through the rewriter, npm run test:browser reported 0 failures across 40 routes and npm run test:a11y 0 failures across 90 checks.
• tools/indexing-surface.json was rewritten deliberately; its only change is this entry’s route.