@decocms/tanstack 7.78.1 → 7.79.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.78.1",
+  "version": "7.79.0",
   "type": "module",
   "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
   "repository": {
@@ -27,9 +27,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.78.1",
-    "@decocms/blocks-admin": "7.78.1",
-    "@decocms/blocks-cli": "7.78.1",
+    "@decocms/blocks": "7.79.0",
+    "@decocms/blocks-admin": "7.79.0",
+    "@decocms/blocks-cli": "7.79.0",
     "@deco-cx/warp-node": "^0.3.16",
     "fast-json-patch": "^3.1.0",
     "ws": "^8.18.0"

package/src/routes/cmsRoute.ts

@@ -69,6 +69,7 @@ import {
 } from "@tanstack/react-start/server";
 import { createElement } from "react";
 import { derivePageUrl, isClientNavigation } from "./pageUrl";
+import { createRequestSingleFlight } from "./requestSingleFlight";
 import { dedupeGlobals, resolveSiteGlobals } from "./withSiteGlobals";
 import type { SiteGlobalRef } from "./withSiteGlobals";
 
@@ -92,7 +93,7 @@ export function setSectionChunkMap(map: Record<string, string>): void {
 // ---------------------------------------------------------------------------
 
 type PageResult = Awaited<ReturnType<typeof loadCmsPageInternal>>;
-const pageInflight = new Map<string, Promise<PageResult>>();
+const loadPageForRequest = createRequestSingleFlight<PageResult>();
 
 /** Same shape as `resolveSiteGlobals()`'s empty result — used when `resolveGlobals: false`. */
 const EMPTY_GLOBALS: { resolvedSections: ResolvedSection[]; rawRefs: SiteGlobalRef[] } = {
@@ -337,33 +338,15 @@ export const loadCmsPage = createServerFn({ method: "GET" })
   .handler(async (ctx) => {
     const { path: fullPath, resolveGlobals } = parseLoadCmsPageInput(ctx.data);
 
-    // Use the full path (including query string) as the dedup key.
-    // Using basePath only caused /s?q=a and /s?q=b to share one promise,
-    // returning wrong/empty results for search and filtered PLPs.
-    //
-    // SSR and client-nav produce the same eager/deferred split now, so the
-    // original reason for the `__nav:` bucket — a client-nav request must never
-    // inherit an SSR response's deferredSections (#277) — no longer applies. It
-    // is kept anyway, because this map is module-global and the payload it
-    // shares carries `pageUrl`, `flags`, and `device` derived from whichever
-    // request won the race. That cross-request bleed is pre-existing and wider
-    // than this bucket (two concurrent same-path requests already collide on
-    // cookies/UA/geo), but SSR and client-nav are exactly the pair whose
-    // `derivePageUrl` inputs differ most, so collapsing them would widen a
-    // known hole for no gain. `resolveGlobals` is part of the key for the same
-    // reason: a `resolveGlobals: false` request must not share a promise with a
-    // `resolveGlobals: true` one.
+    // Whole-page results contain request-specific cookies, flags, device and URL.
+    // A module-global URL key also lets one stalled request block later visitors.
+    // Dedup only within this request; keep query and globals options distinct.
     const clientNav = isClientNavigation(fullPath, getRequestUrl());
     const inflightKey =
       (clientNav ? `__nav:${fullPath}` : fullPath) + (resolveGlobals ? "" : "|noGlobals");
-    const existing = pageInflight.get(inflightKey);
-    if (existing) return existing;
-
-    const promise = loadCmsPageInternal(fullPath, resolveGlobals).finally(() =>
-      pageInflight.delete(inflightKey),
+    return loadPageForRequest(getRequest(), inflightKey, () =>
+      loadCmsPageInternal(fullPath, resolveGlobals),
     );
-    pageInflight.set(inflightKey, promise);
-    return promise;
   });
 
 /** Accepted by `loadCmsHomePage` — optional so existing no-arg callers keep working. */

package/src/routes/requestSingleFlight.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from "vitest";
+import { createRequestSingleFlight } from "./requestSingleFlight";
+
+describe("request-scoped page single-flight", () => {
+  it("lets a healthy visitor complete while an earlier visitor's page is stuck", async () => {
+    const load = createRequestSingleFlight<string>();
+    const path = "/granado/sabonetes/sabonete-barra";
+    let release!: (value: string) => void;
+    const first = load(
+      new Request(`https://shop.test${path}`),
+      path,
+      () =>
+        new Promise<string>((resolve) => {
+          release = resolve;
+        }),
+    );
+    const healthy = load(
+      new Request(`https://shop.test${path}`),
+      path,
+      async () => "healthy visitor",
+    );
+    try {
+      expect(
+        await Promise.race([
+          healthy,
+          new Promise((resolve) => setTimeout(() => resolve("blocked"), 100)),
+        ]),
+      ).toBe("healthy visitor");
+    } finally {
+      release("earlier visitor");
+      await first;
+    }
+  });
+
+  it("deduplicates concurrent callers within one request and removes completed work", async () => {
+    const load = createRequestSingleFlight<string>();
+    const request = new Request("https://shop.test/category");
+    const run = vi.fn(async () => "page");
+    const first = load(request, "/category", run);
+    expect(load(request, "/category", run)).toBe(first);
+    await first;
+    await load(request, "/category", run);
+    expect(run).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps page options separate and allows retry after a failure", async () => {
+    const load = createRequestSingleFlight<string>();
+    const request = new Request("https://shop.test/category");
+    await expect(
+      load(request, "/category", async () => {
+        throw new Error("failed");
+      }),
+    ).rejects.toThrow("failed");
+    expect(await load(request, "/category", async () => "retry")).toBe("retry");
+    const results = await Promise.all([
+      load(request, "/category?p=1", async () => "first page"),
+      load(request, "/category?p=2", async () => "second page"),
+      load(request, "/category?p=1|noGlobals", async () => "without globals"),
+    ]);
+    expect(results).toEqual(["first page", "second page", "without globals"]);
+  });
+});

package/src/routes/requestSingleFlight.ts

@@ -0,0 +1,17 @@
+/** Share pending work only among callers belonging to the same HTTP request. */
+export function createRequestSingleFlight<T>() {
+  const requests = new WeakMap<Request, Map<string, Promise<T>>>();
+
+  return (request: Request, key: string, run: () => Promise<T>): Promise<T> => {
+    const pending = requests.get(request) ?? new Map<string, Promise<T>>();
+    requests.set(request, pending);
+    const existing = pending.get(key);
+    if (existing) return existing;
+
+    const promise = Promise.resolve()
+      .then(run)
+      .finally(() => pending.delete(key));
+    pending.set(key, promise);
+    return promise;
+  };
+}

package/src/sdk/kvHydration.ts

@@ -51,6 +51,8 @@ const G = globalThis as unknown as {
     kvHydrated?: boolean;
     kvHydration?: Promise<void> | null;
     kvLastPolledAt?: number;
+    dataVersion?: string | null;
+    dataVersionAt?: number;
   };
 };
 if (!G.__deco) G.__deco = {};
@@ -255,9 +257,62 @@ async function pollRevisionOnce(kv: KVNamespace, deploymentId: string): Promise<
   }
 }
 
+/** KV key holding the preserved data-cache version. Writing a new value (the
+ * control-plane does, via the CF API) purges preserved loader/fetch data for
+ * every isolate within one poll — no deploy. */
+export const DATA_CACHE_VERSION_KEY = "cache:data-version";
+
+/** Deadline for one `cache:data-version` read. Calibration knob. */
+export const DATA_VERSION_TIMEOUT_MS = 1_000;
+
+/**
+ * Current `DATA_CACHE_VERSION_KEY` value, or "" without a `DECO_KV` binding.
+ * The first call per isolate awaits the read (so a cold isolate never reads
+ * purged keys); after that the cached value is returned and refreshed in the
+ * background every `POLL_INTERVAL_MS`. A failed or slow read (over
+ * `DATA_VERSION_TIMEOUT_MS`) keeps the last value. Only resolved strings are
+ * kept, never a pending read: a `DECO_KV.get` that never settles would otherwise
+ * hold every later request of the isolate.
+ */
+export async function getDataCacheVersion(env: Env, ctx?: ExecutionContextLike): Promise<string> {
+  const kv = getKV(env);
+  if (!kv) return "";
+  const d = G.__deco!;
+  const read = (prev: string): Promise<string> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    return Promise.race([
+      kv.get(DATA_CACHE_VERSION_KEY).then(
+        (v) => v ?? "",
+        () => prev,
+      ),
+      new Promise<string>((resolve) => {
+        timer = setTimeout(() => resolve(prev), DATA_VERSION_TIMEOUT_MS);
+      }),
+    ]).finally(() => clearTimeout(timer));
+  };
+  if (d.dataVersion == null) {
+    d.dataVersionAt = Date.now();
+    d.dataVersion = await read("");
+    return d.dataVersion;
+  }
+  const current = d.dataVersion;
+  if (Date.now() - (d.dataVersionAt ?? 0) >= POLL_INTERVAL_MS) {
+    d.dataVersionAt = Date.now();
+    // Background refresh: requests keep the current value meanwhile.
+    const swap = read(current).then((v) => {
+      d.dataVersion = v;
+    });
+    if (ctx?.waitUntil) ctx.waitUntil(swap);
+    else void swap.catch(() => {});
+  }
+  return current;
+}
+
 /** Test-only: reset the isolate-level hydration flags. */
 export function __resetKvHydrationStateForTests(): void {
   G.__deco!.kvHydrated = false;
   G.__deco!.kvHydration = null;
   G.__deco!.kvLastPolledAt = 0;
+  G.__deco!.dataVersion = null;
+  G.__deco!.dataVersionAt = 0;
 }

