@decocms/tanstack 8.0.0 → 8.1.0-next.0

package/src/sdk/router.ts

@@ -6,61 +6,63 @@
  * filter URLs like `?filter.brand=Nike&filter.brand=Adidas` which must
  * round-trip correctly through the router's search system.
  */
-import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+
+import { getRequestNonce } from "@decocms/blocks/sdk/nonce";
 import type {
-	SearchSerializer,
-	SearchParser,
-	AnyRoute,
-	TrailingSlashOption,
+  AnyRoute,
+  SearchParser,
+  SearchSerializer,
+  TrailingSlashOption,
 } from "@tanstack/react-router";
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
 
 export const decoParseSearch: SearchParser = (searchStr) => {
-	const str = searchStr.startsWith("?") ? searchStr.slice(1) : searchStr;
-	if (!str) return {};
+  const str = searchStr.startsWith("?") ? searchStr.slice(1) : searchStr;
+  if (!str) return {};
 
-	const params = new URLSearchParams(str);
-	const result: Record<string, string | string[]> = {};
+  const params = new URLSearchParams(str);
+  const result: Record<string, string | string[]> = {};
 
-	for (const key of new Set(params.keys())) {
-		const values = params.getAll(key);
-		result[key] = values.length === 1 ? values[0] : values;
-	}
-	return result;
+  for (const key of new Set(params.keys())) {
+    const values = params.getAll(key);
+    result[key] = values.length === 1 ? values[0] : values;
+  }
+  return result;
 };
 
 export const decoStringifySearch: SearchSerializer = (search) => {
-	const params = new URLSearchParams();
-	for (const [key, value] of Object.entries(search)) {
-		if (value === undefined || value === null || value === "") continue;
-		if (Array.isArray(value)) {
-			for (const v of value) params.append(key, String(v));
-		} else {
-			params.append(key, String(value));
-		}
-	}
-	const str = params.toString();
-	return str ? `?${str}` : "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(search)) {
+    if (value === undefined || value === null || value === "") continue;
+    if (Array.isArray(value)) {
+      for (const v of value) params.append(key, String(v));
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  const str = params.toString();
+  return str ? `?${str}` : "";
 };
 
 export interface CreateDecoRouterOptions {
-	routeTree: AnyRoute;
-	scrollRestoration?: boolean;
-	defaultPreload?: "intent" | "viewport" | "render" | false;
-	trailingSlash?: TrailingSlashOption;
-	/**
-	 * Router context — passed to all route loaders/components via routeContext.
-	 * Commonly used for { queryClient } per TanStack Query integration docs.
-	 */
-	context?: Record<string, unknown>;
-	/**
-	 * Non-DOM provider component to wrap the entire router.
-	 * Per TanStack docs, only non-DOM-rendering components (providers) should
-	 * be used — anything else causes hydration errors.
-	 *
-	 * Example: QueryClientProvider wrapping
-	 *   Wrap: ({ children }) => <QueryClientProvider client={qc}>{children}</QueryClientProvider>
-	 */
-	Wrap?: (props: { children: any }) => any;
+  routeTree: AnyRoute;
+  scrollRestoration?: boolean;
+  defaultPreload?: "intent" | "viewport" | "render" | false;
+  trailingSlash?: TrailingSlashOption;
+  /**
+   * Router context — passed to all route loaders/components via routeContext.
+   * Commonly used for { queryClient } per TanStack Query integration docs.
+   */
+  context?: Record<string, unknown>;
+  /**
+   * Non-DOM provider component to wrap the entire router.
+   * Per TanStack docs, only non-DOM-rendering components (providers) should
+   * be used — anything else causes hydration errors.
+   *
+   * Example: QueryClientProvider wrapping
+   *   Wrap: ({ children }) => <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+   */
+  Wrap?: (props: { children: any }) => any;
 }
 
 /**
@@ -70,23 +72,30 @@ export interface CreateDecoRouterOptions {
  * - Preload on intent
  */
 export function createDecoRouter(options: CreateDecoRouterOptions) {
-	const {
-		routeTree,
-		scrollRestoration = true,
-		defaultPreload = "intent",
-		trailingSlash,
-		context,
-		Wrap,
-	} = options;
+  const {
+    routeTree,
+    scrollRestoration = true,
+    defaultPreload = "intent",
+    trailingSlash,
+    context,
+    Wrap,
+  } = options;
+
+  // On the server, `getRouter()` runs per request inside `RequestContext.run`,
+  // so this reads the request's CSP nonce (enforce mode) — `ScriptOnce` and
+  // TanStack's own hydration scripts read `router.options.ssr.nonce` and stamp
+  // it. `undefined` in report-only mode and on the client, where it's a no-op.
+  const nonce = getRequestNonce();
 
-	return createTanStackRouter({
-		routeTree,
-		scrollRestoration,
-		defaultPreload,
-		trailingSlash,
-		context: context as any,
-		Wrap,
-		parseSearch: decoParseSearch,
-		stringifySearch: decoStringifySearch,
-	});
+  return createTanStackRouter({
+    routeTree,
+    scrollRestoration,
+    defaultPreload,
+    trailingSlash,
+    context: context as any,
+    Wrap,
+    parseSearch: decoParseSearch,
+    stringifySearch: decoStringifySearch,
+    ...(nonce ? { ssr: { nonce } } : {}),
+  });
 }

package/src/sdk/serverFnFetch.ts

@@ -0,0 +1,59 @@
+/**
+ * Client-side `serverFns.fetch` hook that echoes the CDN segment marker onto
+ * `/_serverFn` URLs.
+ *
+ * Pairs with `cdnCacheControl: "serverfn-segment"` on `createDecoWorkerEntry`.
+ * Putting the segment in the URL is what makes the key of whatever caches in
+ * front of the Worker equivalent to the Worker's own — see `./cdnSegment`.
+ *
+ * The client does not COMPUTE the token, it repeats one the server issued and
+ * published on the page. That is deliberate: the segment includes dimensions
+ * only the server can see (region comes from `request.cf`), so a client-derived
+ * token never matched on a regionalized store and the feature stayed inert
+ * there.
+ *
+ * Only client-initiated requests carry it — SPA navigation and prefetch, which
+ * is the volume Speculation Rules generates. The initial HTML document is a
+ * browser navigation with no hook to attach anything to.
+ *
+ * SECURITY: the marker is a HINT. The worker recomputes the segment from the
+ * request itself and only relaxes `no-store` on an exact match
+ * (`cdnCacheableServerFn` in `./workerEntry`). A missing, stale, forged or
+ * mismatched marker just keeps today's `no-store` — it can never produce a
+ * wrong response.
+ *
+ * Wired automatically: `decoVitePlugin` supplies `sdk/startEntry` as the Start
+ * entry when a site has no `src/start.ts` of its own. A site that owns one
+ * composes this itself:
+ *
+ * ```ts
+ * import { decoServerFnFetch } from "@decocms/tanstack/sdk/serverFnFetch";
+ * export const startInstance = createStart(() => ({
+ *   serverFns: { fetch: decoServerFnFetch },
+ * }));
+ * ```
+ */
+
+import { CSEG_GLOBAL, CSEG_PARAM } from "./cdnSegment";
+
+function publishedMarker(): string | null {
+  if (typeof window === "undefined") return null;
+  const v = (window as unknown as Record<string, unknown>)[CSEG_GLOBAL];
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+/**
+ * Drop-in `serverFns.fetch`. Falls back to a plain `fetch` whenever there is no
+ * marker to echo — no marker simply means the response stays uncached in front
+ * of the Worker, which is the previous behaviour.
+ */
+export const decoServerFnFetch: typeof fetch = (input, init) => {
+  // TanStack's serverFnFetcher always calls with the URL already built as a
+  // string (start-client-core/src/client-rpc/serverFnFetcher.ts). Anything else
+  // goes through untouched.
+  if (typeof input !== "string") return fetch(input, init);
+  const marker = publishedMarker();
+  if (!marker) return fetch(input, init);
+  const sep = input.includes("?") ? "&" : "?";
+  return fetch(`${input}${sep}${CSEG_PARAM}=${encodeURIComponent(marker)}`, init);
+};

package/src/sdk/speculationRules.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildSpeculationRules,
+  DEFAULT_EXCLUDED_HREF_MATCHES,
+  getSpeculationRules,
+  setSpeculationRules,
+} from "./speculationRules";
+
+describe("buildSpeculationRules", () => {
+  it("defaults to prerender + moderate + document-wide, with safe exclusions", () => {
+    const rule = JSON.parse(buildSpeculationRules());
+    expect(rule.prerender).toHaveLength(1);
+    const entry = rule.prerender[0];
+    expect(entry.eagerness).toBe("moderate");
+    // first condition targets all internal links; rest are exclusions
+    expect(entry.where.and[0]).toEqual({ href_matches: "/*" });
+    const excluded = entry.where.and
+      .filter((c: { not?: { href_matches: string } }) => c.not)
+      .map((c: { not: { href_matches: string } }) => c.not.href_matches);
+    expect(excluded).toEqual([...DEFAULT_EXCLUDED_HREF_MATCHES]);
+  });
+
+  it("scopes to a link selector when given (excludes client-routed links)", () => {
+    const rule = JSON.parse(
+      buildSpeculationRules({ linkSelector: "[data-prerender] a[href]" }),
+    );
+    expect(rule.prerender[0].where.and[0]).toEqual({
+      selector_matches: "[data-prerender] a[href]",
+    });
+  });
+
+  it("merges extra exclusions and honors action/eagerness", () => {
+    const rule = JSON.parse(
+      buildSpeculationRules({
+        action: "prefetch",
+        eagerness: "conservative",
+        excludeHrefMatches: ["/*/p"],
+      }),
+    );
+    expect(rule.prefetch).toBeDefined();
+    expect(rule.prerender).toBeUndefined();
+    expect(rule.prefetch[0].eagerness).toBe("conservative");
+    const excluded = rule.prefetch[0].where.and
+      .filter((c: { not?: unknown }) => c.not)
+      .map((c: { not: { href_matches: string } }) => c.not.href_matches);
+    expect(excluded).toContain("/*/p");
+    expect(excluded).toContain("/checkout*");
+  });
+
+  it("can replace the default exclusions entirely", () => {
+    const rule = JSON.parse(
+      buildSpeculationRules({
+        excludeHrefMatches: ["/only-this*"],
+        overrideDefaultExclusions: true,
+      }),
+    );
+    const excluded = rule.prerender[0].where.and
+      .filter((c: { not?: unknown }) => c.not)
+      .map((c: { not: { href_matches: string } }) => c.not.href_matches);
+    expect(excluded).toEqual(["/only-this*"]);
+  });
+
+  it("emits valid JSON for selectors containing '>'", () => {
+    expect(() =>
+      JSON.parse(buildSpeculationRules({ linkSelector: "nav > a" })),
+    ).not.toThrow();
+  });
+});
+
+describe("speculation rules activation singleton", () => {
+  it("is disabled by default and toggles via set/get", () => {
+    setSpeculationRules(undefined);
+    expect(getSpeculationRules()).toBeUndefined();
+
+    const cfg = { linkSelector: "[data-prerender] a[href]" };
+    setSpeculationRules(cfg);
+    expect(getSpeculationRules()).toBe(cfg);
+
+    setSpeculationRules(undefined);
+    expect(getSpeculationRules()).toBeUndefined();
+  });
+});

package/src/sdk/speculationRules.ts

@@ -0,0 +1,136 @@
+/**
+ * Speculation Rules API helper.
+ *
+ * Builds the JSON for a `<script type="speculationrules">` tag so the browser
+ * prerenders (or prefetches) the next document ahead of a real navigation,
+ * making it feel instant. This only helps *document* navigations — raw `<a>`
+ * links that leave the SPA (mega-menu → category, footer → institutional).
+ * Client-routed `<Link>`s are intercepted by the router and never benefit, so
+ * scope the candidates to the elements that actually do hard navigations via
+ * `linkSelector` (e.g. a header/menu container marked `[data-prerender]`).
+ *
+ * Ships DISABLED: `DecoRootLayout` emits nothing unless a site passes a
+ * `speculationRules` config. Activate per-site only once the site's own
+ * analytics/pixel loaders are prerender-guarded (see ANALYTICS_SCRIPT /
+ * gtmScript in @decocms/blocks/sdk/analytics), otherwise a prerender that
+ * never activates can double-count pageviews.
+ *
+ * @see https://developer.chrome.com/docs/web-platform/prerender-pages
+ */
+
+export type SpeculationAction = "prerender" | "prefetch";
+
+/**
+ * How aggressively the browser speculates:
+ * - `immediate`  — as soon as the rule is seen (use sparingly).
+ * - `eager`      — on the smallest hint of interaction.
+ * - `moderate`   — on hover (~200ms) / pointerdown. Good default for menus.
+ * - `conservative` — on pointerdown only (cheapest; dial down to this if
+ *   speculative server load gets high).
+ */
+export type SpeculationEagerness =
+  | "immediate"
+  | "eager"
+  | "moderate"
+  | "conservative";
+
+export interface SpeculationRulesConfig {
+  /**
+   * `prerender` (instant nav, runs the page's JS in a hidden document — requires
+   * prerender-safe analytics) or `prefetch` (cheaper, fetches the HTML only, no
+   * JS execution). Default: `"prerender"`.
+   */
+  action?: SpeculationAction;
+  /** Default: `"moderate"`. */
+  eagerness?: SpeculationEagerness;
+  /**
+   * CSS selector for candidate anchors. Restricts speculation to hard-navigation
+   * links and excludes client-routed `<Link>`s by construction.
+   * Example: `"[data-prerender] a[href]"`. When omitted, all same-origin
+   * internal links (`/*`) are candidates.
+   */
+  linkSelector?: string;
+  /**
+   * Extra pathname URLPattern strings to exclude, merged with the built-in
+   * stateful/proxy exclusions. Example: `["/*\/p"]` to skip PDPs.
+   */
+  excludeHrefMatches?: string[];
+  /**
+   * Replace the built-in stateful/proxy exclusions instead of extending them.
+   * Only set this if you know none of the default-excluded paths exist.
+   * Default: `false` (keep the safe defaults).
+   */
+  overrideDefaultExclusions?: boolean;
+}
+
+/**
+ * Paths that are unsafe or wasteful to speculatively load: stateful/auth pages
+ * (session side effects) and typical proxied/API routes (uncacheable, fresh-0).
+ * Mirrors the `private` cache profile.
+ */
+export const DEFAULT_EXCLUDED_HREF_MATCHES: readonly string[] = [
+  "/checkout*",
+  "/account*",
+  "/_secure/*",
+  "/login*",
+  "/logout*",
+  "/cart*",
+  "/api/*",
+];
+
+type WhereCondition =
+  | { href_matches: string }
+  | { selector_matches: string }
+  | { not: WhereCondition }
+  | { and: WhereCondition[] };
+
+/**
+ * Builds the JSON string for a `<script type="speculationrules">` tag from a
+ * typed config. Safe stateful/proxy exclusions are baked in by default.
+ */
+export function buildSpeculationRules(config: SpeculationRulesConfig = {}): string {
+  const {
+    action = "prerender",
+    eagerness = "moderate",
+    linkSelector,
+    excludeHrefMatches = [],
+    overrideDefaultExclusions = false,
+  } = config;
+
+  const exclusions = overrideDefaultExclusions
+    ? excludeHrefMatches
+    : [...DEFAULT_EXCLUDED_HREF_MATCHES, ...excludeHrefMatches];
+
+  const conditions: WhereCondition[] = [
+    linkSelector
+      ? { selector_matches: linkSelector }
+      : { href_matches: "/*" },
+    ...exclusions.map((href) => ({ not: { href_matches: href } } as WhereCondition)),
+  ];
+
+  return JSON.stringify({
+    [action]: [{ where: { and: conditions }, eagerness }],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Site-level activation (module singleton)
+//
+// Set once at worker init via `createDecoWorkerEntry({ speculationRules })` —
+// same lifecycle and isolate as setRenderShell — and read at SSR render time by
+// DecoRootLayout. This is why activation lives in the worker-entry options
+// (like `asJson` / `renderJson`) while the tag is still rendered in the HTML
+// (cache-safe) instead of injected at the edge. Ships DISABLED (undefined).
+// ---------------------------------------------------------------------------
+
+let activeConfig: SpeculationRulesConfig | undefined;
+
+/** Enable Speculation Rules site-wide. Called by createDecoWorkerEntry. */
+export function setSpeculationRules(config: SpeculationRulesConfig | undefined): void {
+  activeConfig = config;
+}
+
+/** Current site-wide Speculation Rules config, or undefined when disabled. */
+export function getSpeculationRules(): SpeculationRulesConfig | undefined {
+  return activeConfig;
+}

package/src/sdk/startEntry.ts

@@ -0,0 +1,31 @@
+/**
+ * Default TanStack Start entry, supplied by the framework when a site doesn't
+ * have its own `src/start.ts`.
+ *
+ * It exists so that CDN caching of `/_serverFn` is something a site gets from a
+ * version bump instead of a per-site PR. The only thing it wires is
+ * `decoServerFnFetch`, which appends the cache segment to server-function URLs
+ * — see `./cdnSegment` for why that is what makes the CDN key match the
+ * Worker's.
+ *
+ * A site that declares its own `src/start.ts` keeps it: `decoVitePlugin` only
+ * aliases this module in when that file is absent. Such a site opts into the
+ * CDN behaviour by composing `decoServerFnFetch` itself:
+ *
+ * ```ts
+ * import { decoServerFnFetch } from "@decocms/tanstack/sdk/serverFnFetch";
+ * export const startInstance = createStart(() => ({
+ *   serverFns: { fetch: decoServerFnFetch },
+ * }));
+ * ```
+ *
+ * The export name is load-bearing: `@tanstack/start-client-core`'s
+ * `hydrateStart` does `import { startInstance } from "#tanstack-start-entry"`.
+ */
+
+import { createStart } from "@tanstack/react-start";
+import { decoServerFnFetch } from "./serverFnFetch";
+
+export const startInstance = createStart(() => ({
+  serverFns: { fetch: decoServerFnFetch },
+}));

package/src/sdk/workerEntry.cacheStorage.test.ts

@@ -0,0 +1,147 @@
+// @vitest-environment node
+
+import { setBlocks } from "@decocms/blocks/cms";
+import { clearLoaderCache, createCachedLoader } from "@decocms/blocks/sdk/cachedLoader";
+import {
+  type CacheKVNamespace,
+  createKVCacheStorage,
+  getCacheStorageContext,
+} from "@decocms/blocks/sdk/cacheStorage";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createDecoWorkerEntry } from "./workerEntry";
+
+function makeKV(): CacheKVNamespace {
+  const values = new Map<string, string>();
+  return {
+    get: async (key) => values.get(key) ?? null,
+    put: async (key, value) => {
+      values.set(key, value);
+    },
+    delete: async (key) => {
+      values.delete(key);
+    },
+  };
+}
+const jobs: Promise<unknown>[] = [];
+const ctx = { waitUntil: (work: Promise<unknown>) => jobs.push(work), passThroughOnException() {} };
+async function flush() {
+  while (jobs.length) await Promise.all(jobs.splice(0));
+}
+const request = (path = "/", headers: Record<string, string> = {}) =>
+  new Request(`https://shop.test${path}`, {
+    headers: { accept: "text/html", ...headers },
+  });
+const env = () => ({ CACHE: makeKV(), BUILD_HASH: "build-A", PURGE_TOKEN: "test-token" });
+const options = {
+  observability: false as const,
+  outboundUserAgent: false as const,
+  geoCacheKey: "off" as const,
+  buildSegment: (req: Request) => ({
+    device: "desktop" as const,
+    loggedIn: req.headers.has("authorization"),
+  }),
+  cacheStorage: (bindings: Record<string, unknown>) =>
+    createKVCacheStorage(bindings.CACHE as CacheKVNamespace),
+};
+beforeEach(() => {
+  clearLoaderCache();
+  setBlocks({});
+});
+
+describe("worker cache storage injection", () => {
+  it("uses the injected KV for HTML, with no global Cache API, across worker instances", async () => {
+    const origin = {
+      fetch: vi.fn(async () => new Response("page", { headers: { "content-type": "text/html" } })),
+    };
+    const bindings = env();
+    const first = createDecoWorkerEntry(origin, options);
+    expect((await first.fetch(request(), bindings, ctx)).headers.get("x-cache")).toBe("MISS");
+    await flush();
+    const second = createDecoWorkerEntry(origin, options);
+    const hit = await second.fetch(request(), bindings, ctx);
+    expect(hit.headers.get("x-cache")).toBe("HIT");
+    expect(await hit.text()).toBe("page");
+    expect(origin.fetch).toHaveBeenCalledTimes(1);
+    const changed = await second.fetch(request(), { ...bindings, BUILD_HASH: "build-B" }, ctx);
+    expect(changed.headers.get("x-cache")).toBe("MISS");
+    await flush();
+  });
+
+  it("uses the same adapter for loader results and isolates authenticated requests", async () => {
+    const upstream = vi.fn(async () => ({ n: upstream.mock.calls.length }));
+    const loader = createCachedLoader("worker-cache-test", upstream, {
+      policy: "no-cache",
+      maxAge: 60_000,
+    });
+    const origin = {
+      fetch: vi.fn(async () => {
+        expect(getCacheStorageContext()).toBeDefined();
+        return Response.json(await loader({}), { headers: { "cache-control": "no-store" } });
+      }),
+    };
+    const worker = createDecoWorkerEntry(origin, options);
+    const bindings = env();
+    await worker.fetch(request("/one"), bindings, ctx);
+    await flush();
+    clearLoaderCache();
+    await worker.fetch(request("/two"), bindings, ctx);
+    expect(upstream).toHaveBeenCalledTimes(1);
+    await worker.fetch(request("/two", { authorization: "Bearer private" }), bindings, ctx);
+    expect(upstream).toHaveBeenCalledTimes(2);
+    await flush();
+  });
+
+  it("stores public server-function POSTs by body and excludes unmarked responses", async () => {
+    const origin = {
+      fetch: vi.fn(
+        async (req: Request) =>
+          new Response(await req.text(), {
+            headers: { "X-Deco-Cacheable": "true", "content-type": "application/json" },
+          }),
+      ),
+    };
+    const worker = createDecoWorkerEntry(origin, options);
+    const bindings = env();
+    const post = (body: string) =>
+      new Request("https://shop.test/_serverFn/public", { method: "POST", body });
+    expect((await worker.fetch(post('"first"'), bindings, ctx)).headers.get("x-cache")).toBe(
+      "MISS",
+    );
+    await flush();
+    const hit = await worker.fetch(post('"first"'), bindings, ctx);
+    expect(hit.headers.get("x-cache")).toBe("HIT");
+    expect(await hit.text()).toBe('"first"');
+    expect((await worker.fetch(post('"second"'), bindings, ctx)).headers.get("x-cache")).toBe(
+      "MISS",
+    );
+    await flush();
+    expect(origin.fetch).toHaveBeenCalledTimes(2);
+    const unmarked = createDecoWorkerEntry({ fetch: async () => new Response("private") }, options);
+    expect((await unmarked.fetch(post('"third"'), bindings, ctx)).headers.get("x-cache")).toBe(
+      "BYPASS",
+    );
+  });
+
+  it("purges HTML through the configured adapter", async () => {
+    const worker = createDecoWorkerEntry(
+      { fetch: async () => new Response("page", { headers: { "content-type": "text/html" } }) },
+      options,
+    );
+    const bindings = env();
+    await worker.fetch(request(), bindings, ctx);
+    await flush();
+    expect((await worker.fetch(request(), bindings, ctx)).headers.get("x-cache")).toBe("HIT");
+    const purge = await worker.fetch(
+      new Request("https://shop.test/_cache/purge", {
+        method: "POST",
+        headers: { authorization: "Bearer test-token" },
+        body: JSON.stringify({ paths: ["/"] }),
+      }),
+      bindings,
+      ctx,
+    );
+    expect(purge.status).toBe(200);
+    expect((await worker.fetch(request(), bindings, ctx)).headers.get("x-cache")).toBe("MISS");
+    await flush();
+  });
+});