@rangojs/router 0.17.0 → 0.19.0

package/src/testing/serve-shell-request.ts

@@ -0,0 +1,381 @@
+/**
+ * serveShellRequest — one request through the production PPR serve path.
+ *
+ * Builds the router's request handler as `router.fetch` does
+ * (`createRSCHandler` with the router's `nonce`, `version` and `cache`
+ * config) and serves one GET through it, so middleware, the shell serve path
+ * and a MISS's background capture all run production code, on real Flight
+ * (the vendored react-server-dom serializer). The call settles every
+ * background task the request scheduled before it returns, so a MISS's
+ * `putShell` has landed.
+ *
+ * The one stub is the SSR module (the HTML step): `react-dom/server` refuses
+ * to load under the react-server condition this project runs with.
+ * - `renderHTML` passes the Flight stream through: a document body is its
+ *   Flight payload.
+ * - `captureShellHTML` returns, as the prelude, the Flight text the capture
+ *   rendered before `quiesce` (plus the post-quiesce task hops the real
+ *   capture takes). `postponed` is always null. A capture that does not
+ *   quiesce within what `ppr.captureTimeout` leaves after the handler output
+ *   settled returns no shell; the real one goes on to its abort and returns
+ *   whatever prelude rendered by then.
+ * - `resumeShellHTML` passes the tail's Flight stream through: a HIT body is
+ *   the stored prelude followed by the tail's Flight payload.
+ * So there is no HTML: the prelude's `<body` sanity gate, SSR render errors
+ * (production refuses the capture on one), fizz resume of the holes,
+ * bootstrap scripts and nonce injection stay e2e-only. A route whose real
+ * capture refuses for a root postpone (a live loader read with no boundary
+ * above it) or an SSR render error is captured here.
+ *
+ * Must run under the `react-server` condition (the rsc Vitest project), with
+ * `rangoTestAliases()` resolving `@vitejs/plugin-rsc/rsc/server` to the stub
+ * that carries the Flight runtime.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { toInternal, type Rango } from "../router/router-interfaces.js";
+import { ensureRouterManifest } from "../route-map-builder.js";
+import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import type { ExecutionContext } from "../types/request-scope.js";
+import type { HandlerCacheConfig, SSRModule } from "../rsc/types.js";
+import type { createRSCHandler } from "../rsc/handler.js";
+import {
+  POST_QUIESCE_TASK_HOPS,
+  SHELL_CAPTURE_MAX_WAIT_MS,
+} from "../rsc/shell-capture-constants.js";
+import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../segment-fragments.js";
+import { _getRequestContext } from "../server/request-context.js";
+import {
+  parsePprReplayStatus,
+  parseShellStatus,
+  shellCacheKey,
+  type PprReplayStatus,
+  type ShellStatus,
+} from "./shell-status.js";
+
+/** Options for {@link serveShellRequest}. */
+export interface ServeShellRequestOptions<TEnv = any> {
+  /**
+   * The shell and segment store for this request, in place of the router's
+   * `createRouter({ cache })` store. The rest of that config (`enabled`,
+   * `searchParams`) still applies. Omit it to serve through the router's own
+   * store.
+   */
+  cacheStore?: SegmentCacheStore;
+  /** Environment bindings, as `router.fetch(request, { env })` passes them. */
+  env?: TEnv;
+  /**
+   * Request headers. A document request defaults `accept` to `text/html`.
+   */
+  headers?: HeadersInit;
+  /**
+   * Serve the client navigation the browser sends (`?_rsc_partial`) instead
+   * of a document GET: from `from` (default `/`) with `segments` mounted
+   * (default none), advertising fragment passthrough. The replay decision is
+   * `result.replayStatus`.
+   */
+  partial?: true | { from?: string; segments?: readonly string[] };
+}
+
+/** Result of {@link serveShellRequest}. */
+export interface ServeShellRequestResult {
+  /** The handler's Response. Its body is already read: see `body`. */
+  response: Response;
+  /** The response body text. */
+  body: string;
+  /** `x-rango-shell` (`HIT` | `MISS`), or null when the header is absent. */
+  shellStatus: ShellStatus | null;
+  /** `x-rango-ppr-replay` on a partial request, or null. */
+  replayStatus: PprReplayStatus | null;
+  /**
+   * The prelude a HIT served: the capture's Flight text at quiesce (the
+   * shell as captured). Undefined unless `shellStatus` is `HIT`.
+   */
+  prelude: string | undefined;
+  /**
+   * The Flight payload this request rendered: a HIT's tail, a document's
+   * render, or a Flight response. Undefined when no Flight was rendered (a
+   * redirect or a middleware response).
+   */
+  flight: string | undefined;
+  /**
+   * The shell key production resolved for this request: for a document the
+   * serve path read and captured (a MISS or a HIT), the key it used, request
+   * partition included (a route partitioned by `cache({ key })` or the
+   * store's `keyGenerator`). Otherwise (a route without `ppr`, a request
+   * passed to axis 1 before its key was resolved, a partial request) the
+   * document URL's key without a partition, as `shellCacheKey` builds it.
+   */
+  key: string;
+  /**
+   * Read the document shell entry under `key` from the request's store
+   * (a passive `getShell`), or null. A read, so on a store with a shell memo
+   * (CFCacheStore, VercelCacheStore) it warms the memo like any other read.
+   */
+  readEntry(): Promise<ShellCacheEntry | null>;
+}
+
+type ShellHandler = ReturnType<typeof createRSCHandler>;
+
+/** What one call's cache resolution and SSR step saw. */
+interface Recorder {
+  cache?: HandlerCacheConfig;
+  /** The shell key the serve path resolved (RequestContext._shellKey). */
+  shellKey?: string;
+  /** A document render reached the HTML step. */
+  rendered?: boolean;
+  /** The HIT tail's Flight text. */
+  tail?: string;
+}
+
+const recorders = new AsyncLocalStorage<Recorder>();
+
+function macrotask(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/**
+ * Record the shell key the serve path resolved: every SSR step of a document
+ * the serve path read runs inside its request context (a capture's derived
+ * context inherits it).
+ */
+function recordShellKey(recorder: Recorder | undefined): void {
+  const shellKey = _getRequestContext()?._shellKey;
+  if (recorder && shellKey !== undefined) recorder.shellKey ??= shellKey;
+}
+
+const SSR_STUB: SSRModule = {
+  async renderHTML(rscStream) {
+    const recorder = recorders.getStore();
+    if (recorder) recorder.rendered = true;
+    recordShellKey(recorder);
+    return rscStream;
+  },
+  async captureShellHTML(rscStream, options) {
+    const reader = rscStream.getReader();
+    const decoder = new TextDecoder();
+    let frozen = "";
+    // The capture gate freezes the stream at quiesce without closing it.
+    void (async () => {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        frozen += decoder.decode(value, { stream: true });
+      }
+    })().catch(() => {});
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<false>((resolve) => {
+      timer = setTimeout(
+        () => resolve(false),
+        options.maxWaitMs ?? SHELL_CAPTURE_MAX_WAIT_MS,
+      );
+    });
+    try {
+      const quiet = await Promise.race([
+        options.quiesce.then(() => true as const),
+        deadline,
+      ]);
+      if (!quiet) return null;
+    } finally {
+      clearTimeout(timer);
+    }
+    for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) await macrotask();
+    return { prelude: new TextEncoder().encode(frozen), postponed: null };
+  },
+  async resumeShellHTML(rscStream) {
+    const recorder = recorders.getStore();
+    recordShellKey(recorder);
+    // The served HIT's tail only, not a background re-render's.
+    if (!recorder || recorder.tail !== undefined) return rscStream;
+    recorder.tail = "";
+    const decoder = new TextDecoder();
+    return rscStream.pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          recorder.tail += decoder.decode(chunk, { stream: true });
+          controller.enqueue(chunk);
+        },
+        flush() {
+          recorder.tail += decoder.decode();
+        },
+      }),
+    );
+  },
+};
+
+/** Handlers per router, keyed by the `cacheStore` override or the router. */
+const handlers = new WeakMap<object, WeakMap<object, ShellHandler>>();
+
+async function getHandler(
+  router: Rango<any, any>,
+  cacheStore: SegmentCacheStore | undefined,
+): Promise<ShellHandler> {
+  let byStore = handlers.get(router);
+  if (!byStore) handlers.set(router, (byStore = new WeakMap()));
+  const cached = byStore.get(cacheStore ?? router);
+  if (cached) return cached;
+
+  const internal = toInternal(router);
+  const routerCache = internal.cache;
+  // Resolved per request, as the handler resolves the router's own config.
+  const cache = (env: unknown, ctx?: ExecutionContext): HandlerCacheConfig => {
+    const base =
+      typeof routerCache === "function" ? routerCache(env, ctx) : routerCache;
+    const config = cacheStore ? { ...base, store: cacheStore } : base!;
+    const recorder = recorders.getStore();
+    if (recorder) recorder.cache = config;
+    return config;
+  };
+  const { createRSCHandler } = await import("../rsc/handler.js");
+  const handler = createRSCHandler({
+    router: internal,
+    nonce: internal.nonce,
+    version: internal.version,
+    loadSSRModule: async () => SSR_STUB,
+    cache: routerCache || cacheStore ? cache : undefined,
+  });
+  byStore.set(cacheStore ?? router, handler);
+  return handler;
+}
+
+function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
+  const headers = new Headers(options.headers);
+  const partial = options.partial;
+  if (!partial) {
+    if (!headers.has("accept")) headers.set("accept", "text/html");
+    return new Request(url, { headers });
+  }
+  const { from = "/", segments = [] } = partial === true ? {} : partial;
+  const target = new URL(url);
+  target.searchParams.set("_rsc_partial", "true");
+  target.searchParams.set("_rsc_segments", segments.join(","));
+  if (!headers.has("X-RSC-Router-Client-Path")) {
+    headers.set("X-RSC-Router-Client-Path", new URL(from, url).href);
+  }
+  if (!headers.has(SEGMENT_FRAGMENT_CAPABILITY_HEADER)) {
+    headers.set(SEGMENT_FRAGMENT_CAPABILITY_HEADER, "1");
+  }
+  return new Request(target, { headers });
+}
+
+/**
+ * Reset the per-isolate PPR state requests leave behind, so the next test
+ * starts as a fresh worker would: the capture's stampede guard, its backoff
+ * (a refused capture backs its URL off for later tests too), the shell path's
+ * once-per-key warnings, the build-shell manifest memo, the "use cache"
+ * in-flight leaders and warnings, and CFCacheStore's isolate memos (shells,
+ * tag markers, tag hints) and warnings, which every CFCacheStore in the
+ * process shares by namespace and URL. Call it in `beforeEach`, never while
+ * a request is in flight. VercelCacheStore's memos live on the `cache`
+ * handle it is given: a new handle starts empty.
+ */
+export async function resetShellTestState(): Promise<void> {
+  const [capture, serve, buildShells, cf, cacheRuntime] = await Promise.all([
+    import("../rsc/shell-capture.js"),
+    import("../rsc/shell-serve.js"),
+    import("../rsc/shell-build-manifest.js"),
+    import("../cache/cf/cf-cache-store.js"),
+    import("../cache/cache-runtime.js"),
+  ]);
+  capture.resetShellCaptureStateForTests();
+  serve.resetShellServeStateForTests();
+  buildShells.resetBuildShellManifestForTests();
+  cf.resetCFShellMemoForTests();
+  cacheRuntime.resetCacheRuntimeForTests();
+}
+
+/** Settle background tasks, including ones scheduled while settling. */
+async function settle(tasks: Promise<unknown>[]): Promise<void> {
+  do {
+    while (tasks.length > 0) await Promise.allSettled(tasks.splice(0));
+    await macrotask();
+  } while (tasks.length > 0);
+}
+
+/**
+ * Serve one GET for `url` through the router's production request handler
+ * and settle the background tasks it scheduled (a MISS's capture and
+ * `putShell` included). The first request for a `ppr` route is a MISS; the
+ * next one with the same store is a HIT from the stored shell. The HTML step
+ * is stubbed (see the module header), so `prelude` and `flight` are Flight
+ * text. The request starts in a later millisecond than the call: a store
+ * refuses a capture that starts in the millisecond of a tag invalidation, so
+ * an `updateTag()` made just before the call never refuses its recapture.
+ * Rejects when the handler throws or the response stream errors (a failing
+ * HIT tail), after settling the tasks scheduled so far.
+ *
+ * @example
+ * const store = new MemorySegmentCacheStore();
+ * const miss = await serveShellRequest(router, "/product/1", { cacheStore: store });
+ * expect(miss.shellStatus).toBe("MISS");
+ * const hit = await serveShellRequest(router, "/product/1", { cacheStore: store });
+ * expect(hit.shellStatus).toBe("HIT");
+ * expect(hit.prelude).toContain("Widget"); // captured shell
+ * expect(hit.flight).toContain("in stock"); // live hole, rendered now
+ */
+export async function serveShellRequest<TEnv = any>(
+  router: Rango<TEnv, any>,
+  url: string | URL,
+  options: ServeShellRequestOptions<TEnv> = {},
+): Promise<ServeShellRequestResult> {
+  const called = Date.now();
+  const target = new URL(url, "http://localhost");
+  await ensureRouterManifest(router.id);
+  const handler = await getHandler(router, options.cacheStore);
+  const request = buildRequest(target, options);
+  const tasks: Promise<unknown>[] = [];
+  const executionContext: ExecutionContext = {
+    waitUntil(promise) {
+      tasks.push(
+        Promise.resolve(promise).catch((error) =>
+          console.error("[waitUntil] Background task failed:", error),
+        ),
+      );
+    },
+    passThroughOnException() {},
+  };
+  const recorder: Recorder = {};
+  while (Date.now() === called) await macrotask();
+
+  const { response, body } = await recorders.run(recorder, async () => {
+    try {
+      const response = await handler(request, {
+        env: options.env,
+        ctx: executionContext,
+      });
+      return { response, body: await response.text() };
+    } finally {
+      await settle(tasks);
+    }
+  });
+
+  const config =
+    recorder.cache && recorder.cache.enabled !== false
+      ? recorder.cache
+      : undefined;
+  const key = recorder.shellKey ?? shellCacheKey(target, config?.searchParams);
+  const tail = recorder.tail;
+  const isFlight =
+    recorder.rendered ||
+    response.headers.get("content-type")?.includes("text/x-component");
+  return {
+    response,
+    body,
+    shellStatus: parseShellStatus(response),
+    replayStatus: parsePprReplayStatus(response),
+    prelude:
+      tail !== undefined && body.endsWith(tail)
+        ? body.slice(0, body.length - tail.length)
+        : undefined,
+    flight: tail ?? (isFlight && body ? body : undefined),
+    key,
+    async readEntry() {
+      // Passive, like the serve path's own reads: a stale entry's SWR
+      // revalidation stays unclaimed for the next request.
+      const read = await config?.store.getShell?.(key, {
+        claimRevalidation: false,
+      });
+      return read?.entry ?? null;
+    },
+  };
+}

