@decocms/tanstack 8.0.0 → 8.1.0-next.0

package/src/sdk/kvHydration.test.ts

@@ -213,3 +213,159 @@ describe("maybePollRevision", () => {
     expect(getCalls()).toBe(callsAfterHydrate + 1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Bundles that ship no decofile (`decoVitePlugin({ fastDeploy: true })`)
+//
+// With the decofile stubbed out of the server bundle, KV is the ONLY source of
+// content. The "warn and serve bundled" recovery would serve an EMPTY site —
+// 200s with no pages, which get edge-cached and outlive the KV failure that
+// caused them. These assert it fails loudly instead.
+//
+// The signal is the build-time `__DECO_BLOCKS_STUBBED__` define, NOT an empty
+// in-memory map: draft overrides can make a stubbed bundle look populated, and
+// a legitimately-empty decofile would look stubbed. Both are covered below.
+// ---------------------------------------------------------------------------
+declare global {
+  // eslint-disable-next-line no-var
+  var __DECO_BLOCKS_STUBBED__: boolean | undefined;
+}
+
+/** Simulates a build made with `fastDeploy: true`. */
+function withStubbedBundle() {
+  globalThis.__DECO_BLOCKS_STUBBED__ = true;
+}
+
+describe("ensureBlocksHydrated when the bundle ships no decofile", () => {
+  beforeEach(() => {
+    globalThis.__DECO_BLOCKS_STUBBED__ = undefined;
+  });
+
+  it("throws when the snapshot is missing instead of serving an empty site", async () => {
+    withStubbedBundle();
+    setBlocks({});
+    const { kv } = makeKV(); // no decofile:<id> seeded
+    const env = { DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID };
+
+    await expect(ensureBlocksHydrated(env)).rejects.toThrow(/not found and this bundle ships no/);
+  });
+
+  it("throws when fast-deploy is off at runtime instead of serving {}", async () => {
+    withStubbedBundle();
+    setBlocks({});
+    const { kv } = makeKV();
+
+    await expect(ensureBlocksHydrated({})).rejects.toThrow(/fast-deploy is off/);
+    await expect(ensureBlocksHydrated({ DECO_KV: kv })).rejects.toThrow(/fast-deploy is off/);
+  });
+
+  it("throws when the snapshot exists but is empty", async () => {
+    // A seed that wrote `{}` would otherwise take the success branch, latch,
+    // and serve the empty edge-cached site this guard exists to prevent.
+    withStubbedBundle();
+    setBlocks({});
+    const { kv } = makeKV({ [SNAP]: "{}", [REV]: computeRevision({}) });
+
+    await expect(
+      ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
+    ).rejects.toThrow(/is empty and this bundle ships no/);
+  });
+
+  it("throws when KV itself fails", async () => {
+    withStubbedBundle();
+    setBlocks({});
+    const kv = {
+      get: () => Promise.reject(new Error("KV unreachable")),
+      put: () => Promise.resolve(),
+      delete: () => Promise.resolve(),
+    } as unknown as KVNamespace;
+
+    await expect(
+      ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
+    ).rejects.toThrow(/KV unreachable/);
+  });
+
+  it("throws when no deployment id resolves", async () => {
+    withStubbedBundle();
+    setBlocks({});
+    const { kv } = makeKV();
+
+    await expect(ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1" })).rejects.toThrow(
+      /no deployment id/,
+    );
+  });
+
+  it("is not rescued by a populated in-memory map (draft-preview overrides)", async () => {
+    // `bindRequestDraft` composes overrides into loadBlocks() BEFORE hydration.
+    // Inferring "has a fallback" from the map would latch here and then serve
+    // the empty base decofile for the isolate's life.
+    withStubbedBundle();
+    setBlocks({ "pages-Draft": { name: "override" } });
+    const { kv } = makeKV();
+
+    await expect(
+      ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
+    ).rejects.toThrow(/not found and this bundle ships no/);
+  });
+
+  it("does not latch hydration on the fatal path, so the next request retries", async () => {
+    withStubbedBundle();
+    setBlocks({});
+    const blocks = { Site: { name: "from-kv" } };
+    const store = new Map<string, string>();
+    const kv: KVNamespace = {
+      get: (k) => Promise.resolve(store.get(k) ?? null),
+      put: (k, v) => {
+        store.set(k, v);
+        return Promise.resolve();
+      },
+      delete: (k) => {
+        store.delete(k);
+        return Promise.resolve();
+      },
+    };
+    const env = { DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID };
+
+    // First request: snapshot absent → fatal.
+    await expect(ensureBlocksHydrated(env)).rejects.toThrow();
+
+    // Operator seeds it; the isolate must pick it up rather than stay empty.
+    store.set(SNAP, JSON.stringify(blocks));
+    store.set(REV, computeRevision(blocks));
+
+    await expect(ensureBlocksHydrated(env)).resolves.toBeUndefined();
+    expect(loadBlocks()).toEqual(blocks);
+  });
+});
+
+describe("ensureBlocksHydrated when the bundle DOES ship a decofile (default)", () => {
+  beforeEach(() => {
+    globalThis.__DECO_BLOCKS_STUBBED__ = undefined;
+  });
+
+  it("warns and serves bundled when KV fails", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const kv = {
+      get: () => Promise.reject(new Error("KV unreachable")),
+      put: () => Promise.resolve(),
+      delete: () => Promise.resolve(),
+    } as unknown as KVNamespace;
+
+    await expect(
+      ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
+    ).resolves.toBeUndefined();
+    expect(loadBlocks()).toEqual(BUNDLED);
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it("does not 5xx a site whose bundled decofile is legitimately empty", async () => {
+    // New site / missing blocks.gen.json. Before the build-time flag this
+    // looked identical to a stubbed bundle and started failing requests.
+    setBlocks({});
+    const { kv } = makeKV(); // no snapshot seeded either
+
+    await expect(
+      ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
+    ).resolves.toBeUndefined();
+  });
+});

package/src/sdk/kvHydration.ts

@@ -24,7 +24,7 @@
  * `DecofileProvider` pattern from the deco-cx/deco Fresh runtime.
  */
 
-import { getDeploymentId, getRevision, setBlocks } from "@decocms/blocks/cms";
+import { DEPLOYMENT_ID_ENV, 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";
@@ -95,15 +95,59 @@ export function getFastDeployKV(env: Env): KVNamespace | null {
   return getKV(env);
 }
 
+// Build-time constant injected by `decoVitePlugin({ fastDeploy: true })`: true
+// when `blocks.gen` was stubbed out of THIS server bundle. Declared with a
+// `typeof` guard so it's inert wherever the define isn't applied (this
+// package's own tsc output, the Next.js build, tests).
+declare const __DECO_BLOCKS_STUBBED__: boolean | undefined;
+
+/**
+ * Does this bundle ship no decofile of its own?
+ *
+ * When true, KV is the ONLY source of content, so the "warn and serve bundled"
+ * recovery below would serve an EMPTY site — 200s with no pages, which then get
+ * edge-cached and outlive the KV failure that caused them. Those cases fail
+ * loudly instead.
+ *
+ * This is deliberately a BUILD-time answer rather than "is the in-memory map
+ * empty". The runtime check is not equivalent in three ways:
+ *   - `loadBlocks()` composes request-scoped draft/preview overrides, and
+ *     `bindRequestDraft` runs before hydration — a draft-preview first request
+ *     would make a stubbed bundle look populated, latch, and then serve the
+ *     empty base decofile for the isolate's life.
+ *   - A legitimately-empty decofile (new site, missing `blocks.gen.json`) would
+ *     look stubbed, turning a previously-warning default site into 5xx.
+ *   - An empty snapshot in KV can't be distinguished from a healthy one.
+ */
+function bundleHasNoDecofile(): boolean {
+  return typeof __DECO_BLOCKS_STUBBED__ !== "undefined" && __DECO_BLOCKS_STUBBED__ === true;
+}
+
 /**
  * Cold-start hydration. Awaits the KV snapshot once per isolate and swaps it
  * into the in-memory block map. Concurrent first requests share a single
- * in-flight load. On any error (KV outage, bad JSON) we keep the bundled
- * snapshot and mark hydration done — recovery happens via `maybePollRevision`
- * once KV is reachable again (its revision will differ from the bundled one).
+ * in-flight load.
+ *
+ * On failure (KV outage, bad JSON, snapshot not seeded) the behavior depends on
+ * whether a bundled snapshot exists:
+ *
+ * - Bundled present (default): warn, serve bundled, mark hydration done —
+ *   `maybePollRevision` recovers once KV is reachable again.
+ * - Bundled stubbed out (`fastDeploy`): throw. There is no content to serve, so
+ *   a 5xx is the only honest answer; hydration is left unlatched so the next
+ *   request retries instead of pinning the isolate to an empty decofile.
  */
 export function ensureBlocksHydrated(env: Env, _ctx?: ExecutionContextLike): Promise<void> {
-  if (!isFastDeployEnabled(env)) return Promise.resolve();
+  if (!isFastDeployEnabled(env)) {
+    // A stubbed bundle with fast-deploy off would serve an empty 200 the edge caches.
+    return bundleHasNoDecofile()
+      ? Promise.reject(
+          new Error(
+            `[CMS/KV] this bundle ships no decofile but fast-deploy is off (set ${FAST_DEPLOY_ENV}=1 and bind DECO_KV)`,
+          ),
+        )
+      : Promise.resolve();
+  }
   if (G.__deco!.kvHydrated) return Promise.resolve();
   if (G.__deco!.kvHydration) return G.__deco!.kvHydration;
 
@@ -114,28 +158,54 @@ export function ensureBlocksHydrated(env: Env, _ctx?: ExecutionContextLike): Pro
   // content). Never read another deployment's key.
   const deploymentId = getDeploymentId(env);
   if (!deploymentId) {
+    if (bundleHasNoDecofile()) {
+      return Promise.reject(
+        new Error(
+          `[CMS/KV] no deployment id (set ${DEPLOYMENT_ID_ENV}) and this bundle ships no decofile`,
+        ),
+      );
+    }
     setSpanAttribute("deco.block.source", "bundled");
     G.__deco!.kvHydrated = true;
     return Promise.resolve();
   }
 
   const load = (async () => {
+    // Held rather than rethrown inline so the `finally` below can decide
+    // whether to latch — latching on a fatal path would serve an empty
+    // decofile for the isolate's entire life.
+    let fatal: Error | null = null;
     try {
       const snapshot = await new KVBlockSource(kv, deploymentId).loadSnapshot();
-      if (snapshot) {
-        setBlocks(snapshot.blocks);
+      // An empty snapshot is treated as a failure, not a success: with no
+      // bundled decofile it would otherwise latch and serve exactly the empty,
+      // edge-cached site this guard exists to prevent. A site legitimately has
+      // blocks; `{}` means the seed wrote nothing.
+      const empty = !snapshot || Object.keys(snapshot.blocks).length === 0;
+      if (!empty) {
+        setBlocks(snapshot!.blocks);
         setSpanAttribute("deco.block.source", "kv");
-      } else {
+      } else if (!bundleHasNoDecofile()) {
         setSpanAttribute("deco.block.source", "bundled");
+      } else {
+        fatal = new Error(
+          `[CMS/KV] decofile:${deploymentId} ${snapshot ? "is empty" : "not found"} and this ` +
+            `bundle ships no decofile — seed it before activating this version`,
+        );
       }
     } catch (e) {
-      // Non-fatal: serve the bundled snapshot. The poll loop recovers later.
-      console.warn("[CMS/KV] cold-start hydration failed, using bundled snapshot:", e);
-      setSpanAttribute("deco.block.source", "bundled");
+      if (!bundleHasNoDecofile()) {
+        // Non-fatal: serve the bundled snapshot. The poll loop recovers later.
+        console.warn("[CMS/KV] cold-start hydration failed, using bundled snapshot:", e);
+        setSpanAttribute("deco.block.source", "bundled");
+      } else {
+        fatal = e instanceof Error ? e : new Error(String(e));
+      }
     } finally {
-      G.__deco!.kvHydrated = true;
+      G.__deco!.kvHydrated = !fatal;
       G.__deco!.kvHydration = null;
     }
+    if (fatal) throw fatal;
   })();
 
   G.__deco!.kvHydration = load;

package/src/sdk/kvRedirects.test.ts

@@ -0,0 +1,132 @@
+import {
+  loadRedirects,
+  matchExactRedirect,
+  matchPatternRedirect,
+} from "@decocms/blocks/sdk/redirects";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { clearRedirectCache, lookupExactRedirect } from "./kvRedirects";
+
+/** Minimal KV binding that records every read. */
+function makeKV(values: Record<string, string> = {}) {
+  const get = vi.fn((key: string) => Promise.resolve(values[key] ?? null));
+  return { get, put: vi.fn(), delete: vi.fn() };
+}
+
+const ID = "sha-abc";
+const enabled = (kv: unknown) => ({
+  DECO_FAST_DEPLOY: "1",
+  DECO_KV: kv,
+  DECO_DEPLOYMENT_ID: ID,
+});
+
+beforeEach(() => {
+  clearRedirectCache();
+  vi.useRealTimers();
+});
+
+describe("lookupExactRedirect", () => {
+  it("reads redirect:<id>:<path> and returns the rule", async () => {
+    const kv = makeKV({ [`redirect:${ID}:/old`]: '{"to":"/new","status":301}' });
+    await expect(lookupExactRedirect(enabled(kv), "/old")).resolves.toEqual({
+      from: "/old",
+      to: "/new",
+      status: 301,
+    });
+  });
+
+  it("returns null for a missing key", async () => {
+    await expect(lookupExactRedirect(enabled(makeKV()), "/nope")).resolves.toBeNull();
+  });
+
+  it("caches a HIT so the same path costs one KV read", async () => {
+    const kv = makeKV({ [`redirect:${ID}:/old`]: '{"to":"/new","status":302}' });
+    await lookupExactRedirect(enabled(kv), "/old");
+    await lookupExactRedirect(enabled(kv), "/old");
+    expect(kv.get).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches a MISS too — that is the common case on every request", async () => {
+    const kv = makeKV();
+    await lookupExactRedirect(enabled(kv), "/nope");
+    await lookupExactRedirect(enabled(kv), "/nope");
+    expect(kv.get).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-reads after the TTL, which is how a redirect edit propagates", async () => {
+    // The rules live outside the decofile, so a redirect-only sync leaves the
+    // revision identical and the poller has nothing to react to. The TTL is
+    // the only propagation path.
+    const kv = makeKV();
+    await lookupExactRedirect(enabled(kv), "/soon");
+    vi.useFakeTimers();
+    vi.setSystemTime(Date.now() + 61_000);
+    await lookupExactRedirect(enabled(kv), "/soon");
+    expect(kv.get).toHaveBeenCalledTimes(2);
+  });
+
+  it("is inert when fast-deploy is off", async () => {
+    const kv = makeKV({ [`redirect:${ID}:/old`]: '{"to":"/new","status":301}' });
+    const env = { DECO_KV: kv, DECO_DEPLOYMENT_ID: ID }; // no DECO_FAST_DEPLOY
+    await expect(lookupExactRedirect(env, "/old")).resolves.toBeNull();
+    expect(kv.get).not.toHaveBeenCalled();
+  });
+
+  it("never reads another deployment's keys when the id is unresolvable", async () => {
+    const kv = makeKV();
+    await lookupExactRedirect({ DECO_FAST_DEPLOY: "1", DECO_KV: kv }, "/old");
+    expect(kv.get).not.toHaveBeenCalled();
+  });
+
+  it("treats a KV failure as no-redirect, never a throw", async () => {
+    // A KV outage must not 5xx a page that would otherwise render fine.
+    const kv = { get: vi.fn(() => Promise.reject(new Error("KV down"))) };
+    await expect(lookupExactRedirect(enabled(kv), "/old")).resolves.toBeNull();
+  });
+
+  it("treats a malformed value as no-redirect", async () => {
+    const kv = makeKV({ [`redirect:${ID}:/old`]: "not json" });
+    await expect(lookupExactRedirect(enabled(kv), "/old")).resolves.toBeNull();
+  });
+
+  it("defaults an unknown status to 302 rather than inventing a permanent redirect", async () => {
+    const kv = makeKV({ [`redirect:${ID}:/old`]: '{"to":"/new"}' });
+    await expect(lookupExactRedirect(enabled(kv), "/old")).resolves.toMatchObject({ status: 302 });
+  });
+});
+
+describe("precedence: exact (KV) over glob (memory)", () => {
+  it("an exact rule in KV wins over a glob still in the decofile", async () => {
+    // This is why matchRedirect was split in two. Doing "matchRedirect, then
+    // KV" would return /store/sale here, inverting the precedence every
+    // non-fast-deploy path has.
+    const map = loadRedirects({
+      r: {
+        __resolveType: "website/loaders/redirects.ts",
+        redirects: [{ from: "/shop/*", to: "/store/*" }],
+      },
+    });
+    const kv = makeKV({ [`redirect:${ID}:/shop/sale`]: '{"to":"/promo","status":301}' });
+
+    const hit =
+      matchExactRedirect("/shop/sale", map) ??
+      (await lookupExactRedirect(enabled(kv), "/shop/sale")) ??
+      matchPatternRedirect("/shop/sale", map);
+
+    expect(hit).toMatchObject({ to: "/promo", status: 301 });
+  });
+
+  it("falls through to the glob when KV has no exact rule", async () => {
+    const map = loadRedirects({
+      r: {
+        __resolveType: "website/loaders/redirects.ts",
+        redirects: [{ from: "/shop/*", to: "/store/*" }],
+      },
+    });
+    const hit =
+      matchExactRedirect("/shop/other", map) ??
+      (await lookupExactRedirect(enabled(makeKV()), "/shop/other")) ??
+      matchPatternRedirect("/shop/other", map);
+
+    expect(hit).toMatchObject({ to: "/store/other" });
+  });
+});

package/src/sdk/kvRedirects.ts

@@ -0,0 +1,125 @@
+/**
+ * Request-time lookup for KV-keyed exact redirects.
+ *
+ * A bulk-migration site can carry tens of thousands of rules. Inside the
+ * decofile they are resident in every isolate twice — the parsed snapshot graph
+ * and the `RedirectMap` built from it — for data consulted at most once per
+ * request and usually matching nothing. `splitExactRedirects` moves them to one
+ * `redirect:<deployment-id>:<path>` key each at sync time, so the list is never
+ * loaded and this looks up only the path actually being requested.
+ *
+ * Globs stay in the decofile and in memory: they must be scanned in order
+ * against the path, so they can never be a key lookup. There are tens of them.
+ *
+ * Inert unless fast-deploy is on — without a `DECO_KV` binding there is nowhere
+ * to look, and the rules are still in the decofile where `matchRedirect` finds
+ * them. Same on-or-off switch as the rest of fast-deploy, so a site can't end
+ * up with redirects in neither place.
+ */
+
+import { getDeploymentId, redirectKey, type StoredRedirect } from "@decocms/blocks/cms";
+import type { Redirect } from "@decocms/blocks/sdk/redirects";
+import { getFastDeployKV } from "./kvHydration";
+
+/**
+ * How long a lookup (hit OR miss) is trusted inside one isolate.
+ *
+ * Deliberately a TTL rather than the decofile revision: the rules now live in
+ * their own keys, so a redirect-only content sync leaves the decofile byte
+ * identical and the revision poller sees nothing to react to. The TTL is the
+ * propagation delay for a redirect edit.
+ *
+ * Ceiling: if that delay ever needs to be near-zero, the upgrade is a
+ * `index:redirects-revision:<id>` key polled next to `index:revision:<id>` —
+ * not a shorter TTL, which just multiplies KV reads.
+ */
+const TTL_MS = 60_000;
+
+/** Bounded so a crawler walking unique URLs cannot grow the isolate unbounded —
+ *  the whole point of this module is to stop holding an unbounded list. */
+const MAX_ENTRIES = 2_000;
+
+interface CacheEntry {
+  value: StoredRedirect | null;
+  expiresAt: number;
+}
+
+// globalThis-backed so every Vite server-function split-module copy shares one
+// cache (same reason as `loader.ts` and `kvHydration.ts`).
+const G = globalThis as unknown as { __decoRedirectCache?: Map<string, CacheEntry> };
+function cache(): Map<string, CacheEntry> {
+  G.__decoRedirectCache ??= new Map();
+  return G.__decoRedirectCache;
+}
+
+/** Insertion-ordered LRU touch + evict. */
+function remember(key: string, value: StoredRedirect | null): void {
+  const c = cache();
+  c.delete(key);
+  c.set(key, { value, expiresAt: Date.now() + TTL_MS });
+  while (c.size > MAX_ENTRIES) c.delete(c.keys().next().value!);
+}
+
+/** Cached entry, or `undefined` when absent/expired. */
+function peek(key: string): CacheEntry | undefined {
+  const c = cache();
+  const entry = c.get(key);
+  if (!entry) return undefined;
+  if (Date.now() >= entry.expiresAt) {
+    c.delete(key);
+    return undefined;
+  }
+  c.delete(key);
+  c.set(key, entry);
+  return entry;
+}
+
+/** Test seam — the cache is process-global, so suites must be able to reset it. */
+export function clearRedirectCache(): void {
+  G.__decoRedirectCache = new Map();
+}
+
+/**
+ * Look up one exact redirect for `normalizedPath` (already through
+ * `normalizePath` — the key contract).
+ *
+ * Returns `null` for "no redirect", including every case where the lookup
+ * cannot run (fast-deploy off, no deployment id, KV error). A KV failure must
+ * not 5xx a page that would otherwise render: the worst outcome is the request
+ * proceeds and the URL serves its normal response.
+ */
+export async function lookupExactRedirect(
+  env: Record<string, unknown>,
+  normalizedPath: string,
+): Promise<Redirect | null> {
+  const kv = getFastDeployKV(env);
+  if (!kv) return null;
+
+  const deploymentId = getDeploymentId(env);
+  if (!deploymentId) return null;
+
+  const key = redirectKey(deploymentId, normalizedPath);
+  const cached = peek(key);
+  const stored = cached !== undefined ? cached.value : await read(kv, key);
+  if (cached === undefined) remember(key, stored);
+  if (!stored) return null;
+
+  return { from: normalizedPath, to: stored.to, status: stored.status };
+}
+
+async function read(
+  kv: { get(key: string): Promise<string | null> },
+  key: string,
+): Promise<StoredRedirect | null> {
+  try {
+    const raw = await kv.get(key);
+    if (raw === null) return null;
+    const parsed = JSON.parse(raw) as StoredRedirect;
+    // A malformed value is a miss, not a throw — never let bad data in one key
+    // take down every request for that path.
+    if (!parsed || typeof parsed.to !== "string") return null;
+    return { to: parsed.to, status: parsed.status === 301 ? 301 : 302 };
+  } catch {
+    return null;
+  }
+}