@decocms/tanstack 7.67.1 → 7.69.0

package/package.json

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

package/src/sdk/kvHydration.test.ts

@@ -250,6 +250,15 @@ describe("ensureBlocksHydrated when the bundle ships no decofile", () => {
     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.

package/src/sdk/kvHydration.ts

@@ -138,7 +138,16 @@ function bundleHasNoDecofile(): boolean {
  *   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;
 

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;
+  }
+}

package/src/sdk/workerEntry.ts

@@ -76,7 +76,13 @@ import {
 } from "@decocms/blocks/sdk/otel";
 import { setRuntimeEnv } from "@decocms/blocks/sdk/otelAdapters";
 import { parseTraceparent } from "@decocms/blocks/sdk/otelHttpTracer";
-import { loadRedirects, matchRedirect, type RedirectMap } from "@decocms/blocks/sdk/redirects";
+import {
+  loadRedirects,
+  matchExactRedirect,
+  matchPatternRedirect,
+  normalizePath,
+  type RedirectMap,
+} from "@decocms/blocks/sdk/redirects";
 import { RequestContext } from "@decocms/blocks/sdk/requestContext";
 import { createResponseCache } from "@decocms/blocks/sdk/responseCache";
 import { cleanPathForCacheKey } from "@decocms/blocks/sdk/urlUtils";
@@ -96,6 +102,7 @@ import {
   requestCarriesDraft,
 } from "./draft";
 import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
+import { lookupExactRedirect } from "./kvRedirects";
 import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
 import { type SpeculationRulesConfig, setSpeculationRules } from "./speculationRules";
 
@@ -2192,7 +2199,15 @@ export function createDecoWorkerEntry(
       _redirectMap = loadRedirects(loadBlocks());
       _redirectMapRevision = currentRevision;
     }
-    const cmsRedirect = matchRedirect(url.pathname, _redirectMap!);
+    // Exact before glob, across BOTH sources. On a fast-deploy site the exact
+    // rules live under their own `redirect:<id>:<path>` KV keys and are absent
+    // from the decofile, so the in-memory exact hit is the non-fast-deploy
+    // case. Going straight to `matchRedirect` and only then to KV would let a
+    // glob win over an exact rule, inverting the precedence.
+    const cmsRedirect =
+      matchExactRedirect(url.pathname, _redirectMap!) ??
+      (await lookupExactRedirect(env as Record<string, unknown>, normalizePath(url.pathname))) ??
+      matchPatternRedirect(url.pathname, _redirectMap!);
     if (cmsRedirect) {
       return new Response(null, {
         status: cmsRedirect.status,

package/src/vite/plugin.js

@@ -173,27 +173,52 @@ export function generateSchemaArgs(siteName) {
   return ["--site", siteName];
 }
 
+/**
+ * Env var a deploy pipeline sets to declare "I seed `decofile:<deployment-id>`
+ * into KV BEFORE activating this version". Set by the cfworkers-builder under
+ * exactly the condition that guards its seed step, so the stub below and the
+ * seed can never drift apart.
+ */
+const SEEDED_DEPLOY_ENV = "DECO_SEEDED_DEPLOY";
+
+/** Whether this build runs inside a pipeline that seeds KV before activation. */
+function isSeededDeployPipeline() {
+  const v = process.env[SEEDED_DEPLOY_ENV];
+  return v === "1" || v === "true";
+}
+
 /**
  * @param {object} [opts]
- * @param {boolean} [opts.fastDeploy=false] Stub `blocks.gen` out of the SERVER
- *   bundle too, so the worker's only copy of the decofile is the one hydrated
- *   from KV at cold start.
+ * @param {boolean | "auto"} [opts.fastDeploy="auto"] Stub `blocks.gen` out of
+ *   the SERVER bundle too, so the worker's only copy of the decofile is the one
+ *   hydrated from KV at cold start.
  *
  *   Without this, a fast-deploy site holds the decofile TWICE: the bundled
  *   `JSON.parse(...)` graph stays permanently reachable through the site's
  *   `import { blocks } from ".deco/blocks.gen"` module binding, and
  *   `ensureBlocksHydrated` adds a second graph via `setBlocks()`. For a 10MB
- *   decofile that is tens of MB of avoidable isolate memory.
+ *   decofile that is tens of MB of avoidable isolate memory, on a platform
+ *   whose per-isolate cap is 128MB and has no GC knob.
+ *
+ *   It is gated because it removes the fallback: with no bundled snapshot, a
+ *   cold start that cannot read KV has no content to serve, and
+ *   `ensureBlocksHydrated` fails the request loudly (5xx) rather than serving
+ *   an empty site that the edge would then cache — see `kvHydration.ts`. That
+ *   is only safe when the deploy pipeline seeds `decofile:<deployment-id>`
+ *   BEFORE the new version activates.
  *
- *   Opt-in because it removes the fallback: with no bundled snapshot, a cold
- *   start that cannot read KV has no content to serve. `ensureBlocksHydrated`
- *   detects that case and fails the request loudly (5xx) instead of serving an
- *   empty site — see `kvHydration.ts`. Only enable alongside
- *   `DECO_FAST_DEPLOY=1` + a `DECO_KV` binding + a deploy pipeline that seeds
- *   `decofile:<deployment-id>` BEFORE the new version activates.
+ *   `"auto"` (default) stubs only when the pipeline declares it seeds, via
+ *   `DECO_SEEDED_DEPLOY`. A site building through Cloudflare Workers Builds or
+ *   a manual `wrangler deploy` never sets it, so it keeps the bundled snapshot
+ *   and behaves exactly as before — no site-side config, no way to half-enable
+ *   it. `true` forces the stub, `false` disables it. A stubbed bundle also
+ *   needs `DECO_FAST_DEPLOY=1` and a `DECO_KV` binding at runtime — without
+ *   them `ensureBlocksHydrated` fails every request rather than serve `{}`.
  * @returns {import("vite").PluginOption}
  */
-export function decoVitePlugin({ fastDeploy = false } = {}) {
+export function decoVitePlugin({ fastDeploy = "auto" } = {}) {
+  // Resolved once: the pipeline's answer cannot change mid-build.
+  const stubBlocks = fastDeploy === "auto" ? isSeededDeployPipeline() : fastDeploy === true;
   // Set from the `config` hook (which Vite always runs before `load`). The
   // fastDeploy stub must apply to production builds ONLY: `vite dev` has no KV
   // to hydrate from, and the dev bootstrap below deliberately relies on reading
@@ -239,7 +264,7 @@ export function decoVitePlugin({ fastDeploy = false } = {}) {
         // `import { blocks }` binding keeps the bundled graph alive for the
         // isolate's whole life, even after `setBlocks()` swaps in the KV one).
         // Build only — see `isBuild` above.
-        if (fastDeploy && isBuild) {
+        if (stubBlocks && isBuild) {
           return "export const blocks = {};";
         }
 
@@ -785,7 +810,7 @@ export function decoVitePlugin({ fastDeploy = false } = {}) {
         // is not equivalent — draft-preview overrides can make a stubbed bundle
         // look populated, and a legitimately-empty decofile (new site) would
         // look stubbed.
-        __DECO_BLOCKS_STUBBED__: JSON.stringify(fastDeploy && command === "build"),
+        __DECO_BLOCKS_STUBBED__: JSON.stringify(stubBlocks && command === "build"),
       };
 
       // Only split chunks for production builds — dev uses unbundled ESM.

package/src/vite/plugin.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { decoVitePlugin } from "./plugin.js";
 
 /**
@@ -68,6 +68,12 @@ describe("decoVitePlugin — fastDeploy server stub", () => {
   const id = "/repo/.deco/blocks.gen.ts";
   const STUB = "export const blocks = {};";
 
+  // The default is "auto", which reads DECO_SEEDED_DEPLOY. Pin it off so the
+  // "default does not stub" assertions below can't be silently satisfied (or
+  // broken) by an ambient env var.
+  vi.stubEnv("DECO_SEEDED_DEPLOY", "");
+  afterEach(() => vi.stubEnv("DECO_SEEDED_DEPLOY", ""));
+
   /** @param {{fastDeploy?: boolean}} opts @param {"build"|"serve"} command */
   const make = (opts, command) => {
     const p = /** @type {any} */ (decoVitePlugin(opts));
@@ -110,3 +116,61 @@ describe("decoVitePlugin — fastDeploy server stub", () => {
     expect(def.define.__DECO_BLOCKS_STUBBED__).toBe("false");
   });
 });
+
+/**
+ * The `"auto"` default: stub only when the deploy pipeline declares it seeds
+ * `decofile:<deployment-id>` into KV BEFORE activating the new version.
+ *
+ * Stubbing without that guarantee is a hard outage, not a degraded mode — the
+ * bundle has no decofile, so `ensureBlocksHydrated` 5xxs on purpose rather than
+ * serving an empty site the edge would cache. Cloudflare Workers Builds and a
+ * manual `wrangler deploy` do not seed, and they never set the env.
+ */
+describe("decoVitePlugin — fastDeploy auto gate", () => {
+  const id = "/repo/.deco/blocks.gen.ts";
+  const STUB = "export const blocks = {};";
+
+  afterEach(() => vi.unstubAllEnvs());
+
+  /** @param {"build"|"serve"} command */
+  const makeDefault = (command) => {
+    const p = /** @type {any} */ (decoVitePlugin());
+    const cfg = p.config({}, { command });
+    return { plugin: p, cfg };
+  };
+
+  it("does not stub when the pipeline does not declare a seed step", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "");
+    const { plugin, cfg } = makeDefault("build");
+    expect(plugin.load(id, { ssr: true })).not.toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("false");
+  });
+
+  it("stubs on a production build when the pipeline declares it seeds", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "1");
+    const { plugin, cfg } = makeDefault("build");
+    expect(plugin.load(id, { ssr: true })).toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("true");
+  });
+
+  it("still never stubs SSR in dev, even inside a seeding pipeline", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "1");
+    const { plugin, cfg } = makeDefault("serve");
+    expect(plugin.load(id, { ssr: true })).not.toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("false");
+  });
+
+  it("explicit false wins over a seeding pipeline", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "1");
+    const p = /** @type {any} */ (decoVitePlugin({ fastDeploy: false }));
+    const cfg = p.config({}, { command: "build" });
+    expect(p.load(id, { ssr: true })).not.toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("false");
+  });
+
+  it("explicit true wins over a non-seeding pipeline", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "");
+    const p = /** @type {any} */ (decoVitePlugin({ fastDeploy: true }));
+    expect(p.config({}, { command: "build" }).define.__DECO_BLOCKS_STUBBED__).toBe("true");
+  });
+});