package/src/testing/shell-status.ts

@@ -18,56 +18,42 @@
  *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
- * 3. **Stays e2e-only:** live MISS → background capture → HIT (needs real
- *    `captureShellHTML` / React `prerender` + resume fizz), browser resume of
- *    holes, Cloudflare/Vercel live stores, nonce/eligibility fall-open, and
- *    build-time producer B bake. Unit layer dogfoods the **store family + key
- *    identity + header assert**; it must never stub a shell HIT response.
+ * 3. **A real MISS → capture → HIT in unit tests:** `serveShellRequest`
+ *    (`@rangojs/router/testing/flight`, serve-shell-request.ts) serves one
+ *    request through the router's production handler and settles its
+ *    background capture; a later request with the same store is a real HIT or
+ *    partial replay. Its only stub is the HTML step (the SSR module).
+ *    **Stays e2e-only:** real HTML (the prelude's `<body` gate, fizz resume of
+ *    holes), browser resume of holes, live Cloudflare/Vercel runtimes (store
+ *    test doubles work in unit), and build-time producer B bake. The unit layer
+ *    must never stub a shell HIT response.
  *
  * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
  * (Playwright — same pure helpers, no Vite virtuals).
  */
 
-import { sortedSearchString } from "../cache/cache-key-utils.js";
+import { composeCacheKeys } from "../cache/cache-key-utils.js";
+import {
+  PPR_REPLAY_BYPASS_REASONS,
+  PPR_REPLAY_STATUS_HEADER,
+  SHELL_STATUS_HEADER,
+  buildShellKey,
+  partitionShellKey,
+  type PprReplayBypassReason,
+} from "../rsc/shell-capture-constants.js";
 import {
   compileSearchParamsFilter,
   type CacheSearchParams,
 } from "../cache/search-params-filter.js";
 
