@decocms/tanstack 8.0.0 → 8.1.0-next.0

package/src/routes/withSiteGlobals.ts

@@ -17,16 +17,17 @@
  *
  * export const Route = createFileRoute("/$")({
  *   ...withSiteGlobals(cmsRouteConfig({
- *     siteName: "Bagaggio",
- *     defaultTitle: "Bagaggio",
+ *     siteName: "Acme",
+ *     defaultTitle: "Acme",
  *   })),
  *   component: ...,
  * });
  * ```
  */
 
-import type { ResolvedSection } from "@decocms/blocks/cms";
+import type { MatcherContext, ResolvedSection } from "@decocms/blocks/cms";
 import { loadBlocks, onChange, resolvePageSections } from "@decocms/blocks/cms";
+import { createCacheStore, getCacheStorageContext } from "@decocms/blocks/sdk/cacheStorage";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -73,12 +74,18 @@ interface CacheEntry {
 const DEFAULT_CACHE_TTL_MS = 5 * 60_000;
 const cacheTtlMs = DEFAULT_CACHE_TTL_MS;
 
-let cache: CacheEntry | null = null;
-let inflight: Promise<CacheEntry> | null = null;
+// Keyed by request path — site.global/site.pageSections can contain
+// path-dependent matchers (pathname, multi(ETC Segment), date, etc.), so a
+// single process-wide cache entry would leak one route's matched variant onto
+// every other route (e.g. a /section-only alert winning on "/"). Caching a
+// resolvedSections array per path preserves the original 5-minute SWR behavior
+// while keeping each route's matcher evaluation correct.
+const cache = createCacheStore<CacheEntry>("site-globals");
+const inflight = new Map<string, Promise<CacheEntry>>();
 
 onChange(() => {
-  cache = null;
-  inflight = null;
+  cache.clear();
+  inflight.clear();
 });
 
 function readSiteBlock(): SiteBlock | null {
@@ -99,7 +106,7 @@ function gatherSectionRefs(site: SiteBlock): SiteGlobalRef[] {
 const EMPTY_ENTRY: CacheEntry = {
   resolvedSections: [],
   rawRefs: [],
-  expiresAt: Number.POSITIVE_INFINITY, // empty entries don't need refresh
+  expiresAt: 0,
 };
 
 /**
@@ -112,49 +119,60 @@ const EMPTY_ENTRY: CacheEntry = {
  * Exposed as a util so sites can call it directly if they need globals
  * outside the route loader path (rare).
  */
-export async function resolveSiteGlobals(): Promise<{
+export async function resolveSiteGlobals(matcherCtx?: MatcherContext): Promise<{
   resolvedSections: ResolvedSection[];
   rawRefs: SiteGlobalRef[];
 }> {
+  // Path/date/segment matchers inside site-global sections (e.g. a multivariate
+  // `Alert` gated by a pathname matcher) must evaluate against the actual
+  // request, and the result is cached per path so routes don't share variants.
+  const cacheKey = cache.key(matcherCtx?.path ?? "");
   const now = Date.now();
-  if (cache && cache.expiresAt > now) return cache;
-  if (inflight) return inflight;
+  const cached = getCacheStorageContext()?.storage
+    ? await cache.read(cacheKey)
+    : cache.get(cacheKey);
+  if (cached && cached.expiresAt > now) return cached;
+  const inflightEntry = inflight.get(cacheKey);
+  if (inflightEntry) return inflightEntry;
 
   const site = readSiteBlock();
   if (!site) {
     // Cache the empty result so subsequent requests don't re-walk the
     // block registry. `onChange` invalidation still applies — if a Site
-    // block appears later, the listener nulls `cache` and we re-check.
-    cache = EMPTY_ENTRY;
-    return EMPTY_ENTRY;
+    // block appears later, the listener clears `cache` and we re-check.
+    const empty = { ...EMPTY_ENTRY, expiresAt: Date.now() + cacheTtlMs };
+    cache.set(cacheKey, empty, empty.expiresAt);
+    return empty;
   }
 
   const rawRefs = gatherSectionRefs(site);
   if (rawRefs.length === 0) {
-    cache = EMPTY_ENTRY;
-    return EMPTY_ENTRY;
+    const empty = { ...EMPTY_ENTRY, expiresAt: Date.now() + cacheTtlMs };
+    cache.set(cacheKey, empty, empty.expiresAt);
+    return empty;
   }
 
-  inflight = (async () => {
+  const p = (async () => {
     try {
-      const resolvedSections = await resolvePageSections(rawRefs);
+      const resolvedSections = await resolvePageSections(rawRefs, matcherCtx);
       const entry: CacheEntry = {
         resolvedSections,
         rawRefs,
         expiresAt: Date.now() + cacheTtlMs,
       };
-      cache = entry;
+      cache.set(cacheKey, entry, entry.expiresAt);
       return entry;
     } catch (err) {
       console.error("[site-globals] failed to resolve:", err);
       // Don't cache failures — let the next request retry.
       return { resolvedSections: [], rawRefs, expiresAt: 0 };
     } finally {
-      inflight = null;
+      inflight.delete(cacheKey);
     }
   })();
 
-  return inflight;
+  inflight.set(cacheKey, p);
+  return p;
 }
 
 // ---------------------------------------------------------------------------
@@ -170,7 +188,10 @@ export async function resolveSiteGlobals(): Promise<{
  * both in `site.global` and in a page's section list, which would otherwise
  * render twice.
  */
-export function dedupeGlobals(globals: ResolvedSection[], existing: ResolvedSection[]): ResolvedSection[] {
+export function dedupeGlobals(
+  globals: ResolvedSection[],
+  existing: ResolvedSection[],
+): ResolvedSection[] {
   if (globals.length === 0) return [];
   const seenComponents = new Set<string>();
   for (const s of existing) {
@@ -217,6 +238,6 @@ export function withSiteGlobals<T extends { loader: AnyLoader }>(routeConfig: T)
 
 /** @internal */
 export function __resetSiteGlobalsCache() {
-  cache = null;
-  inflight = null;
+  cache.clear();
+  inflight.clear();
 }

package/src/sdk/backgroundTasks.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Workers run no timers between requests: core background work (release
+ * checks, telemetry batches) runs after the response, inside ctx.waitUntil
+ * (hosted-publishing.mdx, hosted-releases-internals.mdx, telemetry-internals.mdx).
+ */
+import { createCMS, type Loader, resetForTests } from "@decocms/blocks";
+import { setBlocks } from "@decocms/blocks/cms";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createDecoWorkerEntry } from "./workerEntry";
+
+const HOOK = Symbol.for("decocms.blocks.background");
+
+beforeEach(() => {
+  resetForTests();
+  setBlocks({}); // the v7 path this entry still runs reads redirects from it
+});
+afterEach(() => {
+  delete (globalThis as Record<symbol, unknown>)[HOOK];
+  resetForTests();
+});
+
+function context() {
+  const waited: Promise<unknown>[] = [];
+  return {
+    waited,
+    ctx: { waitUntil: (p: Promise<unknown>) => void waited.push(p), passThroughOnException() {} },
+  };
+}
+
+describe("createDecoWorkerEntry: background work", () => {
+  it("runs a due release check after the response, inside ctx.waitUntil", async () => {
+    const update = vi.fn(async () => ({ updated: false }));
+    const loader: Loader = {
+      load: async () => ({ revision: "r1", blocks: {} }),
+      update,
+    };
+    const cms = createCMS({ blocks: {}, content: loader });
+    let checkedBeforeResponse = true;
+    const worker = createDecoWorkerEntry(
+      {
+        fetch: async () => {
+          cms.forRelease();
+          await Promise.resolve();
+          checkedBeforeResponse = update.mock.calls.length > 0;
+          return new Response("ok");
+        },
+      },
+      { observability: false },
+    );
+    const { waited, ctx } = context();
+    const response = await worker.fetch(new Request("https://example.com/"), {}, ctx);
+    expect(await response.text()).toBe("ok");
+    expect(checkedBeforeResponse).toBe(false);
+    expect(waited).toHaveLength(1);
+    await Promise.all(waited);
+    expect(update).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls waitUntil only when there's something queued", async () => {
+    const worker = createDecoWorkerEntry(
+      { fetch: async () => new Response("ok") },
+      { observability: false },
+    );
+    const { waited, ctx } = context();
+    await worker.fetch(new Request("https://example.com/"), {}, ctx);
+    expect(waited).toHaveLength(0);
+  });
+});

package/src/sdk/backgroundTasks.ts

@@ -0,0 +1,38 @@
+/**
+ * Runs `@decocms/blocks` background work (release checks, telemetry batches)
+ * after each response, inside `ctx.waitUntil`. Workers run no timers between
+ * requests, so the core's timer fallback would never fire or would be bound
+ * to a finished request. See /next/hosted-releases-internals and
+ * /next/telemetry-internals#sending-in-the-background.
+ *
+ * The hook is installed once per isolate under the `Symbol.for` key the core
+ * looks for; its queue lives on the hook itself, so two copies of this module
+ * share one queue.
+ */
+
+const HOOK = Symbol.for("decocms.blocks.background");
+
+type Task = () => Promise<void>;
+type Hook = ((task: Task) => void) & { queue: Task[] };
+
+function hook(): Hook {
+  const g = globalThis as unknown as Record<symbol, Hook | undefined>;
+  const existing = g[HOOK];
+  if (typeof existing === "function" && Array.isArray(existing.queue)) return existing;
+  const queue: Task[] = [];
+  const installed = Object.assign((task: Task) => void queue.push(task), { queue });
+  g[HOOK] = installed;
+  return installed;
+}
+
+/** Installs the hook (idempotent): from now on, core background work queues here. */
+export function installBackgroundHook(): void {
+  hook();
+}
+
+/** Runs everything queued so far inside `ctx.waitUntil`. */
+export function runBackgroundTasks(ctx: { waitUntil(promise: Promise<unknown>): void }): void {
+  const tasks = hook().queue.splice(0);
+  if (tasks.length === 0) return;
+  ctx.waitUntil(Promise.all(tasks.map((task) => task().catch(() => {}))));
+}

package/src/sdk/cdnSegment.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { segmentToken } from "./cdnSegment";
+
+const BUILD = "abc123";
+
+describe("segmentToken", () => {
+  it("produces a token for an anonymous visitor", () => {
+    expect(segmentToken("desktop", false, BUILD)).toBeTruthy();
+  });
+
+  it("gives different segments different tokens", () => {
+    // The whole point: the URL has to distinguish what the Worker's key
+    // distinguishes, or a cache in front serves one visitor another's response.
+    const tokens = ["desktop", "mobile", "desktop|r=RJ", "desktop|r=SP", "desktop|sc=3|r=RJ"].map(
+      (s) => segmentToken(s, false, BUILD),
+    );
+    expect(new Set(tokens).size).toBe(tokens.length);
+  });
+
+  it("regionalized and non-regionalized visitors never share a token", () => {
+    // This is the case that made the first version inert on real stores: region
+    // is resolved server-side from cf.regionCode, so it MUST be in the token.
+    expect(segmentToken("desktop", false, BUILD)).not.toBe(
+      segmentToken("desktop|r=RJ", false, BUILD),
+    );
+  });
+
+  it("is stable for the same segment and build", () => {
+    // The worker verifies by recomputing, so the same input must always give
+    // the same token — otherwise nothing would ever match.
+    expect(segmentToken("desktop|r=RJ", false, BUILD)).toBe(
+      segmentToken("desktop|r=RJ", false, BUILD),
+    );
+  });
+
+  it("refuses a logged-in visitor regardless of segment precision", () => {
+    // Personalized responses never belong in a shared entry, however exact the
+    // key is.
+    expect(segmentToken("desktop|auth|r=RJ", true, BUILD)).toBeNull();
+  });
+
+  it("refuses a missing or dev build hash", () => {
+    // Without a build hash there is no way to invalidate on deploy — the cache
+    // in front would keep serving stale code.
+    expect(segmentToken("desktop", false, undefined)).toBeNull();
+    expect(segmentToken("desktop", false, "")).toBeNull();
+    expect(segmentToken("desktop", false, "dev")).toBeNull();
+  });
+
+  it("changes with the build, so a deploy invalidates it", () => {
+    expect(segmentToken("desktop", false, "buildA")).not.toBe(
+      segmentToken("desktop", false, "buildB"),
+    );
+  });
+
+  it("refuses an empty segment descriptor", () => {
+    expect(segmentToken("", false, BUILD)).toBeNull();
+  });
+
+  it("is URL-safe even when the segment carries a VTEX region id", () => {
+    // `v2.XXXX` contains the character an earlier format used as a separator;
+    // hashing sidesteps escaping entirely.
+    const t = segmentToken("desktop|r=v2.ABC-123|sc=3", false, BUILD);
+    expect(t).toMatch(/^[a-z0-9]+$/);
+    expect(encodeURIComponent(t as string)).toBe(t);
+  });
+});

package/src/sdk/cdnSegment.ts

@@ -0,0 +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}`);
+}

package/src/sdk/deferredSectionLoader.test.ts

@@ -3,7 +3,7 @@
  * (`@decocms/tanstack/sdk/deferredSectionLoader`).
  *
  * Before 7.7 this wrapper was unreachable from any public subpath, so
- * migrated sites (lebiscuit, miess, granadobr, casaevideo) each carried a
+ * migrated production storefronts each carried a
  * byte-identical local shim wrapping the public `loadDeferredSection`
  * export. The cases below are derived from how those sites call it: it is
  * passed verbatim as `<DecoPageRenderer loadDeferredSectionFn={...} />`,