@decocms/tanstack 7.78.2 → 7.79.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.78.2",
+  "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.2",
-    "@decocms/blocks-admin": "7.78.2",
-    "@decocms/blocks-cli": "7.78.2",
+    "@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/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),
       });
     }