-/** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
-export const SHELL_STATUS_HEADER: string = "x-rango-shell";
-
-/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
-export const PPR_REPLAY_STATUS_HEADER: string = "x-rango-ppr-replay";
+// The production header names and bypass reasons, from the React-free leaf
+// the serve path reads them from.
+export { PPR_REPLAY_STATUS_HEADER, SHELL_STATUS_HEADER };
+export type { PprReplayBypassReason };
 
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
 
-const PPR_REPLAY_BYPASS_REASONS = [
-  "method",
-  "dynamic",
-  "nonce",
-  "store-unavailable",
-  "passive-read-unsupported",
-  "no-navigation-context",
-  "prerender-store",
-  "intercept",
-  "cache-disabled",
-  "read-error",
-  "no-entry",
-  "invalid-version",
-  "corrupt-entry",
-  "handler-live-holes",
-  "transition-when",
-  "no-segment-snapshot",
-  "snapshot-miss",
-  "explicit-cache-hit",
-  "stale-build-entry",
-] as const;
-
-/** Bounded reasons a PPR partial request can fall open to ordinary matching. */
-export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
-
 /** Parsed `x-rango-ppr-replay` value. */
 export type PprReplayStatus =
   | { outcome: "HIT"; freshness: "fresh" | "stale" }
