@decocms/tanstack 7.2.3 → 7.3.0

package/package.json

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

package/src/routes/cmsRoute.ts

@@ -27,6 +27,7 @@ import {
   getRequest,
   getRequestHeader,
   getRequestUrl,
+  setCookie,
   setResponseHeader,
 } from "@tanstack/react-start/server";
 import { createElement } from "react";
@@ -44,6 +45,12 @@ import {
   runSingleSectionLoader,
 } from "@decocms/blocks/cms";
 import type { DeferredSection, MatcherContext, PageSeo, ResolvedSection } from "@decocms/blocks/cms";
+import {
+  parseSegmentCookie,
+  SEGMENT_COOKIE,
+  serializeSegmentCookie,
+  type StoredFlag,
+} from "@decocms/blocks/sdk/flags";
 import { withTracing } from "@decocms/blocks/middleware/observability";
 import {
   type CacheProfileName,
@@ -78,6 +85,45 @@ export function setSectionChunkMap(map: Record<string, string>): void {
 type PageResult = Awaited<ReturnType<typeof loadCmsPageInternal>>;
 const pageInflight = new Map<string, Promise<PageResult>>();
 
+/** One year — the cohort is sticky; the `pct` fingerprint handles re-rolls. */
+const SEGMENT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+/**
+ * Persist sticky A/B decisions recorded during resolution and return them for
+ * the client (analytics).
+ *
+ * Merges the freshly recorded flags over any already in the `deco_segment`
+ * cookie (so navigating to a second A/B page doesn't drop the first page's
+ * cohort), and only re-issues the cookie when the merged value changed.
+ * Setting the cookie also makes the worker skip caching THIS response
+ * (`deco_segment` is not a "safe" cookie), so an unassigned visitor never
+ * poisons the shared entry — their next request carries the cookie and hits
+ * the per-cohort cache entry.
+ *
+ * `encode: (v) => v` keeps the raw base64 intact — @decocms/apps
+ * OneDollarStats reads the cookie with `atob()` directly.
+ */
+function persistFlags(matcherCtx: MatcherContext): StoredFlag[] {
+  const recorded = matcherCtx.flags ?? [];
+  if (!recorded.length) return [];
+
+  const raw = matcherCtx.cookies?.[SEGMENT_COOKIE];
+  const merged = new Map<string, StoredFlag>();
+  for (const f of parseSegmentCookie(raw)) merged.set(f.name, f);
+  for (const f of recorded) merged.set(f.name, f);
+
+  const serialized = serializeSegmentCookie([...merged.values()]);
+  if (serialized !== (raw ?? "")) {
+    setCookie(SEGMENT_COOKIE, serialized, {
+      path: "/",
+      maxAge: SEGMENT_COOKIE_MAX_AGE,
+      sameSite: "lax",
+      encode: (v) => v,
+    });
+  }
+  return recorded;
+}
+
 async function loadCmsPageInternal(fullPath: string) {
   const [basePath] = fullPath.split("?");
   // On client-side navigation getRequestUrl() is the /_serverFn/... endpoint,
@@ -94,9 +140,11 @@ async function loadCmsPageInternal(fullPath: string) {
     cookies: getCookies(),
     request: originRequest,
     isClientNavigation: isClientNavigation(fullPath, serverUrl),
+    flags: [],
   };
   const page = await resolveDecoPage(basePath, matcherCtx);
   if (!page) return null;
+  const flags = persistFlags(matcherCtx);
 
   const request = new Request(urlWithSearch, {
     headers: originRequest.headers,
@@ -144,6 +192,7 @@ async function loadCmsPageInternal(fullPath: string) {
     pagePath: basePath,
     seo,
     device,
+    flags,
     siteGlobals: { rawRefs: globals.rawRefs },
   };
 }
@@ -179,9 +228,11 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
     cookies: getCookies(),
     request,
     isClientNavigation: isClientNavigation("/", serverUrl),
+    flags: [],
   };
   const page = await resolveDecoPage("/", matcherCtx);
   if (!page) return null;
+  const flags = persistFlags(matcherCtx);
   const [enrichedSections, globals] = await Promise.all([
     runSectionLoaders(page.resolvedSections, request),
     resolveSiteGlobals(),
@@ -208,6 +259,7 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
     pageUrl: serverUrl.toString(),
     seo,
     device,
+    flags,
     siteGlobals: { rawRefs: globals.rawRefs },
   };
 });

package/src/sdk/outboundHeaders.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  _uninstallDefaultUserAgentForTests,
+  DECO_POWERED_BY,
+  DECO_USER_AGENT,
+  installDefaultUserAgent,
+} from "./outboundHeaders";
+
+/** Headers the wrapped baseFetch would put on the wire for a given call. */
+function wireHeaders(call: readonly [RequestInfo | URL, RequestInit?]): Headers {
+  const [input, init] = call;
+  if (init?.headers !== undefined) return new Headers(init.headers);
+  if (input instanceof Request) return new Headers(input.headers);
+  return new Headers();
+}
+
+describe("installDefaultUserAgent", () => {
+  const realFetch = globalThis.fetch;
+
+  afterEach(() => {
+    _uninstallDefaultUserAgentForTests();
+    globalThis.fetch = realFetch;
+    vi.restoreAllMocks();
+  });
+
+  function install(userAgent?: string) {
+    const baseFetch = vi.fn(
+      async (_input: RequestInfo | URL, _init?: RequestInit) => new Response("ok"),
+    );
+    globalThis.fetch = baseFetch as unknown as typeof fetch;
+    installDefaultUserAgent(userAgent);
+    return baseFetch;
+  }
+
+  it("sets the default UA on a bare string fetch", async () => {
+    const baseFetch = install();
+    await fetch("https://api.example.com/products");
+
+    const headers = wireHeaders(baseFetch.mock.calls[0]);
+    expect(headers.get("user-agent")).toBe(DECO_USER_AGENT);
+  });
+
+  it("keeps the caller's UA from init.headers", async () => {
+    const baseFetch = install();
+    await fetch("https://api.example.com/", {
+      headers: { "user-agent": "deco-aws-app/1.0" },
+    });
+
+    // Untouched call: init passed through verbatim.
+    expect(baseFetch.mock.calls[0][1]).toEqual({
+      headers: { "user-agent": "deco-aws-app/1.0" },
+    });
+  });
+
+  it("keeps the UA of a Request input", async () => {
+    const baseFetch = install();
+    const req = new Request("https://api.example.com/", {
+      headers: { "User-Agent": "decocx/1.0" },
+    });
+    await fetch(req);
+
+    expect(baseFetch.mock.calls[0][0]).toBe(req);
+    expect(baseFetch.mock.calls[0][1]).toBeUndefined();
+  });
+
+  it("preserves a Request's other headers when injecting the UA", async () => {
+    const baseFetch = install();
+    await fetch(
+      new Request("https://api.example.com/", {
+        headers: { accept: "application/json", "x-api-key": "k" },
+      }),
+    );
+
+    const headers = wireHeaders(baseFetch.mock.calls[0]);
+    expect(headers.get("user-agent")).toBe(DECO_USER_AGENT);
+    expect(headers.get("accept")).toBe("application/json");
+    expect(headers.get("x-api-key")).toBe("k");
+  });
+
+  it("preserves non-header init members (method, body, signal)", async () => {
+    const baseFetch = install();
+    const controller = new AbortController();
+    await fetch("https://api.example.com/", {
+      method: "POST",
+      body: "{}",
+      signal: controller.signal,
+    });
+
+    const init = baseFetch.mock.calls[0][1]!;
+    expect(init.method).toBe("POST");
+    expect(init.body).toBe("{}");
+    expect(init.signal).toBe(controller.signal);
+    expect(new Headers(init.headers).get("user-agent")).toBe(DECO_USER_AGENT);
+  });
+
+  it("honors a custom UA value", async () => {
+    const baseFetch = install("MyStore-Migration/1.0");
+    await fetch("https://api.example.com/");
+
+    expect(wireHeaders(baseFetch.mock.calls[0]).get("user-agent")).toBe("MyStore-Migration/1.0");
+  });
+
+  it("is idempotent — a second install does not re-wrap", () => {
+    install();
+    const wrapped = globalThis.fetch;
+    installDefaultUserAgent();
+    expect(globalThis.fetch).toBe(wrapped);
+  });
+
+  it("exposes the old-runtime-parity x-powered-by value", () => {
+    expect(DECO_POWERED_BY).toMatch(/^deco@\d+\.\d+\.\d+/);
+  });
+});

package/src/sdk/outboundHeaders.ts

@@ -0,0 +1,81 @@
+/**
+ * Runtime identification headers.
+ *
+ * Outbound: Cloudflare Workers' `fetch` sends NO `User-Agent` header at
+ * all — unlike the old Deno runtime, where every outbound request carried
+ * Deno's implicit `User-Agent: Deno/x.y.z`. UA-less requests are a strong
+ * bot signal: Cloudflare managed WAF rules and Bot Fight Mode on partner
+ * origins block them outright. `installDefaultUserAgent()` restores the
+ * pre-migration behavior with an honest, allowlistable value, applied only
+ * when the caller didn't set a User-Agent of its own.
+ *
+ * Responses: the old runtime stamped `x-powered-by: deco@<version>` on
+ * every response (deco-cx/deco `utils/http.ts` defaultHeaders). The worker
+ * entry reuses `DECO_POWERED_BY` for parity.
+ */
+
+import pkg from "../../package.json";
+
+/**
+ * Default outbound User-Agent. Stable prefix (`Deco/`) so partners can
+ * write one WAF allowlist rule that survives version bumps and platform
+ * changes; the URL comment tells whoever reads an access log who we are.
+ */
+export const DECO_USER_AGENT = `Deco/${pkg.version} (+https://deco.cx)`;
+
+/** Response identification header value — parity with deco-cx/deco. */
+export const DECO_POWERED_BY = `deco@${pkg.version}`;
+
+/**
+ * Cross-module guard on `globalThis` (same trick as logger.ts STATE_KEY):
+ * bundlers may duplicate this module across chunks, so a module-local
+ * boolean would not prevent double-wrapping.
+ */
+const INSTALLED_KEY = Symbol.for("deco.outboundHeaders.installed");
+
+let restoreBaseFetch: (() => void) | undefined;
+
+/**
+ * Patch `globalThis.fetch` so every outbound request carries a User-Agent.
+ *
+ * Set-if-absent only: app-specific UAs (`deco-aws-app/1.0`, `decocx/1.0`,
+ * ...) always win, matching the old runtime where Deno's default applied
+ * only when unset. All other RequestInit members (method, body, signal,
+ * `cf`, ...) pass through untouched. Idempotent — safe to call more than
+ * once (e.g. worker entry + tests).
+ */
+export function installDefaultUserAgent(userAgent: string = DECO_USER_AGENT): void {
+  const g = globalThis as Record<symbol, unknown>;
+  if (g[INSTALLED_KEY]) return;
+  g[INSTALLED_KEY] = true;
+
+  const baseFetch = globalThis.fetch;
+  restoreBaseFetch = () => {
+    globalThis.fetch = baseFetch;
+    delete g[INSTALLED_KEY];
+  };
+
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    // Fetch-spec semantics (same rule instrumentedFetch.ts documents):
+    // when both a Request and `init.headers` are passed, `init.headers`
+    // REPLACES the Request's headers — they do not union. So the headers
+    // that will actually hit the wire are init.headers if present, else
+    // the Request's own headers, else none.
+    const base =
+      init?.headers !== undefined
+        ? init.headers
+        : input instanceof Request
+          ? input.headers
+          : undefined;
+    const headers = new Headers(base ?? undefined);
+    if (headers.has("user-agent")) return baseFetch(input, init);
+    headers.set("user-agent", userAgent);
+    return baseFetch(input, { ...init, headers });
+  }) as typeof fetch;
+}
+
+/** Test-only: restore the unpatched fetch. Do not call from app code. */
+export function _uninstallDefaultUserAgentForTests(): void {
+  restoreBaseFetch?.();
+  restoreBaseFetch = undefined;
+}

