@decocms/tanstack 7.12.1 → 7.15.0

package/package.json

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

package/src/sdk/workerEntry.test.ts

@@ -1,5 +1,13 @@
-import { describe, expect, it } from "vitest";
-import { injectGeoCookies } from "./workerEntry";
+import { setBlocks } from "@decocms/blocks/cms";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildGeoCacheParam, createDecoWorkerEntry, detectLocationMatcher, injectGeoCookies } from "./workerEntry";
+import { __resetKvHydrationStateForTests } from "./kvHydration";
+
+const EMPTY_ENV = {};
+const MOCK_CTX = { waitUntil: (_p: Promise<unknown>) => {} };
+const MOCK_SERVER_ENTRY = {
+  fetch: async (_req: Request) => new Response("page content", { status: 200 }),
+};
 
 function parseCookies(header: string): Record<string, string> {
   return Object.fromEntries(
@@ -104,3 +112,204 @@ describe("injectGeoCookies", () => {
     expect(out.headers.get("cf-ray")).toBe("9ff5b26cf9bc067a");
   });
 });
+
+describe("buildGeoCacheParam", () => {
+  const cf = { country: "BR", region: "São Paulo", city: "SP" };
+
+  it("returns undefined when granularity is off", () => {
+    expect(buildGeoCacheParam(cf, "off")).toBeUndefined();
+  });
+
+  it("returns undefined when cf is undefined", () => {
+    expect(buildGeoCacheParam(undefined, "city")).toBeUndefined();
+  });
+
+  it("returns country only when granularity is country", () => {
+    expect(buildGeoCacheParam(cf, "country")).toBe("BR");
+  });
+
+  it("returns country|region when granularity is region", () => {
+    expect(buildGeoCacheParam(cf, "region")).toBe("BR|São Paulo");
+  });
+
+  it("returns country|region|city when granularity is city", () => {
+    expect(buildGeoCacheParam(cf, "city")).toBe("BR|São Paulo|SP");
+  });
+
+  it("omits missing fields gracefully", () => {
+    expect(buildGeoCacheParam({ country: "BR" }, "city")).toBe("BR");
+    expect(buildGeoCacheParam({ country: "BR", region: "MG" }, "city")).toBe("BR|MG");
+  });
+
+  it("returns undefined when cf has none of country/region/city", () => {
+    expect(buildGeoCacheParam({ asn: "12345" }, "city")).toBeUndefined();
+  });
+});
+
+describe("detectLocationMatcher", () => {
+  it("returns true when decofile has a website/matchers/location.ts __resolveType", () => {
+    const blocks = {
+      "audiences/geo-audience.json": {
+        "__resolveType": "website/flags/audience.ts",
+        "matcher": { "__resolveType": "website/matchers/location.ts", "includeLocations": [{ "country": "BR" }] },
+      },
+    };
+    expect(detectLocationMatcher(blocks)).toBe(true);
+  });
+
+  it("returns false when decofile has no location matcher", () => {
+    const blocks = {
+      "audiences/device-audience.json": {
+        "__resolveType": "website/flags/audience.ts",
+        "matcher": { "__resolveType": "website/matchers/device.ts" },
+      },
+    };
+    expect(detectLocationMatcher(blocks)).toBe(false);
+  });
+
+  it("returns false for an empty decofile", () => {
+    expect(detectLocationMatcher({})).toBe(false);
+  });
+
+  it("returns true when the matcher is nested deeply", () => {
+    const blocks = {
+      "pages/home.json": {
+        "variant": {
+          "matcher": { "__resolveType": "website/matchers/location.ts" },
+        },
+      },
+    };
+    expect(detectLocationMatcher(blocks)).toBe(true);
+  });
+
+  it("returns false when location.ts appears only in a non-resolveType string value (no false positive)", () => {
+    const blocks = {
+      "content/help.json": {
+        "__resolveType": "website/sections/RichText.tsx",
+        "body": "This page is controlled by website/matchers/location.ts for geo targeting.",
+      },
+    };
+    expect(detectLocationMatcher(blocks)).toBe(false);
+  });
+});
+
+describe("CMS redirects", () => {
+  afterEach(() => {
+    setBlocks({});
+    __resetKvHydrationStateForTests();
+  });
+
+  it("returns a 301 redirect for a permanent redirect block", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirect.ts",
+        redirects: [{ from: "/old", to: "/new", type: "permanent" }],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/old"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res.status).toBe(301);
+    expect(res.headers.get("Location")).toBe("/new");
+  });
+
+  it("redirects ?asJson requests too (does not fall through to page resolver)", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirect.ts",
+        redirects: [{ from: "/old", to: "/new", type: "permanent" }],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/old?asJson"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res.status).toBe(301);
+    expect(res.headers.get("Location")).toBe("/new");
+  });
+
+  it("URI-encodes the Location header for non-ASCII destinations", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirect.ts",
+        redirects: [{ from: "/promo", to: "/promoção", type: "temporary" }],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/promo"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res.status).toBe(302);
+    expect(res.headers.get("Location")).toBe("/promo%C3%A7%C3%A3o");
+  });
+
+  it("returns a 302 redirect for a temporary redirect block", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirect.ts",
+        redirects: [{ from: "/promo", to: "/sale", type: "temporary" }],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/promo"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res.status).toBe(302);
+    expect(res.headers.get("Location")).toBe("/sale");
+  });
+
+  it("falls through to serverEntry for paths with no redirect", async () => {
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirect.ts",
+        redirects: [{ from: "/old", to: "/new", type: "permanent" }],
+      },
+    });
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
+    const res = await worker.fetch(
+      new Request("https://example.com/other"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res.status).toBe(200);
+  });
+
+  it("picks up new redirects after setBlocks hot-reload", async () => {
+    setBlocks({});
+    const worker = createDecoWorkerEntry(MOCK_SERVER_ENTRY, { observability: false });
+
+    // First request with no redirects — falls through
+    const res1 = await worker.fetch(
+      new Request("https://example.com/v1"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res1.status).toBe(200);
+
+    // Hot-reload: add a redirect
+    setBlocks({
+      "redirect-1": {
+        __resolveType: "website/loaders/redirect.ts",
+        redirects: [{ from: "/v1", to: "/v2", type: "permanent" }],
+      },
+    });
+
+    // Same path should now redirect
+    const res2 = await worker.fetch(
+      new Request("https://example.com/v1"),
+      EMPTY_ENV,
+      MOCK_CTX,
+    );
+    expect(res2.status).toBe(301);
+    expect(res2.headers.get("Location")).toBe("/v2");
+  });
+});