@@ -77,28 +63,68 @@ export type PprReplayStatus =
 export type ShellStatusTarget = Response | { headers: Headers };
 
 /**
- * Shell store key for a document URL — same formula as production
- * `buildShellKey` in `rsc/shell-serve.ts` (host + pathname + sorted search +
- * `:shell`). Kept here so the testing barrel never imports the shell-serve
- * module (it pulls React). A parity test pins the two implementations.
+ * What partitions a ppr route's shell, for {@link shellCacheKey}: the
+ * request's results of the functions that partition the route's cache()
+ * record.
+ */
+export interface ShellCachePartition {
+  /** The route's cache() `key()` results, outermost first. */
+  keys?: readonly string[];
+  /**
+   * Store `keyGenerator` results, one per store, outermost first: an
+   * enclosing cache() on another store's, then the store's of the route's
+   * own cache() when it sets no `key()` (with no route cache(), the app
+   * store's). When every one returns the default key they partition
+   * nothing: leave them out. Otherwise each keeps its position, and one
+   * that returns the default key is `""`.
+   */
+  generated?: readonly string[];
+}
+
+/**
+ * Shell store key for a document URL: the production `buildShellKey` (host +
+ * pathname + sorted search + `:shell`) and `partitionShellKey`, both from the
+ * React-free leaf `rsc/shell-capture-constants.ts`, so the testing barrel never
+ * imports the shell-serve module (it pulls React).
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
  * resolve against `http://localhost`). Pass the router's `cache.searchParams`
  * config as `searchParams` when the app under test sets one — the production
- * key applies it, so the expected key must too.
+ * key applies it, so the expected key must too. When the route's record is
+ * partitioned by the request, its shell is too: pass what partitions it as
+ * `partition`, composed as production composes it (`composeCacheKeys`,
+ * which namespaces each `key()` result):
+ * - its `cache({ key })` result, as a string;
+ * - nested keyed `cache()` scopes' `key()` results, as an array, outermost
+ *   first;
+ * - store `keyGenerator` results, with or without `key()` results, as
+ *   `{ keys, generated }` (see {@link ShellCachePartition}).
  */
 export function shellCacheKey(
   url: URL | string,
   searchParams?: CacheSearchParams,
+  partition?: string | readonly string[] | ShellCachePartition,
 ): string {
   const resolved =
     typeof url === "string" ? new URL(url, "http://localhost") : url;
-  const sorted = sortedSearchString(
-    resolved.searchParams,
-    compileSearchParamsFilter(searchParams),
-  );
-  const searchSuffix = sorted ? `?${sorted}` : "";
-  return `${resolved.host}${resolved.pathname}${searchSuffix}:shell`;
+  const key = buildShellKey(resolved, compileSearchParamsFilter(searchParams));
+  if (partition === undefined) return key;
+  const { keys = [], generated = [] }: ShellCachePartition =
+    typeof partition === "string"
+      ? { keys: [partition] }
+      : isPartitionList(partition)
+        ? { keys: partition }
+        : partition;
+  // Nothing partitions: the key as when `partition` is omitted.
+  return keys.length === 0 && generated.length === 0
+    ? key
+    : partitionShellKey(key, composeCacheKeys(keys, generated));
+}
+
+function isPartitionList(
+  partition: readonly string[] | ShellCachePartition,
+): partition is readonly string[] {
+  return Array.isArray(partition);
 }
 
 function getHeaders(target: ShellStatusTarget): Headers {

package/src/theme/ThemeProvider.tsx

@@ -133,12 +133,13 @@ export function ThemeProvider({
     setSystemTheme(getSystemTheme());
     // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
     // comes from the payload and can legitimately differ from the visitor's
-    // stored theme — on a PPR shell HIT it is deliberately the CAPTURE's theme
-    // (the resume tree must match the frozen prelude; see
-    // ShellCacheEntry.initialTheme). The FOUC script already applied the stored
-    // theme to the document pre-paint; this brings the provider state (toggles,
-    // useTheme readers) in line with it, and is the ONLY place the provider
-    // reads storage (the initializer must not — see the parity note above).
+    // stored theme — on a PPR shell HIT it is deliberately the CAPTURE's
+    // initialTheme, the no-cookie default (the resume tree must match the
+    // frozen prelude; see ShellCacheEntry.initialTheme). The FOUC script
+    // already applied the stored theme to the document pre-paint; this brings
+    // the provider state (toggles, useTheme readers) in line with it, and is
+    // the ONLY place the provider reads storage (the initializer must not —
+    // see the parity note above).
     // Only an explicit cookie/localStorage value re-syncs — a defaultTheme
     // fallback must not override a server-provided initialTheme when the
     // visitor never chose a theme.