package/src/sdk/workerEntry.ts

@@ -45,6 +45,7 @@ import {
   getCacheProfile,
   serverFnPagePath,
 } from "@decocms/blocks/sdk/cacheHeaders";
+import { parseSegmentCookie, SEGMENT_COOKIE, segmentCacheToken } from "@decocms/blocks/sdk/flags";
 import { buildHtmlShell } from "@decocms/blocks-admin/sdk/htmlShell";
 import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
 import {
@@ -61,6 +62,7 @@ import {
   instrumentWorker,
   type OtelOptions,
 } from "@decocms/blocks/sdk/otel";
+import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
 import { setRuntimeEnv } from "@decocms/blocks/sdk/otelAdapters";
 import { parseTraceparent } from "@decocms/blocks/sdk/otelHttpTracer";
 import { RequestContext } from "@decocms/blocks/sdk/requestContext";
@@ -434,6 +436,25 @@ export interface DecoWorkerEntryOptions {
    * no-op — no buffers, no flushes, no network calls.
    */
   observability?: OtelOptions | false;
+
+  /**
+   * Default `User-Agent` for OUTBOUND `fetch` calls (loaders, commerce
+   * APIs, proxies). Cloudflare Workers sends no User-Agent at all, and
+   * UA-less requests are blocked by common WAF setups (Cloudflare managed
+   * rules / Bot Fight Mode) on partner origins. The old Deno runtime
+   * implicitly sent `Deno/x.y.z` on every outbound request, so this
+   * restores pre-migration behavior with an identifiable value.
+   *
+   * Applied only when the caller didn't set a User-Agent — app-specific
+   * UAs always win.
+   *
+   * - Pass a string to override the value (e.g. to match a partner's
+   *   existing WAF allowlist during migration).
+   * - Pass `false` to leave `globalThis.fetch` untouched.
+   *
+   * @default `Deco/<version> (+https://deco.cx)` — see DECO_USER_AGENT.
+   */
+  outboundUserAgent?: string | false;
 }
 
 // ---------------------------------------------------------------------------
@@ -707,8 +728,18 @@ export function createDecoWorkerEntry(
     staticPaths: staticPathsOpt = DEFAULT_STATIC_PATHS,
     cdnCacheControl: cdnCacheControlOpt = "no-store",
     observability: observabilityOpt,
+    outboundUserAgent: outboundUserAgentOpt,
   } = options;
 
+  // Patch global fetch once so every outbound request — apps calling
+  // `fetch` directly, RequestContext.fetch, instrumentedFetch — carries a
+  // User-Agent. Workers sends none by default, which WAFs on partner
+  // origins read as bot traffic. Set-if-absent: callers that set their
+  // own UA are untouched.
+  if (outboundUserAgentOpt !== false) {
+    installDefaultUserAgent(outboundUserAgentOpt);
+  }
+
   // 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
@@ -830,6 +861,25 @@ export function createDecoWorkerEntry(
     return typeof __DECO_BUILD_HASH__ !== "undefined" ? __DECO_BUILD_HASH__ : "";
   }
 
+  function readRequestCookie(request: Request, name: string): string | undefined {
+    for (const pair of (request.headers.get("cookie") ?? "").split(";")) {
+      const idx = pair.indexOf("=");
+      if (idx <= 0) continue;
+      if (pair.slice(0, idx).trim() !== name) continue;
+      const raw = pair.slice(idx + 1).trim();
+      // Decode once so this matches TanStack's getCookies() used during SSR
+      // (see cms/resolve.ts) — otherwise the worker's cache key and the render
+      // could disagree on the cohort. The deco_segment value is raw base64 (no
+      // percent-escapes), so decoding is a no-op for it and safe in general.
+      try {
+        return decodeURIComponent(raw);
+      } catch {
+        return raw;
+      }
+    }
+    return undefined;
+  }
+
   function buildCacheKey(
     request: Request,
     env: Record<string, unknown>,
@@ -904,6 +954,18 @@ export function createDecoWorkerEntry(
       url.searchParams.set("__fetch", "1");
     }
 
+    // A/B cohort split: fold the sticky `deco_segment` cookie into the cache
+    // key so each variant keeps its own cached HTML. The cookie carries the
+    // traffic fingerprint (see sdk/flags.ts), so a `traffic` change lands
+    // cohorts in fresh buckets. Empty for non-A/B visitors (no cookie) → they
+    // keep sharing one entry. A freshly-assigned visitor sets the cookie on the
+    // response, which is not a "safe" cookie, so that one response bypasses the
+    // cache and never poisons the shared entry.
+    const flagToken = segmentCacheToken(parseSegmentCookie(readRequestCookie(request, SEGMENT_COOKIE)));
+    if (flagToken) {
+      url.searchParams.set("__abf", flagToken);
+    }
+
     if (buildSegment) {
       const segment = buildSegment(request);
       url.searchParams.set("__seg", hashSegment(segment));
@@ -1311,6 +1373,18 @@ export function createDecoWorkerEntry(
         }
       }
 
+      // Old-runtime parity: deco-cx/deco stamped `x-powered-by: deco@<ver>`
+      // on every response (utils/http.ts defaultHeaders); partner-side logs
+      // and ops tooling use it to identify deco traffic. Set-if-absent so
+      // an upstream origin's own value wins.
+      if (!finalResponse.headers.has("x-powered-by")) {
+        try {
+          finalResponse.headers.set("x-powered-by", DECO_POWERED_BY);
+        } catch {
+          /* sealed headers (cached replay) — identification is best-effort */
+        }
+      }
+
       // Metrics + structured request log. Done after security headers so
       // the recorded status reflects what the client actually receives.
       // Both calls are no-ops when no meter / logger is configured.
@@ -1318,8 +1392,9 @@ export function createDecoWorkerEntry(
       try {
         // Phase 2 / D-11 canonical labels — lift the cache decision +
         // profile + region off the response we just built so dashboards
-        // can answer "cache hit rate per route" from `http_requests_total`
-        // alone, no join to `cache_*_total` required.
+        // can answer "cache hit rate per route" from
+        // `http.server.request.duration` alone, no join to a cache counter
+        // required.
         const xCacheRaw = finalResponse.headers.get("X-Cache");
         const cacheDecision = isCacheDecision(xCacheRaw) ? xCacheRaw : undefined;
         const colo = (request as unknown as { cf?: { colo?: string } }).cf?.colo;

package/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "outDir": "dist"
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*", "package.json"]
 }