feat(tanstack): opt-in CDN caching for /_serverFn via a URL segment marker

[JonasJesus42]

Split out of #510 at review request. Stacked on #512 (private-route hotfix), which is this branch's base —
merge that one first.

The problem

Anything sitting in front of the Worker keys on the raw URL. The Worker keys on a synthetic Request
carrying __seg/__cf_device/__cf_geo/__bot/__fetch/__abf (buildCacheKey). That mismatch is what
forces CDN-Cache-Control: no-store on every response, and why 100% of traffic invokes the Worker.

The fix, for /_serverFn

Invert the problem: instead of expecting the layer in front to reproduce the key, the client puts the
segment in the URL itself (?__cseg=<device>.<buildHash>), which makes the two keys equivalent.

// worker-entry.ts
createDecoWorkerEntry(serverEntry, {
  cdnCacheControl: "serverfn-segment",
  buildSegment: (request) => ({ /* ... */ }),   // required
});

// src/start.ts
import { decoServerFnFetch } from "@decocms/tanstack/sdk/serverFnFetch";
export const startInstance = createStart(() => ({ serverFns: { fetch: decoServerFnFetch } }));

Covers SPA navigation and prefetch — the volume Speculation Rules generates. Default unchanged.

Why it's safe

The marker is a hint, not a source of truth. The Worker recomputes the segment from the request itself and
only relaxes no-store on an exact match. These all keep today's behaviour:

marker absent · diverging · forged · stale build · logged-in · region · sales channel ≠ 1 · unknown custom
SegmentKey field · bot UA · A/B cohort cookie · geo-varying key

The worst case is not caching, never a wrong response.

isBot and the A/B cookie are checked with the same helpers buildCacheKey uses — keying and releasing
off different predicates is exactly how the two silently diverge.

The build hash is part of the token because deploying does not purge whatever is caching the response, so the
URL has to change on its own when the bundle does.

HTML stays no-store: the initial navigation is a browser request, with no client hook to attach a marker
to.

Also here: match-profile was a silent trap

Its JSDoc promised safety "without buildSegment and deviceSpecificKeys: false", but deviceSpecificKeys
defaults to true — the condition is false on every site. Following the docs would have cross-served segments
with no warning. Now refused with a warning.

Provenance

Ported from a site-level implementation running in production, with two gaps closed: that version verified
only the device, leaving bots (which execute JS — Lighthouse, PageSpeed) and A/B cohorts able to poison a
shared entry. On the site, this replaced ~230 lines of shim with 6 lines plus a 9-line start.ts.

Validation

Tested end-to-end against a real built site, not just unit tests: linked packages, bun run build, worker
under wrangler dev, SPA navigation driven by Chrome.

case	Cdn-Cache-Control
GET /_serverFn with a correct marker (desktop and mobile)	public, max-age=1800 ✅
no marker	no-store
marker for another device (forged)	no-store
stale build	no-store
bot UA	no-store
login cookie	no-store
A/B cookie	no-store
HTML document	no-store

The released value matches exactly what the site-level implementation produces in production.

2573 tests passing. Typecheck clean.

The 4 draft preview failures are pre-existing on main.

What was dropped

The Cache Rules generator that was in #510 is gone. Review pointed out — correctly — that sites served by
Workers have no cache in front of them, and that the path is Workers Cache (cache: { enabled: true } in
wrangler), not zone-level Cache Rules. That changes the design: per-worker instead of the shared zone,
config-as-code, the worker version already in the key (so a deploy invalidates on its own), and Vary
respected.

I'll redo the HTML side on top of that, in its own PR. No point merging a generator I already know is the
wrong approach.

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 7.56.0 🎉

The release is available on:

• blocks-v7.56.0
• GitHub release

Your semantic-release bot 📦🚀