@decocms/tanstack 7.6.0 → 7.7.0

package/package.json

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

package/src/cms/kvBlockSource.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { computeRevision, KV_KEYS, type KVNamespace } from "@decocms/blocks/cms";
+import { computeRevision, type KVNamespace, revisionKey, snapshotKey } from "@decocms/blocks/cms";
 import { KVBlockSource } from "./kvBlockSource";
 
+const ID = "sha-abc123";
+const SNAP = snapshotKey(ID);
+const REV = revisionKey(ID);
+
 function makeKV(initial: Record<string, string> = {}): KVNamespace {
   const store = new Map<string, string>(Object.entries(initial));
   return {
@@ -19,7 +23,17 @@ function makeKV(initial: Record<string, string> = {}): KVNamespace {
 
 describe("KVBlockSource.loadSnapshot", () => {
   it("returns null when the snapshot key is missing", async () => {
-    const src = new KVBlockSource(makeKV());
+    const src = new KVBlockSource(makeKV(), ID);
+    await expect(src.loadSnapshot()).resolves.toBeNull();
+  });
+
+  it("reads the key for its own deployment id, not another", async () => {
+    const blocks = { Site: { name: "x" } };
+    // Store under a DIFFERENT deployment id — this source must not see it.
+    const src = new KVBlockSource(
+      makeKV({ [snapshotKey("other-sha")]: JSON.stringify(blocks) }),
+      ID,
+    );
     await expect(src.loadSnapshot()).resolves.toBeNull();
   });
 
@@ -27,16 +41,17 @@ describe("KVBlockSource.loadSnapshot", () => {
     const blocks = { Site: { name: "x" } };
     const src = new KVBlockSource(
       makeKV({
-        [KV_KEYS.SNAPSHOT]: JSON.stringify(blocks),
-        [KV_KEYS.REVISION]: "stored-rev",
+        [SNAP]: JSON.stringify(blocks),
+        [REV]: "stored-rev",
       }),
+      ID,
     );
     await expect(src.loadSnapshot()).resolves.toEqual({ blocks, revision: "stored-rev" });
   });
 
   it("recomputes the revision when only the snapshot is stored", async () => {
     const blocks = { Site: { name: "x" } };
-    const src = new KVBlockSource(makeKV({ [KV_KEYS.SNAPSHOT]: JSON.stringify(blocks) }));
+    const src = new KVBlockSource(makeKV({ [SNAP]: JSON.stringify(blocks) }), ID);
     await expect(src.loadSnapshot()).resolves.toEqual({
       blocks,
       revision: computeRevision(blocks),
@@ -44,24 +59,24 @@ describe("KVBlockSource.loadSnapshot", () => {
   });
 
   it("throws on a non-object snapshot (treated as KV-unavailable by callers)", async () => {
-    const src = new KVBlockSource(makeKV({ [KV_KEYS.SNAPSHOT]: "[1,2,3]" }));
+    const src = new KVBlockSource(makeKV({ [SNAP]: "[1,2,3]" }), ID);
     await expect(src.loadSnapshot()).rejects.toThrow();
   });
 
   it("throws on malformed JSON", async () => {
-    const src = new KVBlockSource(makeKV({ [KV_KEYS.SNAPSHOT]: "{not json" }));
+    const src = new KVBlockSource(makeKV({ [SNAP]: "{not json" }), ID);
     await expect(src.loadSnapshot()).rejects.toThrow();
   });
 });
 
 describe("KVBlockSource.getRevision", () => {
   it("returns the stored revision", async () => {
-    const src = new KVBlockSource(makeKV({ [KV_KEYS.REVISION]: "r1" }));
+    const src = new KVBlockSource(makeKV({ [REV]: "r1" }), ID);
     await expect(src.getRevision()).resolves.toBe("r1");
   });
 
   it("returns null when absent", async () => {
-    const src = new KVBlockSource(makeKV());
+    const src = new KVBlockSource(makeKV(), ID);
     await expect(src.getRevision()).resolves.toBeNull();
   });
 });

package/src/cms/kvBlockSource.ts

@@ -1,10 +1,13 @@
 /**
- * KVBlockSource — a `BlockSource` backed by a Cloudflare KV namespace.
+ * KVBlockSource — a `BlockSource` backed by a Cloudflare KV namespace, scoped
+ * to a single **deployment id**.
  *
- * Reads the whole decofile snapshot (`decofile:current`) and its revision
- * (`index:revision`) from KV. Used by the runtime hydration path
+ * Reads the whole decofile snapshot (`decofile:<id>`) and its revision
+ * (`index:revision:<id>`) from KV. Used by the runtime hydration path
  * (`src/sdk/kvHydration.ts`) on cold start and during revision polling, and by
  * the write-through path (`src/admin/decofile.ts`) which writes the same keys.
+ * Keying by deployment id means each running version only ever sees its own
+ * content — a rolling deploy can't feed new content to still-live old code.
  *
  * This class is intentionally thin — error handling (KV outages, JSON parse
  * failures) is the caller's responsibility so the framework can fall back to
@@ -15,15 +18,26 @@ import {
   type BlockSnapshot,
   type BlockSource,
   computeRevision,
-  KV_KEYS,
   type KVNamespace,
+  revisionKey,
+  snapshotKey,
 } from "@decocms/blocks/cms";
 
 export class KVBlockSource implements BlockSource {
-  constructor(private readonly kv: KVNamespace) {}
+  private readonly snapshotKey: string;
+  private readonly revisionKey: string;
+
+  constructor(
+    private readonly kv: KVNamespace,
+    /** Deployment id (git commit sha) this source is scoped to. */
+    deploymentId: string,
+  ) {
+    this.snapshotKey = snapshotKey(deploymentId);
+    this.revisionKey = revisionKey(deploymentId);
+  }
 
   /**
-   * Read and parse the full decofile snapshot from KV.
+   * Read and parse this deployment's full decofile snapshot from KV.
    *
    * Returns `null` when no snapshot is present (key missing) so the caller
    * keeps whatever blocks are already in memory (the bundled fallback).
@@ -34,21 +48,21 @@ export class KVBlockSource implements BlockSource {
    * unavailable" and falls back.
    */
   async loadSnapshot(): Promise<BlockSnapshot | null> {
-    const raw = await this.kv.get(KV_KEYS.SNAPSHOT);
+    const raw = await this.kv.get(this.snapshotKey);
     if (raw === null) return null;
 
     const parsed = JSON.parse(raw) as unknown;
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw new Error(`[CMS/KV] ${KV_KEYS.SNAPSHOT} is not a JSON object`);
+      throw new Error(`[CMS/KV] ${this.snapshotKey} is not a JSON object`);
     }
     const blocks = parsed as Record<string, unknown>;
 
-    const storedRevision = await this.kv.get(KV_KEYS.REVISION);
+    const storedRevision = await this.kv.get(this.revisionKey);
     return { blocks, revision: storedRevision ?? computeRevision(blocks) };
   }
 
   /** Cheap revision probe for change detection (no full snapshot transfer). */
   getRevision(): Promise<string | null> {
-    return this.kv.get(KV_KEYS.REVISION);
+    return this.kv.get(this.revisionKey);
   }
 }

package/src/sdk/kvHydration.test.ts

@@ -1,14 +1,28 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { computeRevision, getRevision, KV_KEYS, type KVNamespace, loadBlocks, setBlocks } from "@decocms/blocks/cms";
+import {
+  computeRevision,
+  getRevision,
+  type KVNamespace,
+  loadBlocks,
+  revisionKey,
+  setBlocks,
+  snapshotKey,
+} from "@decocms/blocks/cms";
 import {
   __resetKvHydrationStateForTests,
   ensureBlocksHydrated,
+  getDeploymentId,
   isFastDeployEnabled,
   maybePollRevision,
 } from "./kvHydration";
 
 const BUNDLED = { Site: { name: "bundled" } };
 
+/** Deployment id used across the hydration tests. */
+const ID = "sha-deadbeef";
+const SNAP = snapshotKey(ID);
+const REV = revisionKey(ID);
+
 /** KV stub that counts get() calls so we can assert throttling / single-load. */
 function makeKV(initial: Record<string, string> = {}) {
   const store = new Map<string, string>(Object.entries(initial));
@@ -32,11 +46,16 @@ function makeKV(initial: Record<string, string> = {}) {
 
 function snapshotEnv(blocks: Record<string, unknown>, extra: Record<string, unknown> = {}) {
   const { kv, ...rest } = makeKV({
-    [KV_KEYS.SNAPSHOT]: JSON.stringify(blocks),
-    [KV_KEYS.REVISION]: computeRevision(blocks),
+    [SNAP]: JSON.stringify(blocks),
+    [REV]: computeRevision(blocks),
   });
-  // DECO_FAST_DEPLOY="1" is the explicit opt-in required alongside the binding.
-  return { env: { DECO_KV: kv, DECO_FAST_DEPLOY: "1", ...extra }, kv, ...rest };
+  // DECO_FAST_DEPLOY="1" is the explicit opt-in required alongside the binding;
+  // DECO_DEPLOYMENT_ID scopes the read to this deployment's keyed snapshot.
+  return {
+    env: { DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID, ...extra },
+    kv,
+    ...rest,
+  };
 }
 
 /** Collects ctx.waitUntil promises so tests can await background polls. */
@@ -110,10 +129,19 @@ describe("ensureBlocksHydrated", () => {
     expect(getCalls()).toBe(2);
   });
 
-  it("keeps the bundled snapshot when the snapshot key is absent", async () => {
-    const { kv } = makeKV({ [KV_KEYS.REVISION]: "r" }); // no SNAPSHOT
-    await ensureBlocksHydrated({ DECO_KV: kv });
+  it("keeps the bundled snapshot when this deployment's snapshot key is absent", async () => {
+    const { kv } = makeKV({ [REV]: "r" }); // revision present, but no SNAPSHOT
+    await ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID });
+    expect(loadBlocks()).toEqual(BUNDLED);
+  });
+
+  it("keeps bundled (never touches KV) when no deployment id resolves", async () => {
+    const kvBlocks = { Site: { name: "from-kv" } };
+    const { kv, getCalls } = makeKV({ [SNAP]: JSON.stringify(kvBlocks) });
+    // Fast-deploy enabled + bound, but no DECO_DEPLOYMENT_ID / BUILD_HASH.
+    await ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1" });
     expect(loadBlocks()).toEqual(BUNDLED);
+    expect(getCalls()).toBe(0);
   });
 
   it("falls back to bundled (and does not throw) when KV errors", async () => {
@@ -123,11 +151,27 @@ describe("ensureBlocksHydrated", () => {
       delete: () => Promise.resolve(),
     };
     vi.spyOn(console, "warn").mockImplementation(() => {});
-    await expect(ensureBlocksHydrated({ DECO_KV: kv })).resolves.toBeUndefined();
+    await expect(
+      ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
+    ).resolves.toBeUndefined();
     expect(loadBlocks()).toEqual(BUNDLED);
   });
 });
 
+describe("getDeploymentId", () => {
+  it("prefers DECO_DEPLOYMENT_ID", () => {
+    expect(getDeploymentId({ DECO_DEPLOYMENT_ID: "a", BUILD_HASH: "b" })).toBe("a");
+  });
+
+  it("falls back to BUILD_HASH", () => {
+    expect(getDeploymentId({ BUILD_HASH: "b" })).toBe("b");
+  });
+
+  it("is null when nothing resolves", () => {
+    expect(getDeploymentId({})).toBeNull();
+  });
+});
+
 describe("maybePollRevision", () => {
   it("is a no-op before cold-start hydration has run", async () => {
     const { env, getCalls } = snapshotEnv({ Site: { name: "x" } });
@@ -145,8 +189,8 @@ describe("maybePollRevision", () => {
 
     // Simulate a publish from another isolate: KV now holds v2.
     const updated = { Site: { name: "v2" }, "pages-x": { path: "/x" } };
-    store.set(KV_KEYS.SNAPSHOT, JSON.stringify(updated));
-    store.set(KV_KEYS.REVISION, computeRevision(updated));
+    store.set(SNAP, JSON.stringify(updated));
+    store.set(REV, computeRevision(updated));
 
     const { ctx, settle } = makeCtx();
     maybePollRevision(env, ctx);

package/src/sdk/kvHydration.ts

@@ -24,12 +24,12 @@
  * `DecofileProvider` pattern from the deco-cx/deco Fresh runtime.
  */
 
-import { getRevision, setBlocks } from "@decocms/blocks/cms";
+import { getDeploymentId, getRevision, setBlocks } from "@decocms/blocks/cms";
 import { KVBlockSource } from "../cms/kvBlockSource";
 import type { KVNamespace } from "@decocms/blocks/cms";
 import { setSpanAttribute } from "@decocms/blocks/sdk/observability";
 
-/** How often (ms) an isolate re-probes `index:revision`. */
+/** How often (ms) an isolate re-probes its `index:revision:<id>`. */
 export const POLL_INTERVAL_MS = 10_000;
 
 /** KV binding name expected on the Worker `env`. */
@@ -39,6 +39,11 @@ export const KV_BINDING = "DECO_KV";
  * binding must also be present. */
 export const FAST_DEPLOY_ENV = "DECO_FAST_DEPLOY";
 
+// Deployment-id resolution lives in `@decocms/blocks/cms` (next to the key
+// builders it feeds) so the runtime read path and the admin write-through
+// resolve it identically. Re-exported for the existing call sites/tests.
+export { getDeploymentId };
+
 // globalThis-backed state so all Vite server-function split-module copies share
 // the same hydration flags (same pattern as `loader.ts`).
 const G = globalThis as unknown as {
@@ -105,9 +110,18 @@ export function ensureBlocksHydrated(env: Env, _ctx?: ExecutionContextLike): Pro
   const kv = getKV(env);
   if (!kv) return Promise.resolve();
 
+  // No resolvable deployment id ⇒ keep the bundled snapshot (this build's own
+  // content). Never read another deployment's key.
+  const deploymentId = getDeploymentId(env);
+  if (!deploymentId) {
+    setSpanAttribute("deco.block.source", "bundled");
+    G.__deco!.kvHydrated = true;
+    return Promise.resolve();
+  }
+
   const load = (async () => {
     try {
-      const snapshot = await new KVBlockSource(kv).loadSnapshot();
+      const snapshot = await new KVBlockSource(kv, deploymentId).loadSnapshot();
       if (snapshot) {
         setBlocks(snapshot.blocks);
         setSpanAttribute("deco.block.source", "kv");
@@ -144,16 +158,19 @@ export function maybePollRevision(env: Env, ctx?: ExecutionContextLike): void {
   const kv = getKV(env);
   if (!kv) return;
 
-  const poll = pollRevisionOnce(kv);
+  const deploymentId = getDeploymentId(env);
+  if (!deploymentId) return; // bundled-only; nothing to poll
+
+  const poll = pollRevisionOnce(kv, deploymentId);
   // Prefer waitUntil so the work outlives the response; fall back to a
   // fire-and-forget promise (dev / tests) with its rejection swallowed.
   if (ctx?.waitUntil) ctx.waitUntil(poll);
   else void poll.catch(() => {});
 }
 
-async function pollRevisionOnce(kv: KVNamespace): Promise<void> {
+async function pollRevisionOnce(kv: KVNamespace, deploymentId: string): Promise<void> {
   try {
-    const source = new KVBlockSource(kv);
+    const source = new KVBlockSource(kv, deploymentId);
     const remoteRevision = await source.getRevision();
     if (!remoteRevision || remoteRevision === getRevision()) return;
 

package/src/sdk/workerEntry.ts

@@ -122,7 +122,7 @@ function appendResourceHints(resp: Response): void {
 
 /**
  * Minimal ExecutionContext interface compatible with Cloudflare Workers.
- * Defined here so deco-start doesn't need @cloudflare/workers-types.
+ * Defined here so blocks doesn't need @cloudflare/workers-types.
  */
 interface WorkerExecutionContext {
   waitUntil(promise: Promise<unknown>): void;