package/src/sdk/workerEntry.ts

@@ -30,12 +30,15 @@ import { getAppMiddleware } from "@decocms/blocks-admin/sdk/setupApps";
 import {
   isBot,
   loadBlocks,
+  getRevision,
   type MatcherContext,
+  onChange,
   resolveDecoPage,
   runSectionLoaders,
   runSingleSectionLoader,
 } from "@decocms/blocks/cms";
 import { DECO_MATCHERS_OVERRIDE_PARAM } from "@decocms/blocks/matchers/override";
+import { loadRedirects, matchRedirect, type RedirectMap } from "@decocms/blocks/sdk/redirects";
 import {
   type CacheProfileName,
   cacheHeaders,
@@ -363,6 +366,29 @@ export interface DecoWorkerEntryOptions {
    */
   autoInjectGeoCookies?: boolean;
 
+  /**
+   * Controls how Cloudflare geo data is folded into edge cache keys.
+   *
+   * - `"auto"` (default): inspects the loaded decofile on every `setBlocks()`
+   *   call (startup + fast-deploy swaps). If any block is configured with
+   *   `website/matchers/location.ts`, geo keying is activated at `"region"`
+   *   granularity (country+state); otherwise it is set to `"off"`. `"region"`
+   *   covers VTEX regionalization and most geo matchers without city-level
+   *   fragmentation. Sites that need city precision should set `"city"`
+   *   explicitly. No manual configuration needed for the common case.
+   * - `"city"`: full `country|region|city` key — maximum isolation for sites
+   *   with city-level location matchers.
+   * - `"region"`: `country|region` — good for region/state matchers (e.g.
+   *   VTEX regionalization), avoids city-level fragmentation.
+   * - `"country"`: country only.
+   * - `"off"`: no `__cf_geo` param is added and the automatic `regionId`
+   *   backfill from CF geo is disabled. Use for single-catalog storefronts
+   *   that do not vary content by location — recovers the full edge HIT rate.
+   *
+   * @default "auto"
+   */
+  geoCacheKey?: "auto" | "off" | "country" | "region" | "city";
+
   /**
    * Cookie names considered "safe" for caching — these are public/anonymous
    * cookies that do not carry per-user session or auth data.
@@ -501,6 +527,43 @@ function buildPreviewShell(): string {
  * };
  * ```
  */
+/**
+ * Returns `true` when the decofile contains at least one block whose
+ * `__resolveType` is `website/matchers/location.ts`. Used by
+ * `geoCacheKey: "auto"` to decide whether geo cache key fragmentation
+ * should be active.
+ *
+ * Matches only resolver-type references (not arbitrary string values) to
+ * avoid false positives from content/label fields that happen to mention
+ * the path.
+ */
+export function detectLocationMatcher(blocks: Record<string, unknown>): boolean {
+  return JSON.stringify(blocks).includes('"__resolveType":"website/matchers/location.ts"');
+}
+
+/**
+ * Build the `__cf_geo` cache-key fragment from Cloudflare's `request.cf`
+ * object at the requested granularity.
+ *
+ * Returns `undefined` when `granularity` is `"off"`, `cf` is absent, or no
+ * relevant fields are present.
+ *
+ * @example
+ * buildGeoCacheParam({ country: "BR", region: "São Paulo", city: "SP" }, "region")
+ * // → "BR|São Paulo"
+ */
+export function buildGeoCacheParam(
+  cf: Record<string, string> | undefined,
+  granularity: "off" | "country" | "region" | "city",
+): string | undefined {
+  if (granularity === "off" || !cf) return undefined;
+  const parts: string[] = [];
+  if (cf.country) parts.push(cf.country);
+  if (granularity !== "country" && cf.region) parts.push(cf.region);
+  if (granularity === "city" && cf.city) parts.push(cf.city);
+  return parts.length ? parts.join("|") : undefined;
+}
+
 export function injectGeoCookies(request: Request): Request {
   const cf = (request as unknown as { cf?: Record<string, string> }).cf;
   if (!cf) return request;
@@ -677,6 +740,28 @@ function deduplicateSetCookies(response: Response): void {
 
 const FINGERPRINTED_ASSET_RE = /(?:\/_build)?\/assets\/.*-[a-zA-Z0-9_-]{8,}\.\w+$/;
 
+// ---------------------------------------------------------------------------
+// Auto geo-key detection (module-level singleton)
+// ---------------------------------------------------------------------------
+// Registered once so that multiple createDecoWorkerEntry calls in the same
+// isolate (e.g. integration tests) don't accumulate listeners. Uses "region"
+// (country+state) as the auto granularity — covers VTEX regionalization and
+// most geo matchers without the city-level fragmentation (~hundreds of buckets).
+// Sites that need city precision should set geoCacheKey: "city" explicitly.
+
+let _autoGeoKey: "off" | "region" = "off";
+let _autoGeoListenerInstalled = false;
+
+function installAutoGeoListener(): void {
+  if (_autoGeoListenerInstalled) return;
+  _autoGeoListenerInstalled = true;
+  const update = (blocks: Record<string, unknown>) => {
+    _autoGeoKey = detectLocationMatcher(blocks) ? "region" : "off";
+  };
+  onChange(update);
+  update(loadBlocks());
+}
+
 const IMMUTABLE_HEADERS: Record<string, string> = {
   "Cache-Control": `public, max-age=${ONE_YEAR}, immutable`,
   Vary: "Accept-Encoding",
@@ -691,6 +776,14 @@ async function hashText(text: string): Promise<string> {
     .join("");
 }
 
+// ---------------------------------------------------------------------------
+// CMS redirect cache — keyed by revision so cross-bundle setBlocks() calls
+// (Vite server-function split) are detected via globalThis.__deco.revision.
+// ---------------------------------------------------------------------------
+
+let _redirectMap: RedirectMap | null = null;
+let _redirectMapRevision: string | null = null;
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -724,6 +817,7 @@ export function createDecoWorkerEntry(
     securityHeaders: securityHeadersOpt,
     csp: cspOpt,
     autoInjectGeoCookies: geoOpt = true,
+    geoCacheKey: geoCacheKeyOpt = "auto",
     safeCookies: safeCookiesOpt = DEFAULT_SAFE_COOKIES,
     staticPaths: staticPathsOpt = DEFAULT_STATIC_PATHS,
     cdnCacheControl: cdnCacheControlOpt = "no-store",
@@ -740,6 +834,19 @@ export function createDecoWorkerEntry(
     installDefaultUserAgent(outboundUserAgentOpt);
   }
 
+  // When geoCacheKey is "auto", install the module-level listener that watches
+  // the decofile for website/matchers/location.ts. The listener is registered
+  // only once regardless of how many times this factory is called, so there is
+  // no listener accumulation in tests or dynamic worker-composition scenarios.
+  if (geoCacheKeyOpt === "auto") {
+    installAutoGeoListener();
+  }
+
+  /** Resolve the effective geo granularity for the current request. */
+  function effectiveGeoKey(): "off" | "country" | "region" | "city" {
+    return geoCacheKeyOpt === "auto" ? _autoGeoKey : geoCacheKeyOpt;
+  }
+
   // Backfill `regionId` from Cloudflare geo when the consumer's buildSegment
   // doesn't set one. Without this, sites using website/matchers/location.ts
   // get a single cached response per device that leaks across regions: the
@@ -760,6 +867,7 @@ export function createDecoWorkerEntry(
     ? (request: Request): SegmentKey => {
         const seg = rawBuildSegment(request);
         if (seg.regionId) return seg;
+        if (effectiveGeoKey() === "off") return seg;
         const region = readRegionFromRequest(request);
         return region ? { ...seg, regionId: region } : seg;
       }
@@ -913,17 +1021,14 @@ export function createDecoWorkerEntry(
     }
 
     // Include CF geo data in cache key so location matcher results don't leak
-    // across different geos. Applies to both segment and device-based keys.
-    const cf = (request as unknown as { cf?: Record<string, string> }).cf;
-    if (cf) {
-      const geoParts: string[] = [];
-      if (cf.country) geoParts.push(cf.country);
-      if (cf.region) geoParts.push(cf.region);
-      if (cf.city) geoParts.push(cf.city);
-      if (geoParts.length) {
-        url.searchParams.set("__cf_geo", geoParts.join("|"));
-      }
-    }
+    // across different geos. Granularity is controlled by `geoCacheKey`:
+    // "city" (default) → country|region|city, "region" → country|region,
+    // "country" → country only, "off" → omitted entirely.
+    const geoParam = buildGeoCacheParam(
+      (request as unknown as { cf?: Record<string, string> }).cf,
+      effectiveGeoKey(),
+    );
+    if (geoParam) url.searchParams.set("__cf_geo", geoParam);
 
     // Bots render every section eagerly (shouldDeferSection short-circuits in
     // resolve.ts), producing a ~10x larger HTML payload (all eager-section
@@ -1449,6 +1554,23 @@ export function createDecoWorkerEntry(
       return handlePurge(request, env);
     }
 
+    // CMS redirects (website/loaders/redirect.ts blocks) — checked before
+    // ?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();
+    if (_redirectMapRevision !== currentRevision) {
+      _redirectMap = loadRedirects(loadBlocks());
+      _redirectMapRevision = currentRevision;
+    }
+    const cmsRedirect = matchRedirect(url.pathname, _redirectMap!);
+    if (cmsRedirect) {
+      return new Response(null, {
+        status: cmsRedirect.status,
+        headers: { Location: encodeURI(cmsRedirect.to) },
+      });
+    }
+
     // ?asJson — return resolved page data as JSON (legacy deco compat)
     if (url.searchParams.has("asJson") && request.method === "GET") {
       const basePath = url.pathname;
@@ -1644,15 +1766,14 @@ export function createDecoWorkerEntry(
         const device = isMobileUA(request.headers.get("user-agent") ?? "") ? "mobile" : "desktop";
         cacheKeyUrl.searchParams.set("__cf_device", device);
       }
-      // Include CF geo data so location-based content doesn't leak across geos
-      const cf = (request as unknown as { cf?: Record<string, string> }).cf;
-      if (cf) {
-        const geoParts: string[] = [];
-        if (cf.country) geoParts.push(cf.country);
-        if (cf.region) geoParts.push(cf.region);
-        if (cf.city) geoParts.push(cf.city);
-        if (geoParts.length) cacheKeyUrl.searchParams.set("__cf_geo", geoParts.join("|"));
-      }
+      // Include CF geo data so location-based content doesn't leak across geos.
+      // Uses the same effectiveGeoKey() as the GET path so geoCacheKey config
+      // is respected consistently for both HTML and server-fn responses.
+      const sfnGeoParam = buildGeoCacheParam(
+        (request as unknown as { cf?: Record<string, string> }).cf,
+        effectiveGeoKey(),
+      );
+      if (sfnGeoParam) cacheKeyUrl.searchParams.set("__cf_geo", sfnGeoParam);
       const sfnCacheKey = new Request(cacheKeyUrl.toString(), { method: "GET" });
 
       // Use "listing" profile for server function responses