@decocms/tanstack 7.77.11 → 7.77.13

package/package.json

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

package/src/sdk/kvRedirects.test.ts

@@ -2,8 +2,9 @@ import {
   loadRedirects,
   matchExactRedirect,
   matchPatternRedirect,
+  setRedirectSemantics,
 } from "@decocms/blocks/sdk/redirects";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { clearRedirectCache, lookupExactRedirect } from "./kvRedirects";
 
 /** Minimal KV binding that records every read. */
@@ -39,7 +40,7 @@ describe("lookupExactRedirect", () => {
   });
 
   it("caches a HIT so the same path costs one KV read", async () => {
-    const kv = makeKV({ [`redirect:${ID}:/old`]: '{"to":"/new","status":302}' });
+    const kv = makeKV({ [`redirect:${ID}:/old`]: '{"to":"/new","status":307}' });
     await lookupExactRedirect(enabled(kv), "/old");
     await lookupExactRedirect(enabled(kv), "/old");
     expect(kv.get).toHaveBeenCalledTimes(1);
@@ -88,10 +89,45 @@ describe("lookupExactRedirect", () => {
     await expect(lookupExactRedirect(enabled(kv), "/old")).resolves.toBeNull();
   });
 
-  it("defaults an unknown status to 302 rather than inventing a permanent redirect", async () => {
+  it("answers an unknown status as temporary 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 });
   });
+
+  it("looks the request path up under its folded key", async () => {
+    const kv = makeKV({ [`redirect:${ID}:/old`]: '{"from":"/Old/","to":"/new","status":307}' });
+    await expect(lookupExactRedirect(enabled(kv), "/OLD/")).resolves.toMatchObject({
+      to: "/new",
+      status: 302,
+    });
+  });
+});
+
+describe("lookupExactRedirect — semantics", () => {
+  afterEach(() => setRedirectSemantics("legacy"));
+  const value = JSON.stringify([
+    { from: "/meia/p", to: "/a", status: 307 },
+    { from: "/Meia/p/", to: "/b", status: 307 },
+  ]);
+
+  it("legacy serves the last rule under the key, temporary as 302", async () => {
+    const kv = makeKV({ [`redirect:${ID}:/meia/p`]: value });
+    await expect(lookupExactRedirect(enabled(kv), "/meia/p")).resolves.toMatchObject({
+      to: "/b",
+      status: 302,
+    });
+  });
+
+  it("fresh serves the rule written byte for byte, temporary as 307", async () => {
+    setRedirectSemantics("fresh");
+    const kv = makeKV({ [`redirect:${ID}:/meia/p`]: value });
+    await expect(lookupExactRedirect(enabled(kv), "/meia/p")).resolves.toMatchObject({
+      to: "/a",
+      status: 307,
+    });
+    clearRedirectCache();
+    await expect(lookupExactRedirect(enabled(kv), "/MEIA/p")).resolves.toBeNull();
+  });
 });
 
 describe("precedence: exact (KV) over glob (memory)", () => {

package/src/sdk/kvRedirects.ts

@@ -18,7 +18,7 @@
  */
 
 import { getDeploymentId, redirectKey, type StoredRedirect } from "@decocms/blocks/cms";
-import type { Redirect } from "@decocms/blocks/sdk/redirects";
+import { normalizePath, type Redirect, selectExactRedirect } from "@decocms/blocks/sdk/redirects";
 import { getFastDeployKV } from "./kvHydration";
 
 /**
@@ -39,8 +39,10 @@ const TTL_MS = 60_000;
  *  the whole point of this module is to stop holding an unbounded list. */
 const MAX_ENTRIES = 2_000;
 
+type StoredValue = StoredRedirect | StoredRedirect[];
+
 interface CacheEntry {
-  value: StoredRedirect | null;
+  value: StoredValue | null;
   expiresAt: number;
 }
 
@@ -53,7 +55,7 @@ function cache(): Map<string, CacheEntry> {
 }
 
 /** Insertion-ordered LRU touch + evict. */
-function remember(key: string, value: StoredRedirect | null): void {
+function remember(key: string, value: StoredValue | null): void {
   const c = cache();
   c.delete(key);
   c.set(key, { value, expiresAt: Date.now() + TTL_MS });
@@ -80,8 +82,10 @@ export function clearRedirectCache(): void {
 }
 
 /**
- * Look up one exact redirect for `normalizedPath` (already through
- * `normalizePath` — the key contract).
+ * Look up one exact redirect for the request's `pathname`. The key is
+ * `normalizePath(pathname)` (the key contract, the same in both semantics);
+ * which of the rules stored there answers — if any — is the semantics' call
+ * (`selectExactRedirect`).
  *
  * 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
@@ -90,7 +94,7 @@ export function clearRedirectCache(): void {
  */
 export async function lookupExactRedirect(
   env: Record<string, unknown>,
-  normalizedPath: string,
+  pathname: string,
 ): Promise<Redirect | null> {
   const kv = getFastDeployKV(env);
   if (!kv) return null;
@@ -98,28 +102,40 @@ export async function lookupExactRedirect(
   const deploymentId = getDeploymentId(env);
   if (!deploymentId) return null;
 
-  const key = redirectKey(deploymentId, normalizedPath);
+  const key = redirectKey(deploymentId, normalizePath(pathname));
   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 };
+  return selectExactRedirect(stored, pathname);
 }
 
 async function read(
   kv: { get(key: string): Promise<string | null> },
   key: string,
-): Promise<StoredRedirect | null> {
+): Promise<StoredValue | null> {
   try {
     const raw = await kv.get(key);
     if (raw === null) return null;
-    const parsed = JSON.parse(raw) as StoredRedirect;
+    const parsed = JSON.parse(raw) as unknown;
     // 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 };
+    const rules = (Array.isArray(parsed) ? parsed : [parsed])
+      .map(toStored)
+      .filter((r): r is StoredRedirect => r !== null);
+    if (rules.length === 0) return null;
+    return rules.length === 1 ? rules[0] : rules;
   } catch {
     return null;
   }
 }
+
+function toStored(value: unknown): StoredRedirect | null {
+  const parsed = value as Partial<StoredRedirect> | null;
+  if (!parsed || typeof parsed !== "object" || typeof parsed.to !== "string") return null;
+  const stored: StoredRedirect = { to: parsed.to, status: parsed.status === 301 ? 301 : 307 };
+  if (typeof parsed.from === "string") stored.from = parsed.from;
+  if (parsed.discardQueryParameters === true) stored.discardQueryParameters = true;
+  return stored;
+}

package/src/sdk/workerEntry.test.ts

@@ -230,7 +230,7 @@ describe("CMS redirects", () => {
     expect(res.headers.get("Location")).toBe("/new");
   });
 
-  it("redirects ?asJson requests too (does not fall through to page resolver)", async () => {
+  it("fresh: redirects ?asJson requests too, keeping the query (does not fall through to page resolver)", async () => {
     setBlocks({
       "redirect-1": {
         __resolveType: "website/loaders/redirect.ts",
@@ -239,6 +239,7 @@ describe("CMS redirects", () => {
     });
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, {
       observability: false,
+      redirects: { semantics: "fresh" },
     });
     const res = await worker.fetch(
       new Request("https://example.com/old?asJson"),
@@ -246,10 +247,83 @@ describe("CMS redirects", () => {
       MOCK_CTX,
     );
     expect(res.status).toBe(301);
-    expect(res.headers.get("Location")).toBe("/new");
+    // The query travels with the redirect, so the client that follows it
+    // still gets JSON for the page that moved.
+    expect(res.headers.get("Location")).toBe("/new?asJson");
   });
 
-  it("URI-encodes the Location header for non-ASCII destinations", async () => {
+  it("fresh: appends the request's query string to Location unless the rule discards it", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirects.ts",
+        redirects: [
+          { from: "/old", to: "/new", type: "permanent" },
+          { from: "/strip", to: "/clean?ref=1", type: "permanent", discardQueryParameters: true },
+        ],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, {
+      observability: false,
+      redirects: { semantics: "fresh" },
+    });
+    const kept = await worker.fetch(
+      new Request("https://example.com/old?utm_source=qa&gclid=x"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(kept.headers.get("Location")).toBe("/new?gclid=x&utm_source=qa");
+
+    const dropped = await worker.fetch(
+      new Request("https://example.com/strip?utm_source=qa"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(dropped.headers.get("Location")).toBe("/clean?ref=1");
+  });
+
+  it("fresh: matches a rule scoped to a query before the bare path, and case-sensitively", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirects.ts",
+        redirects: [
+          { from: "/kit/p", to: "/camisa/p", type: "permanent" },
+          { from: "/kit/p?skuId=4432", to: "/roupas/kits", type: "permanent" },
+          { from: "/Calca/p", to: "/calca/p", type: "permanent" },
+        ],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, {
+      observability: false,
+      redirects: { semantics: "fresh" },
+    });
+    const scoped = await worker.fetch(
+      new Request("https://example.com/kit/p?skuId=4432"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(scoped.headers.get("Location")).toBe("/roupas/kits?skuId=4432");
+
+    const bare = await worker.fetch(new Request("https://example.com/kit/p"), EMPTY_ENV, MOCK_CTX);
+    expect(bare.headers.get("Location")).toBe("/camisa/p");
+
+    // `/Calca/p -> /calca/p` is a redirect, not a loop: the lower-case URL
+    // has no rule and renders.
+    const upper = await worker.fetch(
+      new Request("https://example.com/Calca/p"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(upper.status).toBe(301);
+    expect(upper.headers.get("Location")).toBe("/calca/p");
+    const lower = await worker.fetch(
+      new Request("https://example.com/calca/p"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(lower.status).toBe(200);
+  });
+
+  it("fresh: URI-encodes the Location header for non-ASCII destinations", async () => {
     setBlocks({
       "redirect-1": {
         __resolveType: "website/loaders/redirect.ts",
@@ -258,13 +332,14 @@ describe("CMS redirects", () => {
     });
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, {
       observability: false,
+      redirects: { semantics: "fresh" },
     });
     const res = await worker.fetch(new Request("https://example.com/promo"), EMPTY_ENV, MOCK_CTX);
-    expect(res.status).toBe(302);
+    expect(res.status).toBe(307);
     expect(res.headers.get("Location")).toBe("/promo%C3%A7%C3%A3o");
   });
 
-  it("returns a 302 redirect for a temporary redirect block", async () => {
+  it("fresh: returns a 307 redirect for a temporary redirect block", async () => {
     setBlocks({
       "redirect-1": {
         __resolveType: "website/loaders/redirect.ts",
@@ -273,9 +348,10 @@ describe("CMS redirects", () => {
     });
     const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, {
       observability: false,
+      redirects: { semantics: "fresh" },
     });
     const res = await worker.fetch(new Request("https://example.com/promo"), EMPTY_ENV, MOCK_CTX);
-    expect(res.status).toBe(302);
+    expect(res.status).toBe(307);
     expect(res.headers.get("Location")).toBe("/sale");
   });
 
@@ -316,6 +392,45 @@ describe("CMS redirects", () => {
     expect(res2.status).toBe(301);
     expect(res2.headers.get("Location")).toBe("/v2");
   });
+
+  it("legacy (default): folds case and trailing slash, drops the query, 302 for temporary", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirects.ts",
+        redirects: [
+          { from: "/baixeoapp", to: "/baixe-o-app", type: "permanent" },
+          { from: "/promo", to: "/promoção", type: "temporary" },
+          { from: "/Calca/p", to: "/calca/p", type: "permanent" },
+        ],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, {
+      observability: false,
+    });
+    const folded = await worker.fetch(
+      new Request("https://example.com/BaixeoApp/?utm_source=a&asJson"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(folded.status).toBe(301);
+    expect(folded.headers.get("Location")).toBe("/baixe-o-app");
+
+    const temporary = await worker.fetch(
+      new Request("https://example.com/promo"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(temporary.status).toBe(302);
+    expect(temporary.headers.get("Location")).toBe("/promo%C3%A7%C3%A3o");
+
+    // Folded, this rule would redirect /calca/p to itself forever — dropped.
+    const loop = await worker.fetch(
+      new Request("https://example.com/calca/p"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(loop.status).toBe(200);
+  });
 });
 
 describe("degraded origin (anti-cache-poisoning)", () => {

package/src/sdk/workerEntry.ts

@@ -78,11 +78,14 @@ import {
 import { setRuntimeEnv } from "@decocms/blocks/sdk/otelAdapters";
 import { parseTraceparent } from "@decocms/blocks/sdk/otelHttpTracer";
 import {
+  getRedirectSemantics,
   loadRedirects,
   matchExactRedirect,
   matchPatternRedirect,
-  normalizePath,
   type RedirectMap,
+  type RedirectSemantics,
+  redirectLocation,
+  setRedirectSemantics,
 } from "@decocms/blocks/sdk/redirects";
 import { RequestContext } from "@decocms/blocks/sdk/requestContext";
 import { createResponseCache } from "@decocms/blocks/sdk/responseCache";
@@ -261,6 +264,16 @@ export interface DecoWorkerEntryOptions {
    */
   renderJson?: boolean;
 
+  /**
+   * `?renderJson` strips the request-derived keys the section mixins inject
+   * (`device`, `isMobile`, `currentSearchParam`) from every section. A section
+   * whose own loader returns one of them as content (Fresh: `device:
+   * ctx.device`, which production's `?renderJson` carries) can keep it here:
+   * resolveType suffix (matched like `renderJson.sectionsToIgnore`) → keys to
+   * preserve. Example: `{ "Product/ProductDetails.tsx": ["device"] }`.
+   */
+  renderJsonKeepKeys?: Record<string, readonly string[]>;
+
   /**
    * Serve the raw resolved page as JSON on `?asJson` (legacy admin-preview
    * path). Set to `false` to disable it site-wide.
@@ -615,6 +628,23 @@ export interface DecoWorkerEntryOptions {
    * @default `Deco/<version> (+https://deco.cx)` — see DECO_USER_AGENT.
    */
   outboundUserAgent?: string | false;
+
+  /**
+   * How CMS redirects (`website/loaders/redirect(s).ts`, `redirectsFromCsv`)
+   * match and answer — see `@decocms/blocks/sdk/redirects`.
+   *
+   * - `"legacy"` (default): case- and trailing-slash-insensitive match,
+   *   temporary → 302, the request's query dropped from `Location`. What every
+   *   `@decocms/*` site has answered so far.
+   * - `"fresh"`: what the Fresh site a migration came from answered — source
+   *   matched byte for byte (`pathname + search` first), temporary → 307, the
+   *   request's query appended to `Location` unless `discardQueryParameters`.
+   *
+   * Both drop self-redirects and never double-encode `Location`.
+   *
+   * @default { semantics: "legacy" }
+   */
+  redirects?: { semantics?: RedirectSemantics };
 }
 
 // ---------------------------------------------------------------------------
@@ -1153,6 +1183,7 @@ export function createDecoWorkerEntry(
     extraBypassPaths = [],
     fingerprintedAssetPattern = FINGERPRINTED_ASSET_RE,
     stripTrackingParams: shouldStripTracking = true,
+    redirects: redirectsOpt,
     previewShell: customPreviewShell,
     cacheVersionEnv = "BUILD_HASH",
     securityHeaders: securityHeadersOpt,
@@ -1168,6 +1199,10 @@ export function createDecoWorkerEntry(
     speculationRules: speculationRulesOpt,
   } = options;
 
+  // Before the first request builds the redirect map — the map keys its rules
+  // for the semantics in force when it is built.
+  setRedirectSemantics(redirectsOpt?.semantics ?? "legacy");
+
   // Speculation Rules — store the site-wide config in the shared singleton so
   // DecoRootLayout (SSR) emits the tag in <head>. Inert unless the site opts in.
   setSpeculationRules(speculationRulesOpt);
@@ -2313,7 +2348,9 @@ export function createDecoWorkerEntry(
     // ?asJson and commerce proxy so every request path respects redirects.
     // Revision-keyed so cross-bundle setBlocks() calls are detected even when
     // onChange listeners don't fire across Vite split-bundle module instances.
-    const currentRevision = getRevision();
+    // The semantics are part of the key: a map keys its rules for the
+    // semantics in force when it is built.
+    const currentRevision = `${getRevision()}:${getRedirectSemantics()}`;
     if (_redirectMapRevision !== currentRevision) {
       _redirectMap = loadRedirects(loadBlocks());
       _redirectMapRevision = currentRevision;
@@ -2323,14 +2360,16 @@ export function createDecoWorkerEntry(
     // 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.
+    // Query-scoped rules (`/x?map=ft`) live in memory only, so the KV lookup
+    // stays one read, keyed by pathname.
     const cmsRedirect =
-      matchExactRedirect(url.pathname, _redirectMap!) ??
-      (await lookupExactRedirect(env as Record<string, unknown>, normalizePath(url.pathname))) ??
+      matchExactRedirect(url.pathname, _redirectMap!, url.search) ??
+      (await lookupExactRedirect(env as Record<string, unknown>, url.pathname)) ??
       matchPatternRedirect(url.pathname, _redirectMap!);
     if (cmsRedirect) {
       return new Response(null, {
         status: cmsRedirect.status,
-        headers: { Location: encodeURI(cmsRedirect.to) },
+        headers: { Location: redirectLocation(cmsRedirect, url.search) },
       });
     }
 
@@ -2398,6 +2437,16 @@ export function createDecoWorkerEntry(
       const getSectionModule = (component: string) => ({
         renderJson: getSectionOptions(component)?.renderJson,
       });
+      const keepEntries = Object.entries(options.renderJsonKeepKeys ?? {});
+      const keepInjectedKeys =
+        keepEntries.length === 0
+          ? undefined
+          : (component: string) => {
+              const keys = keepEntries.flatMap(([suffix, k]) =>
+                component.endsWith(suffix) ? k : [],
+              );
+              return keys.length > 0 ? keys : undefined;
+            };
 
       const jsonHeaders = {
         ...corsHeaders,
@@ -2435,7 +2484,7 @@ export function createDecoWorkerEntry(
         }
         const [serialized] = serializeRenderJson(
           [{ component: resolved.component, props: resolved.props }],
-          { getSectionModule, sectionsToIgnore: ignoreSuffixes },
+          { getSectionModule, sectionsToIgnore: ignoreSuffixes, keepInjectedKeys },
         );
         if (!serialized) {
           return Response.json(
@@ -2466,6 +2515,7 @@ export function createDecoWorkerEntry(
           sectionsToIgnore: ignoreSuffixes,
           deferred: page.deferredSections.map((d) => ({ component: d.component, index: d.index })),
           lazyUrlFor,
+          keepInjectedKeys,
         },
       );