package/src/sdk/workerEntry.cacheStorage.test.ts

@@ -8,6 +8,15 @@ import {
   getCacheStorageContext,
 } from "@decocms/blocks/sdk/cacheStorage";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createFetchCache } from "@decocms/blocks/sdk/fetchCache";
+import { __resetKvHydrationStateForTests, DATA_VERSION_TIMEOUT_MS } from "./kvHydration";
+
+const FETCH_KNOBS = {
+  maxEntries: 10,
+  freshTtlMs: { success: 60_000, notFound: 1_000, serverError: 0 },
+  staleIfErrorMs: 60_000,
+  inflightBackstopMs: 5_000,
+};
 import { createDecoWorkerEntry } from "./workerEntry";
 
 function makeKV(): CacheKVNamespace {
@@ -91,6 +100,123 @@ describe("worker cache storage injection", () => {
     await flush();
   });
 
+  // A fresh fetch cache per request: its memory tier can't answer, so a hit
+  // proves the shared (KV) entry was found under the same key.
+  function fetchWorker(opts: object = {}) {
+    const upstream = vi.fn(async () => Response.json({ ok: true }));
+    const worker = createDecoWorkerEntry(
+      {
+        fetch: async () => {
+          const cache = createFetchCache({ provider: "test", ...FETCH_KNOBS });
+          const body = await cache.fetchWithCache("https://upstream.test/x", upstream);
+          return Response.json(body, { headers: { "cache-control": "no-store" } });
+        },
+      },
+      { ...options, ...opts },
+    );
+    return { worker, upstream };
+  }
+
+  it("DECO_DATA_CACHE_ON_DEPLOY=preserve keeps fetch results across deploys and publishes", async () => {
+    const { worker, upstream } = fetchWorker();
+    const bindings = { ...env(), DECO_DATA_CACHE_ON_DEPLOY: "preserve" };
+    await worker.fetch(request("/one"), bindings, ctx);
+    await flush();
+    // Distinct paths: only the fetch cache is under test, not the HTML cache.
+    await worker.fetch(request("/two"), { ...bindings, BUILD_HASH: "build-B" }, ctx);
+    // A CMS publish (new decofile revision) keeps them too.
+    setBlocks({ published: { __resolveType: "x" } });
+    await worker.fetch(request("/three"), { ...bindings, BUILD_HASH: "build-B" }, ctx);
+    expect(upstream).toHaveBeenCalledTimes(1);
+    // A new DECO_DATA_CACHE_PURGE value drops the preserved data once.
+    await worker.fetch(request("/four"), { ...bindings, DECO_DATA_CACHE_PURGE: "2026-09-22" }, ctx);
+    expect(upstream).toHaveBeenCalledTimes(2);
+    await flush();
+  });
+
+  it("loader results stay per-build even with preserve", async () => {
+    const upstream = vi.fn(async () => ({ n: 1 }));
+    const loader = createCachedLoader("worker-preserve-loader", upstream, {
+      policy: "no-cache",
+      maxAge: 60_000,
+    });
+    const worker = createDecoWorkerEntry(
+      {
+        fetch: async () =>
+          Response.json(await loader({}), { headers: { "cache-control": "no-store" } }),
+      },
+      options,
+    );
+    const bindings = { ...env(), DECO_DATA_CACHE_ON_DEPLOY: "preserve" };
+    await worker.fetch(request("/a"), bindings, ctx);
+    await flush();
+    clearLoaderCache();
+    await worker.fetch(request("/b"), { ...bindings, BUILD_HASH: "build-B" }, ctx);
+    expect(upstream).toHaveBeenCalledTimes(2);
+    await flush();
+  });
+
+  it("invalidate or unset keeps fetch results per build", async () => {
+    for (const extra of [{}, { DECO_DATA_CACHE_ON_DEPLOY: "invalidate" }, { DECO_DATA_CACHE_ON_DEPLOY: "yes" }]) {
+      const { worker, upstream } = fetchWorker();
+      const bindings = { ...env(), ...extra };
+      await worker.fetch(request("/a"), bindings, ctx);
+      await flush();
+      await worker.fetch(request("/b"), { ...bindings, BUILD_HASH: "build-B" }, ctx);
+      expect(upstream).toHaveBeenCalledTimes(2);
+      await flush();
+    }
+  });
+
+  it("a new cache:data-version in DECO_KV purges preserved data without a deploy", async () => {
+    __resetKvHydrationStateForTests();
+    const { worker, upstream } = fetchWorker();
+    const DECO_KV = makeKV();
+    const bindings = { ...env(), DECO_KV, DECO_DATA_CACHE_ON_DEPLOY: "preserve" };
+    await worker.fetch(request("/a"), bindings, ctx);
+    await flush();
+    await worker.fetch(request("/b"), bindings, ctx);
+    expect(upstream).toHaveBeenCalledTimes(1);
+    await DECO_KV.put("cache:data-version", "v2", { expirationTtl: 60 });
+    __resetKvHydrationStateForTests(); // skip the poll interval
+    await worker.fetch(request("/c"), bindings, ctx);
+    expect(upstream).toHaveBeenCalledTimes(2);
+    await flush();
+  });
+
+  it("a hung cache:data-version read falls back instead of holding the request", async () => {
+    vi.useFakeTimers();
+    try {
+      __resetKvHydrationStateForTests();
+      const { worker, upstream } = fetchWorker();
+      const DECO_KV = { ...makeKV(), get: () => new Promise<string | null>(() => {}) };
+      const bindings = { ...env(), DECO_KV, DECO_DATA_CACHE_ON_DEPLOY: "preserve" };
+      const pending = worker.fetch(request("/a"), bindings, ctx);
+      await vi.advanceTimersByTimeAsync(DATA_VERSION_TIMEOUT_MS);
+      expect((await pending).status).toBe(200);
+      expect(upstream).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+      await flush();
+    }
+  });
+
+  it("honours dataCacheOnDeployEnv renames and opt-out", async () => {
+    const run = async (opts: object, extra: Record<string, string>) => {
+      const { worker, upstream } = fetchWorker(opts);
+      const bindings = { ...env(), ...extra };
+      await worker.fetch(request("/a"), bindings, ctx);
+      await flush();
+      await worker.fetch(request("/b"), { ...bindings, BUILD_HASH: "build-B" }, ctx);
+      await flush();
+      return upstream.mock.calls.length;
+    };
+    expect(await run({ dataCacheOnDeployEnv: "KEEP" }, { KEEP: "preserve" })).toBe(1);
+    expect(
+      await run({ dataCacheOnDeployEnv: false }, { DECO_DATA_CACHE_ON_DEPLOY: "preserve" }),
+    ).toBe(2);
+  });
+
   it("stores public server-function POSTs by body and excludes unmarked responses", async () => {
     const origin = {
       fetch: vi.fn(

package/src/sdk/workerEntry.ts

@@ -105,7 +105,7 @@ import {
   registerDraftOverride,
   requestCarriesDraft,
 } from "./draft";
-import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
+import { ensureBlocksHydrated, getDataCacheVersion, maybePollRevision } from "./kvHydration";
 import { lookupExactRedirect } from "./kvRedirects";
 import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
 import { type SpeculationRulesConfig, setSpeculationRules } from "./speculationRules";
@@ -423,6 +423,33 @@ export interface DecoWorkerEntryOptions {
    */
   cacheVersionEnv?: string | false;
 
+  /**
+   * Environment variable choosing what a deploy does to the `createFetchCache`
+   * entries (`fetch:*`, raw upstream responses) in shared storage (e.g. KV):
+   *
+   *   - `"invalidate"` (or unset — the default): keyed by build and CMS revision,
+   *     a deploy or publish starts them cold. Today's behaviour.
+   *   - `"preserve"`: keyed without build or CMS revision, they survive both.
+   *     A raw response doesn't depend on the code or the decofile; the new
+   *     code re-transforms it, so a deploy can't serve an old shape.
+   *
+   * `cachedLoader` results, HTML responses and sections stay per-build in both
+   * modes: they hold code output. Segment/device and geo stay in every key.
+   * Any other value falls back to `"invalidate"`.
+   *
+   * To drop preserved responses once, set `DECO_DATA_CACHE_PURGE` to a new value
+   * (any string, e.g. the date), or write a new `cache:data-version` in DECO_KV.
+   *
+   * @default "DECO_DATA_CACHE_ON_DEPLOY"
+   *
+   * @example
+   * ```jsonc
+   * // wrangler.jsonc
+   * "vars": { "DECO_DATA_CACHE_ON_DEPLOY": "preserve" }
+   * ```
+   */
+  dataCacheOnDeployEnv?: string | false;
+
   /**
    * Security headers appended to every SSR response (HTML pages).
    * Pass `false` to disable entirely.
@@ -1186,6 +1213,7 @@ export function createDecoWorkerEntry(
     redirects: redirectsOpt,
     previewShell: customPreviewShell,
     cacheVersionEnv = "BUILD_HASH",
+    dataCacheOnDeployEnv = "DECO_DATA_CACHE_ON_DEPLOY",
     securityHeaders: securityHeadersOpt,
     csp: cspOpt,
     cspMode = "report-only",
@@ -1826,7 +1854,8 @@ export function createDecoWorkerEntry(
   // handlePurge (Bearer `purgeTokenEnv`). Per-isolate by nature — the isolate
   // that serves this request clears its cache; other live isolates keep theirs
   // until they're recycled or hit too. For a guaranteed global flush, redeploy
-  // (loader cache keys are build-hash versioned).
+  // (loader cache keys are build-hash versioned; preserved `fetch:*` entries are
+  // not — see `dataCacheOnDeployEnv`).
   async function handlePurgeLoaders(
     request: Request,
     env: Record<string, unknown>,
@@ -2305,24 +2334,36 @@ export function createDecoWorkerEntry(
       } catch {
         /* Missing storage is a cache miss, never a storefront failure. */
       }
+      const preserveData = !!dataCacheOnDeployEnv && env[dataCacheOnDeployEnv] === "preserve";
+      // Purge without a deploy: bump `cache:data-version` in DECO_KV.
+      const kvDataVersion = preserveData && storage ? await getDataCacheVersion(env, ctx) : "";
+      // Everything but the version is shared by the build and data scopes.
+      // Revision is left out of `variant`: build-scoped stores add it below, while
+      // preserved fetch data skips it — a raw upstream response does not depend on
+      // the decofile (a publish that changes props changes the URL, hence the key).
+      const variant = [
+        segment
+          ? hashSegment(segment)
+          : isMobileUA(request.headers.get("user-agent") ?? "")
+            ? "mobile"
+            : "desktop",
+        buildGeoCacheParam(
+          (request as unknown as { cf?: Record<string, string> }).cf,
+          effectiveGeoKey(),
+        ),
+        privateRequest ? crypto.randomUUID() : null,
+      ];
+      const scopeFor = (version: string, revision: string | null = getRevision()) =>
+        JSON.stringify([url.origin, version, revision, ...variant]);
       bindCacheStorage({
         storage,
         disabled: privateRequest || isDevMode(),
-        scope: JSON.stringify([
-          new URL(request.url).origin,
-          getBuildHash(env),
-          getRevision(),
-          segment
-            ? hashSegment(segment)
-            : isMobileUA(request.headers.get("user-agent") ?? "")
-              ? "mobile"
-              : "desktop",
-          buildGeoCacheParam(
-            (request as unknown as { cf?: Record<string, string> }).cf,
-            effectiveGeoKey(),
-          ),
-          privateRequest ? crypto.randomUUID() : null,
-        ]),
+        scope: scopeFor(getBuildHash(env)),
+        // Only `createFetchCache` (`fetch:*`) uses dataScope. Preserve keys it without
+        // build or CMS revision; invalidate keeps today's per-build key.
+        dataScope: preserveData
+          ? scopeFor(`data:${(env.DECO_DATA_CACHE_PURGE as string) ?? ""}:${kvDataVersion}`, null)
+          : undefined,
         waitUntil: (work) => ctx.waitUntil(work),
       });
     }