feat(tanstack): server issues the CDN segment token, so regionalized stores engage #524
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| /** | ||
| * Publishes the CDN segment token this server computed, so `decoServerFnFetch` | ||
| * can echo it back on `/_serverFn` URLs. | ||
| * | ||
| * Only the server can produce this value: the segment includes dimensions the | ||
| * browser cannot observe — region is resolved from `request.cf.regionCode`. | ||
| * A client that derives its own token therefore never matches on a | ||
| * regionalized store, which is exactly why this component exists. | ||
| * | ||
| * - **Server:** read the token from the RequestContext bag (filled by | ||
| * `createDecoWorkerEntry`) and emit a tiny inline `<script>`. | ||
| * - **Client:** the bag is a no-op stub, so the read yields undefined and this | ||
| * renders nothing — the global set during SSR is already on `window`. | ||
| * | ||
| * Safe in a cached response: the Worker's edge cache keys on the segment, so a | ||
| * stored entry carries the token of its own segment. And a stale token is | ||
| * harmless by construction — the Worker verifies by recomputing and falls back | ||
| * to `no-store` when it doesn't match. | ||
| */ | ||
| import { RequestContext } from "@decocms/blocks/sdk/requestContext"; | ||
| import { CSEG_BAG_KEY, CSEG_GLOBAL } from "../sdk/cdnSegment"; | ||
|
|
||
| export function CdnSegmentMarker() { | ||
| const token = RequestContext.getBag<string>(CSEG_BAG_KEY); | ||
| if (!token) return null; | ||
| return ( | ||
| <script | ||
| // A hash this server computed, not user input. JSON.stringify keeps it | ||
| // inert regardless. | ||
| dangerouslySetInnerHTML={{ | ||
| __html: `window.${CSEG_GLOBAL}=${JSON.stringify(token)}`, | ||
| }} | ||
| /> | ||
| ); | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,74 +1,71 @@ | ||
| /** | ||
| * Segment marker on `/_serverFn` URLs, so a cache in front of the Worker can | ||
| * serve the response without invoking it. | ||
| * | ||
| * The problem: whatever sits in front (Workers Cache, a CDN rule) keys on the | ||
| * raw URL. The Worker keys on a SYNTHETIC Request carrying | ||
| * `__seg`/`__cf_device`/`__bot`/`__fetch`/`__abf` (`buildCacheKey` in | ||
| * `./workerEntry`) — params the URL never shows. That mismatch is why the | ||
| * framework stamps `CDN-Cache-Control: no-store` on public responses. | ||
| * | ||
| * The fix: put the segment in the URL itself, so the two keys become | ||
| * equivalent. | ||
| * | ||
| * ## Why the SERVER issues the token | ||
| * | ||
| * The first version had the client derive the token from what it could see | ||
| * (`navigator.userAgent`). That only ever worked on sites whose segment | ||
| * reduces to device alone. A regionalized VTEX store — most of them — segments | ||
| * on region too, and region is resolved from `request.cf.regionCode`, which | ||
| * exists **only** on the server. The client cannot see it, so its token never | ||
| * matched and the feature stayed permanently inert. | ||
| * | ||
| * So the server computes the token from the segment it already built, publishes | ||
| * it to the page, and the client only echoes it back. The Worker still verifies | ||
| * by recomputing — the marker is never trusted, so a stale or forged one just | ||
| * keeps the `no-store`. | ||
| * | ||
| * The token is a hash rather than readable fields: `regionId` can contain the | ||
| * separator (`v2.XXXX`), values would need escaping, and there is no reason to | ||
| * publish a visitor's region in a URL that ends up in logs. | ||
| */ | ||
|
|
||
| import { djb2Hex } from "@decocms/blocks/sdk/djb2"; | ||
|
|
||
| /** `__d` is reserved: `workerEntry` uses `?__d=` as an OTel debug flag. */ | ||
| export const CSEG_PARAM = "__cseg"; | ||
|
|
||
| /** Global the SSR publishes the token on, read back by `decoServerFnFetch`. */ | ||
| export const CSEG_GLOBAL = "__DECO_CSEG"; | ||
|
|
||
| /** RequestContext bag key the worker entry fills before rendering. */ | ||
| export const CSEG_BAG_KEY = "deco.cdn.segmentToken"; | ||
|
|
||
| /** | ||
| * Build the token for a segment, or `null` when this request must not be | ||
| * cached in front of the Worker. | ||
| * | ||
| * `null` — i.e. keep `no-store` — when: | ||
| * | ||
| * - the visitor is logged in. Personalized responses never belong in a shared | ||
| * entry, no matter how precise the key is. | ||
| * - there is no build hash, or it is `"dev"`. The build is part of the token | ||
| * because deploying does not purge the cache in front, so the URL has to | ||
| * change on its own when the bundle does. | ||
| * | ||
| * Everything else in the segment — device, sales channel, region, a site's own | ||
| * custom dimensions — is folded INTO the token rather than rejected. That is | ||
| * the difference from the first version: those are what the key needs to | ||
| * distinguish, not reasons to give up on caching. | ||
| */ | ||
| export function segmentToken( | ||
| segmentDescriptor: string, | ||
| loggedIn: boolean, | ||
| buildHash: string | undefined, | ||
| ): string | null { | ||
| if (loggedIn) return null; | ||
| if (!buildHash || buildHash === "dev") return null; | ||
| if (!segmentDescriptor) return null; | ||
|
|
||
| return djb2Hex(`${segmentDescriptor}|${buildHash}`); | ||
|
There was a problem hiding this comment. P1: When two segment descriptors collide in this 32-bit hash, Prompt for AI agents |
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,63 +1,59 @@ | ||
| /** | ||
| * Client-side `serverFns.fetch` hook that echoes the CDN segment marker onto | ||
| * `/_serverFn` URLs. | ||
| * | ||
| * Pairs with `cdnCacheControl: "serverfn-segment"` on `createDecoWorkerEntry`. | ||
| * Putting the segment in the URL is what makes the key of whatever caches in | ||
| * front of the Worker equivalent to the Worker's own — see `./cdnSegment`. | ||
| * | ||
| * The client does not COMPUTE the token, it repeats one the server issued and | ||
| * published on the page. That is deliberate: the segment includes dimensions | ||
| * only the server can see (region comes from `request.cf`), so a client-derived | ||
| * token never matched on a regionalized store and the feature stayed inert | ||
| * there. | ||
| * | ||
| * Only client-initiated requests carry it — SPA navigation and prefetch, which | ||
| * is the volume Speculation Rules generates. The initial HTML document is a | ||
| * browser navigation with no hook to attach anything to. | ||
| * | ||
| * SECURITY: the marker is a HINT. The worker recomputes the segment from the | ||
| * request itself and only relaxes `no-store` on an exact match | ||
| * (`cdnCacheableServerFn` in `./workerEntry`). A missing, stale, forged or | ||
| * mismatched marker just keeps today's `no-store` — it can never produce a | ||
| * wrong response. | ||
| * | ||
| * Wired automatically: `decoVitePlugin` supplies `sdk/startEntry` as the Start | ||
| * entry when a site has no `src/start.ts` of its own. A site that owns one | ||
| * composes this itself: | ||
| * | ||
| * ```ts | ||
| * import { decoServerFnFetch } from "@decocms/tanstack/sdk/serverFnFetch"; | ||
| * export const startInstance = createStart(() => ({ | ||
| * serverFns: { fetch: decoServerFnFetch }, | ||
| * })); | ||
| * ``` | ||
| */ | ||
|
|
||
| import { CSEG_GLOBAL, CSEG_PARAM } from "./cdnSegment"; | ||
|
|
||
| function publishedMarker(): string | null { | ||
| if (typeof window === "undefined") return null; | ||
| const v = (window as unknown as Record<string, unknown>)[CSEG_GLOBAL]; | ||
| return typeof v === "string" && v.length > 0 ? v : null; | ||
| } | ||
|
|
||
| /** | ||
| * Drop-in `serverFns.fetch`. Falls back to a plain `fetch` whenever there is no | ||
| * marker to echo — no marker simply means the response stays uncached in front | ||
| * of the Worker, which is the previous behaviour. | ||
| */ | ||
| export const decoServerFnFetch: typeof fetch = (input, init) => { | ||
| // TanStack's serverFnFetcher always calls with the URL already built as a | ||
| // string (start-client-core/src/client-rpc/serverFnFetcher.ts). Anything else | ||
| // goes through untouched. | ||
| if (typeof input !== "string") return fetch(input, init); | ||
| const marker = publishedMarker(); | ||
| if (!marker) return fetch(input, init); | ||
| const sep = input.includes("?") ? "&" : "?"; | ||
| return fetch(`${input}${sep}${CSEG_PARAM}=${encodeURIComponent(marker)}`, init); | ||
| }; |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2: When SSR publishes a token, the client hydration tree omits this server-rendered
<script>because the browserRequestContextbag is empty. React therefore reports a hydration mismatch and can discard the SSR tree; readwindow.__DECO_CSEGon the client and render the same script node, asDraftPreviewIndicatordoes.Prompt for AI agents