feat(tanstack): cache de CDN para /_serverFn via marcador de segmento na URL

[JonasJesus42]

Separado do #510 a pedido do review. Depende de #512 (hotfix de rotas privadas), que é a base desta branch —
mergear aquele primeiro.

O problema

Qualquer camada na frente do Worker chaveia pela URL crua. O Worker chaveia por uma Request sintética que
carrega __seg/__cf_device/__cf_geo/__bot/__fetch/__abf (buildCacheKey). É essa divergência que
obriga o CDN-Cache-Control: no-store em toda resposta, e por isso 100% do tráfego invoca o Worker.

A solução, para /_serverFn

Inverte o problema: em vez de esperar que a camada da frente reproduza a chave, o cliente põe o segmento na
própria URL (?__cseg=<device>.<buildHash>), o que torna as duas chaves equivalentes.

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

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

Cobre navegação SPA e prefetch — o volume que o Speculation Rules gera. Default inalterado.

Por que é seguro

O marcador é dica, não fonte de verdade. O Worker recalcula o segmento do próprio request e só relaxa o
no-store quando confere exatamente. Mantêm o no-store:

marcador ausente · divergente · forjado · de build antigo · logado · região · canal ≠ 1 · campo custom
desconhecido no SegmentKey · UA de bot · cookie de A/B · chave que varia por geo

O pior caso é não cachear, nunca uma resposta errada.

isBot e o cookie de A/B são checados com os mesmos helpers que o buildCacheKey usa — chavear e liberar
por predicados diferentes é exatamente como os dois divergem em silêncio.

O build hash entra no token porque deploy não purga quem estiver cacheando a resposta; a URL precisa mudar
sozinha quando o bundle muda.

HTML continua no-store: a navegação inicial é request do browser, sem hook de JS para anexar marcador.

Também aqui: match-profile virou armadilha silenciosa

O JSDoc prometia segurança "sem buildSegment e deviceSpecificKeys: false", mas deviceSpecificKeys é
true por default — a condição é falsa em todo site. Quem seguisse a doc cross-serviria segmentos sem aviso.
Agora é recusado com warning.

Procedência

Portado de uma implementação que já roda em produção num site, com dois gaps fechados: aquela versão
verificava só o device, deixando bots (que executam JS — Lighthouse, PageSpeed) e cohorts de A/B envenenarem
uma entrada compartilhada. No site, isso substituiu ~230 linhas de shim por 6 linhas + um start.ts de 9.

Validação

Testado end-to-end contra um site real buildado, não só unit: pacotes linkados, bun run build, worker no
wrangler dev, navegação SPA dirigida por Chrome.

caso	Cdn-Cache-Control
GET /_serverFn com marcador correto (desktop e mobile)	public, max-age=1800 ✅
sem marcador	no-store
marcador de outro device (forjado)	no-store
build antigo	no-store
UA de bot	no-store
cookie de login	no-store
cookie de A/B	no-store
documento HTML	no-store

O valor liberado bate exatamente com o que a implementação de site produz em produção.

2573 testes passando. Typecheck limpo.

As 4 falhas em draft preview são pré-existentes no main.

O que ficou de fora

O gerador de Cache Rules que estava no #510 saiu. O review apontou — corretamente — que em sites servidos
por Workers não existe cache na frente, e que o caminho é o Workers Cache (cache: { enabled: true } no
wrangler), não Cache Rules na zona. Isso muda o desenho: é por worker em vez da zona compartilhada, é
config-as-code, a versão do worker já entra na chave (deploy invalida sozinho) e o Vary é respeitado.

Vou refazer a parte de HTML em cima disso, em PR próprio. Não fazia sentido mergear um gerador que já sei que
é a abordagem errada.

🤖 Generated with Claude Code

---

Summary by cubic

Enables opt-in CDN caching for /_serverFn requests by making the CDN's cache key (the raw URL) match the Worker's, and hardens the cache boundaries that change depends on.

The client now attaches a segment marker (?__cseg=<device>.<buildHash>) to /_serverFn URLs; the Worker recomputes the segment from the request and only relaxes CDN-Cache-Control on an exact match. Absent, diverging, forged, or stale-build markers keep today's no-store — the worst case is not caching, never a wrong response.

New Features

• cdnCacheControl: "serverfn-segment" on createDecoWorkerEntry, paired with the decoServerFnFetch client hook wired in src/start.ts.
• Covers SPA navigation and prefetch; HTML documents stay no-store since the initial navigation has no client hook to attach a marker.
• Build hash is part of the token so stale CDN entries invalidate when the bundle changes.
• Bot UAs and A/B cohort cookies are rejected using the same helpers buildCacheKey uses.

Bug Fixes

• cdnCacheControl: "match-profile" is now refused (with a warning) while the cache key is segmented — its JSDoc promised safety that never held since deviceSpecificKeys defaults to true.
• Private path detection now covers wishlist, profile, signup, and returns routes (previously fell through to the cacheable listing default), is case-insensitive, and tolerates locale prefixes.
• setCacheProfile refuses to flip private/cart/none profiles public; custom cache patterns can no longer make a private path public, and the new registerPrivatePaths() is the safe way to add private routes.
• VTEX middleware no longer overwrites the cache layer's Cache-Control on every response — it only personalizes for logged-in or custom-pricing requests, and clears CDN-Cache-Control when it does.
• Cache bypasses fail closed: unparseable set-cookie values are never cached, bypassPaths always extends the framework defaults, and CDN-Cache-Control is decided at the single response exit (bypass or absent header → no-store).

^{Written for commit b079c94. Summary will update on new commits.}