@rangojs/router 0.16.0 → 0.18.0

package/src/rsc/shell-serve.ts

@@ -20,9 +20,15 @@ import React from "react";
 import { isPprEntry, type EntryData } from "../server/context.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
+import { base64ToBytes } from "../cache/cf/cf-base64.js";
+import { getNonceAttribute } from "../theme/theme-script.js";
 import type {
   DocumentShellCacheEntry,
   ShellCacheEntry,
+  ShellDocumentRead,
+  ShellReadStats,
+  ShellSnapshotFailure,
+  ShellSnapshotRecord,
   SegmentCacheStore,
 } from "../cache/types.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
@@ -132,6 +138,66 @@ export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
   return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
 }
 
+export {
+  navigationShellKey,
+  partitionShellKey,
+} from "./shell-capture-constants.js";
+
+/**
+ * The forced-MISS query marker. A document HIT that cannot finish its tail
+ * reloads the page with it (shellReloadScript); the serve gate renders a
+ * request carrying it on axis 1, with no shell read and no capture, so the
+ * reload can never be a HIT that degrades again. The handler drops it from
+ * the request on entry (withoutShellMissMarker) and keeps only the flag
+ * (RequestContext._shellForcedMiss), so nothing else sees it.
+ */
+export const SHELL_MISS_PARAM: string = "_rsc_shell";
+
+/**
+ * The request without the forced-MISS marker, or undefined when it carries
+ * none. The handler calls it before anything reads the request: left in, the
+ * marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
+ * search seed (so `useSearchParams` rendered it), and a `"use cache"` key
+ * built from the request URL was never read again. GET and HEAD only: the
+ * reload is a navigation, and a request with a body cannot be re-created
+ * without re-streaming it. The substring test keeps the URL parse off every
+ * other request.
+ */
+export function withoutShellMissMarker(request: Request): Request | undefined {
+  if (!request.url.includes(SHELL_MISS_PARAM)) return undefined;
+  if (request.method !== "GET" && request.method !== "HEAD") return undefined;
+  const url = new URL(request.url);
+  if (!url.searchParams.has(SHELL_MISS_PARAM)) return undefined;
+  url.searchParams.delete(SHELL_MISS_PARAM);
+  return new Request(url, request);
+}
+
+/**
+ * The inline script a degraded document HIT ends with: reload once into a
+ * forced MISS. The marker in the URL is the loop bound — a request carrying
+ * it is never a HIT, so this script never runs on the reload, and if it ever
+ * did (a server that ignores the marker) it would return without touching
+ * the page. window.stop() runs only when it reloads: it keeps the half-sent
+ * Flight stream from being closed by DOMContentLoaded, which would throw
+ * React's "Connection closed" (#412) before the reload lands. `nonce` is the
+ * request's CSP nonce; a ppr route with an active nonce is axis 1
+ * (rsc-rendering.ts shellServePlan), so on a HIT it is normally absent.
+ */
+export function shellReloadScript(nonce?: string): string {
+  return inlineShellScript(
+    "(function(){var u=new URL(location.href);" +
+      `if(u.searchParams.has(${JSON.stringify(SHELL_MISS_PARAM)}))return;` +
+      `u.searchParams.set(${JSON.stringify(SHELL_MISS_PARAM)},"miss");` +
+      "try{window.stop()}catch(e){}location.replace(u.href)})()",
+    nonce,
+  );
+}
+
+/** An inline script a shell HIT's tail appends, carrying the CSP nonce if any. */
+export function inlineShellScript(body: string, nonce?: string): string {
+  return `<script${getNonceAttribute(nonce)}>${body}</script>`;
+}
+
 /**
  * The shell key's search portion (`?`-prefixed sorted search with the
  * cache.searchParams filter applied, or "") — ALSO the string the capture and
@@ -166,17 +232,25 @@ export function isValidShellHit(
   );
 }
 
+/** The postponed blob is stored and parses (null is the DATA variant). */
+function hasParseablePostponed(
+  entry: ShellCacheEntry,
+): entry is ShellCacheEntry & { postponed: string | null } {
+  if (entry.postponed === undefined) return false;
+  try {
+    if (entry.postponed !== null) JSON.parse(entry.postponed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
- * DOCUMENT-half integrity gate and type narrowing, run BEFORE the HIT response
- * commits: a stored entry whose prelude is not decodable base64 or whose
- * postponed blob is not parseable JSON would otherwise throw AFTER the 200 +
- * full static prelude flushed (`serveShellHit` decodes at stream construction,
- * `resumeShellHTML` parses in the tail) — the client gets a visually complete
- * page that never hydrates, re-served on every request until the entry ages
- * out (no eviction path exists; failure schedules no recapture by itself).
- * Checking here turns a corrupt entry (store-layer fault) into a plain MISS
- * the recapture overwrites. Cost: one duplicate decode/parse per HIT, sub-ms
- * against a prelude flush that dominates the path.
+ * DOCUMENT-half structural gate and type narrowing, without decoding the
+ * prelude: the prelude is a string and the postponed blob parses. Partial
+ * replay (which never serves the prelude) and the build-manifest read-through
+ * use it as-is; the document HIT path runs it inside
+ * {@link openShellDocument}, whose single decode is the prelude's check.
  *
  * navigationOnly entries store no document half (prelude/postponed absent) and
  * therefore never pass. The partial-replay path skips this gate for them
@@ -187,25 +261,85 @@ export function isValidShellHit(
 export function hasIntactShellPayload(
   entry: ShellCacheEntry,
 ): entry is DocumentShellCacheEntry {
-  if (typeof entry.prelude !== "string" || entry.postponed === undefined) {
-    return false;
+  return typeof entry.prelude === "string" && hasParseablePostponed(entry);
+}
+
+/** A document shell ready to serve: its prelude decoded exactly once. */
+export interface ShellDocument {
+  entry: ShellCacheEntry;
+  prelude: Uint8Array;
+  /** React's postponed state, parse-checked (null = DATA variant). */
+  postponed: string | null;
+  /**
+   * The capture snapshot: on the entry, or still arriving on its own promise
+   * after a prelude-first read (SegmentCacheStore.readShellDocument), which
+   * only the tail awaits.
+   */
+  snapshot:
+    | ShellSnapshotRecord[]
+    | undefined
+    | Promise<ShellSnapshotRecord[] | undefined>;
+  /** Why a prelude-first read's snapshot is missing (ShellDocumentRead). */
+  snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
+  /** The prelude-first read's stats, when perf metrics are on. */
+  stats?: ShellReadStats;
+}
+
+/**
+ * Pre-commit integrity gate for a document HIT, and its only prelude decode.
+ * A stored entry whose prelude is not decodable base64 or whose postponed blob
+ * is not parseable JSON would otherwise throw AFTER the 200 + full static
+ * prelude flushed (`resumeShellHTML` parses in the tail) — the client gets a
+ * visually complete page that never hydrates, re-served on every request
+ * until the entry ages out. Returning null here turns a corrupt entry
+ * (store-layer fault) into a plain MISS the recapture overwrites. The decoded
+ * bytes are what serveShellHit enqueues, so the check costs no second decode.
+ * A prelude-first `read` (SegmentCacheStore.readShellDocument) already carries
+ * the raw bytes and a pending snapshot, so only its postponed blob is checked.
+ */
+export function openShellDocument(
+  entry: ShellCacheEntry,
+  read?: Pick<
+    ShellDocumentRead,
+    "prelude" | "snapshot" | "snapshotFailure" | "stats"
+  >,
+): ShellDocument | null {
+  if (read) {
+    if (!hasParseablePostponed(entry)) return null;
+    return {
+      entry,
+      postponed: entry.postponed,
+      prelude: read.prelude,
+      snapshot: read.snapshot,
+      ...(read.snapshotFailure && { snapshotFailure: read.snapshotFailure }),
+      ...(read.stats && { stats: read.stats }),
+    };
   }
+  if (!hasIntactShellPayload(entry)) return null;
+  let prelude: Uint8Array;
   try {
-    base64ToBytes(entry.prelude);
-    if (entry.postponed !== null) JSON.parse(entry.postponed);
-    return true;
+    prelude = base64ToBytes(entry.prelude);
   } catch {
-    return false;
+    return null;
   }
+  return {
+    entry,
+    postponed: entry.postponed,
+    prelude,
+    snapshot: entry.snapshot,
+  };
 }
 
-/** Decode a base64 prelude back into bytes for stream composition. */
-export function base64ToBytes(b64: string): Uint8Array {
-  const binary = atob(b64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
+/**
+ * Prelude enqueue granularity. A streaming compressor in front of the worker
+ * emits its first byte only after compressing the whole write it was handed:
+ * one 629 KB enqueue delayed the first compressed byte by the full prelude's
+ * compression time (brotli-6 5.1 ms, gzip-6 1.1 ms in Node zlib with a flush
+ * per write; workerd's CompressionStream emits nothing until the whole write is
+ * compressed), while 32 KB chunks emit within 0.1 ms and cost slightly more
+ * in total compression (0.55-0.70 ms) than one write (issue #941).
+ */
+export const SHELL_PRELUDE_CHUNK_BYTES: number = 32 * 1024;
 
 /** True when the store implements the shell entry family. */
 export function hasShellFamily(
@@ -227,8 +361,22 @@ export function hasShellFamily(
 export interface ShellTailTiming {
   key: string;
   outcome: "complete" | "redirect" | "error";
+  /** The capture snapshot available to the tail (read and parsed). */
+  snapshotMs?: number;
+  /** Snapshot bytes read after the commit (prelude-first stores). */
+  snapshotBytes?: number;
+  /** Snapshot bytes read after the commit, excluding the parse. */
+  snapshotReadMs?: number;
+  /** Snapshot JSON.parse CPU (reads 0 on a deployed worker: see bytes). */
+  snapshotParseMs?: number;
+  /** Snapshot records by family, e.g. `segment:1/item:5` (no commas: it rides a Server-Timing desc). */
+  snapshotRecords?: string;
+  /** Records the capture pruned from the snapshot, same format (ShellCacheEntry.prunedRecords). */
+  snapshotPruned?: string;
   /** Loader-family seed decode (only when the entry carried a snapshot). */
   seedMs?: number;
+  /** The seed decode's own duration: Flight deserialization, CPU only. */
+  seedCpuMs?: number;
   /** Tail router.match() settled. */
   matchMs?: number;
   /** Tail stream (resume output) handed to the response stream. */
@@ -244,13 +392,35 @@ export interface ShellTailTiming {
 }
 
 /**
- * Compact single-line form for the console log and the dev Server-Timing
- * mirror's `desc`. Plain alphanumerics/`=`/`-` only — no quoted-string
- * escaping needed.
+ * Compact single-line form for the console log and the Server-Timing mirror's
+ * `desc`: alphanumerics and `=`, `-`, `:`, `/` only (records=segment:1 pruned=item:5),
+ * so no quoted-string escaping is needed. Offsets are from the commit; the
+ * `-cpu` fields are CPU-only durations.
  */
 export function describeShellTailTiming(timing: ShellTailTiming): string {
   const parts: string[] = [timing.outcome];
+  if (timing.snapshotMs !== undefined) {
+    parts.push(`snapshot=${timing.snapshotMs}ms`);
+  }
+  if (timing.snapshotReadMs !== undefined) {
+    parts.push(`snapshot-read=${timing.snapshotReadMs}ms`);
+  }
+  if (timing.snapshotBytes !== undefined) {
+    parts.push(`snapshot-bytes=${timing.snapshotBytes}b`);
+  }
+  if (timing.snapshotParseMs !== undefined) {
+    parts.push(`snapshot-parse-cpu=${timing.snapshotParseMs}ms`);
+  }
+  if (timing.snapshotRecords !== undefined) {
+    parts.push(`records=${timing.snapshotRecords}`);
+  }
+  if (timing.snapshotPruned !== undefined) {
+    parts.push(`pruned=${timing.snapshotPruned}`);
+  }
   if (timing.seedMs !== undefined) parts.push(`seed=${timing.seedMs}ms`);
+  if (timing.seedCpuMs !== undefined) {
+    parts.push(`seed-cpu=${timing.seedCpuMs}ms`);
+  }
   if (timing.matchMs !== undefined) parts.push(`match=${timing.matchMs}ms`);
   if (timing.handoverMs !== undefined) {
     parts.push(`handover=${timing.handoverMs}ms`);
@@ -269,19 +439,19 @@ export function describeShellTailTiming(timing: ShellTailTiming): string {
 }
 
 /**
- * Dev-only last-tail-per-key buffer backing the `ppr:tail` Server-Timing
- * mirror: a HIT's tail finishes after its own headers are long gone, so its
- * per-stage numbers ride the NEXT ppr GET for the key when the metrics
- * surface is active (debugPerformance). Same shape and FIFO cap as the
- * capture mirror (shell-capture.ts lastCaptureEventsForTiming); dev-only so
- * production isolates never grow the map.
+ * Last-tail-per-key buffer backing the `ppr:tail` Server-Timing mirror: a
+ * HIT's tail finishes after its own headers are long gone, so its per-stage
+ * numbers ride the NEXT ppr GET for the key when the metrics surface is
+ * active (debugPerformance). Same shape and FIFO cap as the capture mirror
+ * (shell-capture.ts lastCaptureEventsForTiming). serveShellHit collects and
+ * publishes a timing only in dev or when the HIT itself collected metrics, so
+ * a production isolate without debugPerformance never grows the map.
  */
 const lastTailTimingsForServerTiming = new Map<string, ShellTailTiming>();
 const MAX_TAIL_TIMING_KEYS = 100;
 
-/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+/** Buffer one terminal tail timing for the Server-Timing mirror. */
 export function publishShellTailTiming(timing: ShellTailTiming): void {
-  if (process.env.NODE_ENV === "production") return;
   lastTailTimingsForServerTiming.delete(timing.key);
   if (lastTailTimingsForServerTiming.size >= MAX_TAIL_TIMING_KEYS) {
     const oldest = lastTailTimingsForServerTiming.keys().next().value;
@@ -348,3 +518,115 @@ export function warnPprNonceActiveOnce(key: string): void {
       "ppr option on this route, or stop setting a per-request nonce for it.",
   );
 }
+
+/** Routes already warned about a ppr window the route cache() caps. */
+const warnedPprWindowCapped = new Set<string>();
+
+/**
+ * Dev only (the caller gates on NODE_ENV): warn once per route that the
+ * route's cache() entry reduces an explicit `ppr.ttl` or `ppr.swr`. `shell`
+ * is what the capture stores for a record written just now
+ * (shell-capture.ts capShellWindow), so the message states the values the
+ * shell actually gets. A ppr value the cap leaves whole (or raises: the
+ * cap can move a record's stale time into the shell's swr) is silent, and
+ * so is a ppr config that sets no ttl/swr.
+ */
+export function warnPprWindowCappedOnce(
+  routeName: string,
+  ppr: { ttl?: number; swr?: number },
+  shell: { ttl: number; swr: number },
+  cache: { ttl: number; swr: number },
+): void {
+  if (warnedPprWindowCapped.has(routeName)) return;
+  const reduced: string[] = [];
+  for (const field of ["ttl", "swr"] as const) {
+    const own = ppr[field];
+    if (own !== undefined && shell[field] < own) {
+      reduced.push(`ppr.${field} ${own}`);
+    }
+  }
+  if (reduced.length === 0) return;
+  warnedPprWindowCapped.add(routeName);
+  console.warn(
+    `[rango] Route "${routeName}": its shell is stored with ttl ${shell.ttl} ` +
+      `and swr ${shell.swr}, below its ${reduced.join(" and ")}. A shell ` +
+      `never outlives the route cache() entry (ttl ${cache.ttl}, swr ` +
+      `${cache.swr}) it was captured from, so a document request and a ` +
+      "client navigation show the same handler output. Keep ppr.ttl within " +
+      "the cache() ttl, and ppr.ttl + ppr.swr within the cache() ttl + swr, " +
+      "to silence this.",
+  );
+}
+
+/** Routes (or paths) already warned that a partition skips their build shell. */
+const partitionBuildShellWarned = new Set<string>();
+
+/**
+ * Paths a partitioned request found without a build shell. Build shells are
+ * per path (a param route prerenders some of its paths), so a negative is
+ * kept per path, not per route; cleared when full, so it stays bounded.
+ */
+const pathsWithoutBuildShell = new Set<string>();
+const PATHS_WITHOUT_BUILD_SHELL_MAX = 1_000;
+
+/**
+ * Whether a partitioned request needs no build-shell probe: its route was
+ * already warned, or its path was already found without one.
+ */
+export function partitionBuildShellCheckDone(
+  pathname: string,
+  routeName: string | undefined,
+): boolean {
+  return (
+    partitionBuildShellWarned.has(routeName ?? pathname) ||
+    pathsWithoutBuildShell.has(pathname)
+  );
+}
+
+/**
+ * Record a partitioned request's build-shell probe, and warn once per route
+ * when it found one: the route has a build-time shell its requests cannot
+ * read. The route's request partition (a `cache({ key })` enclosing it, at
+ * any depth (#970), or the store's keyGenerator) keys the shell per
+ * partition, and the build captured only
+ * the default one, so each partition captures at runtime. Same
+ * declared-intent-cannot-be-honored doctrine as the warnings above; a path
+ * with no build shell stays silent.
+ */
+export function notePartitionBuildShellCheck(
+  pathname: string,
+  routeName: string | undefined,
+  found: boolean,
+): void {
+  if (!found) {
+    if (pathsWithoutBuildShell.size >= PATHS_WITHOUT_BUILD_SHELL_MAX) {
+      pathsWithoutBuildShell.clear();
+    }
+    pathsWithoutBuildShell.add(pathname);
+    return;
+  }
+  // Concurrent first requests can both probe; one of them warns.
+  const route = routeName ?? pathname;
+  if (partitionBuildShellWarned.has(route)) return;
+  partitionBuildShellWarned.add(route);
+  console.warn(
+    `[rango] Route ${routeName ? `"${routeName}" ` : ""}("${pathname}") has a ` +
+      "build-time shell, but its request partition (a cache({ key }) enclosing the route, " +
+      "or the store's keyGenerator) keys its shell per partition, so the build " +
+      "shell is not served and each partition captures its own at runtime. A " +
+      "keyGenerator that returns the default key unchanged keeps the build shell.",
+  );
+}
+
+/**
+ * @internal Reset the serve path's once-per-key warnings and buffered tail
+ * timings. Tests only (testing/serve-shell-request.ts resetShellTestState).
+ */
+export function resetShellServeStateForTests(): void {
+  warnedMissingStore.clear();
+  warnedNonceActive.clear();
+  partitionBuildShellWarned.clear();
+  pathsWithoutBuildShell.clear();
+  warnedPprWindowCapped.clear();
+  lastTailTimingsForServerTiming.clear();
+}

package/src/rsc/ssr-setup.ts

@@ -82,11 +82,11 @@ export interface SsrHtmlStageOptions<TEnv> {
   /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
   metricsStore: MetricsStore | undefined;
   /**
-   * renderHTML options minus streamMode (the stage resolves streamMode). Carries
-   * the per-site nonce and, for the PE action re-render, formState. Spread
-   * verbatim so each call site's exact key set is preserved.
+   * renderHTML options minus streamMode and onError (the stage owns both).
+   * Carries the per-site nonce and, for the PE action re-render, formState.
+   * Spread verbatim so each call site's exact key set is preserved.
    */
-  render: Omit<SSRRenderOptions, "streamMode">;
+  render: Omit<SSRRenderOptions, "streamMode" | "onError">;
   /** ResponseInit merged into the prepared render (e.g. content-type). */
   init?: ResponseInit;
 }
@@ -109,6 +109,7 @@ export function createSsrHtmlStage<TEnv>(
       options.url,
       options.metricsStore,
     );
+    const renderErrors = _getRequestContext()?._renderErrors;
     return {
       render: () =>
         // search: the LIVE request's query string, threaded out-of-band into
@@ -124,6 +125,12 @@ export function createSsrHtmlStage<TEnv>(
           // so origin-dependent markup (Link's data-external) agrees with the
           // browser's window.location across hydration.
           origin: options.url.origin,
+          // A component that throws inside a Suspense boundary leaves an
+          // errored boundary in a completed document; the document cache
+          // reads the list before storing it.
+          onError: (error) => {
+            renderErrors?.push(error);
+          },
         }),
       ...(options.init && { init: options.init }),
     };
@@ -185,8 +192,8 @@ function acceptsFlightExplicitly(request: Request, url: URL): boolean {
  * Classify whether a request may require SSR (HTML rendering).
  *
  * Returns false for requests that are definitively RSC-only: transport
- * params (partial/action/loader/__rsc), prerender collection, or an explicit
- * Accept: text/x-component. Must never return false for a request whose
+ * params (partial/action/loader/__rsc) or an explicit Accept:
+ * text/x-component. Must never return false for a request whose
  * render-time decision (isRscRequest) will be HTML — the two share
  * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
  * keys its HTML/RSC response slots off this function, so any divergence from
@@ -201,8 +208,7 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
     url.searchParams.has("_rsc_action") ||
     request.headers.has("rsc-action") ||
     url.searchParams.has("_rsc_loader") ||
-    url.searchParams.has("__rsc") ||
-    url.searchParams.has("__prerender_collect")
+    url.searchParams.has("__rsc")
   ) {
     return false;
   }

package/src/rsc/types.ts

@@ -193,6 +193,13 @@ export interface SSRRenderOptions {
    * the browser across hydration. Absent on host-agnostic build captures.
    */
   origin?: string;
+
+  /**
+   * Called for each error Fizz reports through its onError: a component that
+   * threw inside a Suspense boundary, which leaves the boundary errored in an
+   * otherwise completed document. React's default console.error is kept.
+   */
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -219,6 +226,15 @@ export interface SSRModule {
       maxWaitMs?: number;
       search?: string;
       origin?: string;
+      /** Each component error the prerender reports (never the capture's own abort). */
+      onError?: (error: unknown) => void;
+      /**
+       * React's errorInfo for each task still pending at the capture's abort
+       * (its componentStack is computed when read).
+       */
+      onAbortedTask?: (
+        errorInfo: { componentStack?: string } | undefined,
+      ) => void;
     },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 
@@ -237,6 +253,8 @@ export interface SSRModule {
       nonce?: string;
       search?: string;
       origin?: string;
+      /** Each component error the resumed holes report. */
+      onError?: (error: unknown) => void;
     },
   ) => Promise<ReadableStream<Uint8Array>>;
 }