@rangojs/router 0.20.0 → 0.22.0

package/src/server/request-context.ts

@@ -46,7 +46,11 @@ import { withDefer } from "../defer.js";
 import { type MetricsStore } from "./context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
-import type { SegmentCacheStore } from "../cache/types.js";
+import type {
+  SegmentCacheStore,
+  ShellSnapshotHandlesValue,
+} from "../cache/types.js";
+import type { RouterVersions } from "../router-versions.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
 import type { TransitionWhenRecord } from "../router/transition-when.js";
@@ -288,6 +292,30 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal Env-scoped writable prerender store (the durable overlay) plus the
+   * deployment identity for build-scoped keys, resolved per request from the
+   * `prerender` router option. Read by the serve-path overlay lookup before the
+   * bundled build manifest. Absent when no prerender store is configured.
+   */
+  // ResolvedPrerender<any> (not <TEnv>): onRevalidate's contravariant `env` would
+  // otherwise make RequestContext invariant in TEnv, breaking existing
+  // RequestContext<{}> -> RequestContext<unknown> assignments.
+  _prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
+
+  /**
+   * @internal Set only on the requestless on-demand producer's context. When
+   * present, the standalone request-scoped READS — `cookies()`, `headers()`,
+   * `invalidateClientCache()`, `keepClientCache()` — throw a
+   * PrerenderPersonalizationError so a personalized render is skipped rather than
+   * baked into a shared payload. Response MUTATIONS on the producer context
+   * (`ctx.setStatus`/`header`/`setCookie`) stay silent no-op stubs, matching
+   * build-time prerender (the design's "throw or skip" contract permits skip):
+   * they write to a discarded synthetic response, so there is nothing to leak.
+   * Never set on the live request path.
+   */
+  _onDemandProducer?: true;
+
   /**
    * @internal Compiled `cache.searchParams` filter for default cache-key
    * generation (undefined = "all", the byte-stable unfiltered format). Set
@@ -364,6 +392,22 @@ export interface RequestContext<
    */
   _shellForcedMiss?: true;
 
+  /**
+   * @internal This request is a router.prerender() warm
+   * (prerender/warm-request.ts). In `replace` mode every runtime cache read
+   * misses (isWarmReplace); the layers report into the record. A capture's
+   * derived context inherits it through the prototype.
+   */
+  _prerenderWarm?: import("../prerender/warm-request.js").PrerenderWarmRecord;
+
+  /**
+   * @internal Runs a callback in the async context this request entered the
+   * handler with (captureRequestEntryContext). router.prerender() dispatches
+   * a warm through it when called from inside a request. Absent where the
+   * runtime has no AsyncLocalStorage.snapshot.
+   */
+  _runAtRequestEntry?: <T>(fn: () => T) => T;
+
   /**
    * @internal The freshness window of the route cache() records this
    * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
@@ -377,7 +421,7 @@ export interface RequestContext<
 
   /**
    * @internal Loader-family snapshot seed for a shell HIT's tail render:
-   * segment-key -> the capture's elided container (already Flight-deserialized
+   * loader id -> the capture's elided container (already Flight-deserialized
    * by serveShellHit) plus its capture-computed hole bit. resolveLoaderData
    * overlays it onto the fresh run's container (recorded paths pinned,
    * hole-marker paths keep the fresh nested promises) so the payload's baked
@@ -385,7 +429,9 @@ export interface RequestContext<
    * and does not run the loader. Two owners: serveShellHit sets it on the
    * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
    * request context of a PPR partial replay once its doc record hits, and
-   * restores the previous value after the match.
+   * restores the previous value after the match. Read through servedPins
+   * (loader-cache.ts) only: it also decides which of the record's
+   * loader-owned handle pushes stand (loaderPins).
    */
   _shellLoaderSeed?: Map<
     string,
@@ -446,9 +492,7 @@ export interface RequestContext<
      * scope replaces any route-derived cache() scope for the tail's match
      * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
      * ShellRecordUnavailableError instead of resolving segments
-     * (withCacheLookup): a HIT never runs a handler. The record's
-     * loader-owned handle pushes restore as authoritative
-     * (HandleStore.pushRestored): the prelude rendered them.
+     * (withCacheLookup): a HIT never runs a handler.
      */
     docTail?: true;
     /**
@@ -458,6 +502,8 @@ export interface RequestContext<
      * host) and miss the record.
      */
     fixedDocKey?: string;
+    /** @internal The snapshot's `handles` record (ShellSnapshotHandlesValue). */
+    prerenderHandles?: ShellSnapshotHandlesValue;
     /**
      * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
      * serve path. Its presence arms the explicit-scope composition in
@@ -807,6 +853,18 @@ export interface RequestContext<
    */
   _renderErrors?: unknown[];
 
+  /**
+   * @internal Rejections of streamed (loading()) handlers that were recovered
+   * into a declared errorBoundary()/notFoundBoundary() fallback, by segment id.
+   * The recovered promise resolves, so Flight reports nothing; cacheRoute
+   * (cache-scope.ts) refuses a write only when one of ITS segments is listed,
+   * the granularity a Flight error row has. The same errors are also pushed to
+   * `_renderErrors` for the document cache and PPR shell capture. A render
+   * under a derived context (shell capture, SWR re-render) owns its own map.
+   * Allocated on the first recovery.
+   */
+  _recoveredHandlerErrors?: Map<string, unknown>;
+
   /**
    * @internal Report a non-fatal background error through the router's
    * onError callback. Wired by the RSC handler / router during request
@@ -857,6 +915,15 @@ export interface RequestContext<
    *  lookups per router (route-map-builder.ts) */
   _routerId?: string;
 
+  /**
+   * @internal Cache versions of the router serving this request. The cache
+   * factory builds a store per request without knowing the router, so a store
+   * reads its key versions from here, lazily, the same way CFCacheStore
+   * resolves its base URL (getCacheVersions, server/build-version-table.ts).
+   * Unset on a context no router created; a store then uses the build version.
+   */
+  _versions?: RouterVersions;
+
   /**
    * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
@@ -916,6 +983,8 @@ export type PublicRequestContext<
   | "_transitionWhenRefs"
   | "_pprReplayPostMatchReason"
   | "_cacheStore"
+  | "_prerender"
+  | "_onDemandProducer"
   | "_searchParamsFilter"
   | "_shellCaptureRun"
   | "_shellImplicitCache"
@@ -926,6 +995,8 @@ export type PublicRequestContext<
   | "_resolvedCacheKeys"
   | "_shellKey"
   | "_shellForcedMiss"
+  | "_prerenderWarm"
+  | "_runAtRequestEntry"
   | "_routeRecordWindow"
   | "_shellFragmentPayload"
   | "_shellCaptureGuardTripped"
@@ -947,6 +1018,7 @@ export type PublicRequestContext<
   | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderErrors"
+  | "_recoveredHandlerErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"
   | "_renderBarrierSegmentOrder"
@@ -966,6 +1038,7 @@ export type PublicRequestContext<
   | "_tracing"
   | "_basename"
   | "_routerId"
+  | "_versions"
   | "_setStatus"
   | "_rotateStateCookie"
   | "_setKeepCacheDirective"
@@ -996,6 +1069,22 @@ export const UNTRACKED_BACKGROUND_TASK: unique symbol = Symbol.for(
 // AsyncLocalStorage instance for request context
 const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
 
+/**
+ * Capture the current async context (RequestContext._runAtRequestEntry), taken
+ * on handler entry before any router scope, so a nested dispatch (a
+ * router.prerender() warm called from a handler, loader or action) does not
+ * inherit the caller's route-definition, loader and cache-scope state. Per
+ * request: workerd refuses a snapshot outside the request that created it.
+ * See docs/design/prerender-every-route.md.
+ */
+export function captureRequestEntryContext():
+  | (<T>(fn: () => T) => T)
+  | undefined {
+  return typeof AsyncLocalStorage.snapshot === "function"
+    ? AsyncLocalStorage.snapshot()
+    : undefined;
+}
+
 /**
  * Run a function within a request context
  * Used by the RSC handler to provide context to server actions
@@ -1107,6 +1196,12 @@ export interface CreateRequestContextOptions<TEnv> {
   initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /**
+   * Optional env-scoped writable prerender store + deployment identity (the
+   * durable overlay), resolved per request by the RSC handler from the
+   * `prerender` router option.
+   */
+  prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
   /**
    * Compiled `cache.searchParams` filter from the resolved handler cache
    * config (handler.ts). Stored as _searchParamsFilter.
@@ -1130,8 +1225,13 @@ export interface CreateRequestContextOptions<TEnv> {
   themeConfig?: ResolvedThemeConfig | null;
   /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
   stateCookieName?: string;
-  /** Build version, used as the prefix of a server-rotated rango state value. */
-  version?: string;
+  /**
+   * The versions of the router serving this request (resolveRouterVersions).
+   * Stored as `_versions` for the cache stores; `document` is also the prefix
+   * of a server-rotated rango state value, which the browser compares with the
+   * payload's `metadata.version`.
+   */
+  versions?: RouterVersions;
 }
 
 /**
@@ -1152,6 +1252,7 @@ export function createRequestContext<TEnv>(
     variables,
     initialResponse,
     cacheStore,
+    prerender,
     searchParamsFilter,
     explicitTaggedStores,
     cacheProfiles,
@@ -1159,7 +1260,7 @@ export function createRequestContext<TEnv>(
     build = false,
     themeConfig,
     stateCookieName,
-    version: stateVersion,
+    versions,
   } = options;
   // ctx.request.headers is guarded like headers() (#976); every router read
   // of this request's headers goes through requestHeaders().
@@ -1194,6 +1295,12 @@ export function createRequestContext<TEnv>(
   // Set-Cookie drain (rsc/helpers.ts) run outside any latched funnel scope,
   // where assertCachedHeaderWriteAllowed is a no-op.
   let rawStubHeaders = stubResponse.headers;
+  // Node's util.inspect unwraps this Proxy and calls undici's Headers hook
+  // with the proxy as `this`. That reads `#headersList` and throws (#1000).
+  // Inspect does not consult the get trap, so the hook is an own property of
+  // the target and formats `rawStubHeaders`. Read on each call: setStatus
+  // rebinds that let to a new Headers.
+  const NODE_INSPECT = Symbol.for("nodejs.util.inspect.custom");
   const guardedStubHeaders: Headers = new Proxy(new Headers(), {
     get(_target, prop) {
       const raw = rawStubHeaders;
@@ -1208,6 +1315,22 @@ export function createRequestContext<TEnv>(
       return (value as (...a: unknown[]) => unknown).bind(raw);
     },
   });
+  Object.defineProperty(guardedStubHeaders, NODE_INSPECT, {
+    value(...args: unknown[]): unknown {
+      const hook = (rawStubHeaders as unknown as Record<symbol, unknown>)[
+        NODE_INSPECT
+      ];
+      if (typeof hook === "function") return hook.apply(rawStubHeaders, args);
+      // DOM Headers has forEach and not entries. Node always has the hook above.
+      const listed: Record<string, string> = {};
+      rawStubHeaders.forEach((value, key) => {
+        listed[key] = value;
+      });
+      return listed;
+    },
+    configurable: true,
+    writable: true,
+  });
   const shadowStubHeaders = (res: Response): void => {
     Object.defineProperty(res, "headers", {
       value: guardedStubHeaders,
@@ -1429,7 +1552,7 @@ export function createRequestContext<TEnv>(
       const prevRaw =
         (requestHeaders(request).get("x-rango-state") || null) ??
         getRawCookieValue(cookieHeader, stateCookieName);
-      const value = mintStateValue(stateVersion ?? "0", prevRaw);
+      const value = mintStateValue(versions?.document ?? "0", prevRaw);
       // rawStubHeaders: guard-exempt internal writer — invalidateClientCache()
       // is documented callable from loaders and during shell capture.
       rawStubHeaders.append(
@@ -1505,6 +1628,8 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _prerender: prerender,
+    _versions: versions,
     _searchParamsFilter: searchParamsFilter,
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
@@ -1515,11 +1640,23 @@ export function createRequestContext<TEnv>(
 
     waitUntil(fn: () => Promise<void>): void {
       if (ctx.build) return;
-      // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
+      // A deferred task does not rely on the platform carrying the request's
+      // async context into it. Deployed workerd lost it once ("use cache"
+      // background revalidation, cache-runtime.ts); Node and miniflare never
+      // do, so no local run shows a loss. A cache store builds its key inside
+      // the task and reads the serving router's versions and the request host
+      // from the context: without it the write lands under the whole-build
+      // pair, which no router with its own version reads. So the task
+      // re-enters the context it was scheduled under: the store active then
+      // (a derived context), else this one.
+      const scheduledUnder = requestContextStorage.getStore() ?? ctx;
+      // Wrap in Promise.resolve().then(...) so a SYNCHRONOUS throw in a
       // non-async callback becomes a rejected promise handed to the host's
       // waitUntil (logged as a background failure), instead of escaping into
       // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
-      const task = Promise.resolve().then(fn);
+      const task = Promise.resolve().then(() =>
+        requestContextStorage.run(scheduledUnder, fn),
+      );
       // Track the task promise so the PPR shell capture can settle the
       // foreground's deferred cache writes before its own match/render (the
       // ordering edge; see _pendingBackgroundTasks). The capture task itself

package/src/ssr/ssr-root.tsx

@@ -7,7 +7,11 @@ import {
 } from "../browser/react/filter-segment-order.js";
 import { ThemeProvider } from "../theme/ThemeProvider.js";
 import { NonceContext } from "../browser/react/nonce-context.js";
-import { NavigationStoreContext } from "../browser/react/context.js";
+import {
+  HydrationBarrierContext,
+  LocationStateContext,
+  NavigationStoreContext,
+} from "../browser/react/context.js";
 import type { NavigationStoreContextValue } from "../browser/react/context.js";
 import type { HandleData } from "../browser/types.js";
 import type { ResolvedSegment } from "../types.js";
@@ -119,11 +123,17 @@ function createSsrEventController(opts: {
     flushRouteState: () => {},
     setHandleData: () => {},
     getHandleState: () => handleState,
+    lockHydration: () => {},
+    getHydrationSnapshot: () => undefined,
+    releaseHydrationLock: () => {},
     setRouteSegmentIds: () => {},
     setParams: (nextParams) => {
       params = nextParams;
     },
     getParams: () => params,
+    commitLocationState: () => {},
+    getLocationState: () => undefined,
+    takeTreelessLocationState: () => false,
     setLocation: () => {},
     startNavigation: () => {
       throw new Error("Navigation not supported during SSR");
@@ -277,24 +287,28 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     }
 
     // Create SSR context with request-local pathname/params/handles.
-    ssrContextValue ??= {
-      store: null as any,
-      eventController: createSsrEventController({
+    if (!ssrContextValue) {
+      const eventController = createSsrEventController({
         pathname,
         search,
         origin,
         params: resolved.metadata?.params,
         handleData,
         matched: resolved.metadata?.matched,
-      }),
-      navigate: async () => {},
-      refresh: async () => {},
-      version: resolved.metadata?.version,
-      basename: resolved.metadata?.basename,
-    };
+      });
+      ssrContextValue = {
+        store: null as any,
+        eventController,
+        navigate: async () => {},
+        refresh: async () => {},
+        version: resolved.metadata?.version,
+        basename: resolved.metadata?.basename,
+        origin: (eventController.getState().location as URL).origin,
+      };
+    }
 
     // Build content tree from segments.
-    // Order must match NavigationProvider: NavigationStoreContext > NonceContext > ThemeProvider > content
+    // Order must match NavigationProvider: NavigationStoreContext > LocationStateContext > NonceContext > ThemeProvider > content
     // Memoize like payload/handles above: renderSegments is async, so
     // React.use() on a fresh promise suspends and replays SsrRoot, which
     // would re-run the entire segment-tree build on every initial render.
@@ -324,10 +338,15 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
       <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
     );
 
-    // Wrap with NavigationStoreContext for useNavigation hook
+    // Wrap with NavigationStoreContext for useNavigation hook. The server has
+    // no history entry: location state is undefined, as readers hydrate.
     return (
       <NavigationStoreContext.Provider value={ssrContextValue!}>
-        {content}
+        <LocationStateContext.Provider value={undefined}>
+          <HydrationBarrierContext.Provider value={0}>
+            {content}
+          </HydrationBarrierContext.Provider>
+        </LocationStateContext.Provider>
       </NavigationStoreContext.Provider>
     );
   };

package/src/suspense-audit-react.tsx

@@ -0,0 +1,98 @@
+import { useEffect, useLayoutEffect, useRef, type ReactNode } from "react";
+import {
+  auditCommit,
+  auditFallback,
+  auditHandover,
+  auditMount,
+  auditRead,
+  auditReveal,
+  auditUnmount,
+  createBoundaryAudit,
+  type BoundaryAudit,
+} from "./suspense-audit.js";
+
+// Hooks of the suspense audit (docs/internal/suspense-contract.md), called by
+// dev-only components: React Compiler skips a component with a gated hook.
+
+function useRecord(boundary: string, segmentId: string): BoundaryAudit {
+  const ref = useRef<BoundaryAudit | null>(null);
+  // One position can hold another segment's boundary: its Suspense is keyed.
+  if (ref.current === null || ref.current.boundary !== boundary) {
+    ref.current = createBoundaryAudit(boundary, segmentId);
+  }
+  return ref.current;
+}
+
+// Passive, not layout: React disconnects the layout effects of content a
+// Suspense boundary hides, and that is not an unmount.
+function useMount(rec: BoundaryAudit): void {
+  useEffect(() => {
+    auditMount(rec);
+    return () => auditUnmount(rec);
+  }, [rec]);
+}
+
+/**
+ * One boundary: what each render hands it, what each commit carries, and its
+ * mount. Called above the Suspense, which commits while the content waits.
+ * `streams` and `nodes` are what else its content waits for (I3 only).
+ */
+export function useBoundaryAudit(
+  boundary: string,
+  segmentId: string,
+  value: unknown,
+  streams?: Record<string, unknown>,
+  nodes?: unknown,
+): BoundaryAudit {
+  const rec = useRecord(boundary, segmentId);
+  auditHandover(rec, value);
+  useLayoutEffect(() => {
+    auditCommit(rec, value, streams, nodes);
+  }, [rec, value, streams, nodes]);
+  useMount(rec);
+  return rec;
+}
+
+/** The boundary's content is on screen. */
+export function useRevealAudit(rec: BoundaryAudit): void {
+  useLayoutEffect(() => {
+    auditReveal(rec);
+  }, [rec]);
+}
+
+/**
+ * One `useLoader` read of a per-loader stream (I1, I2 at the read site). A
+ * read that suspends while mounting keeps no record: only a reader on screen
+ * is audited.
+ */
+export function useReadAudit(loaderId: string, stream: unknown): void {
+  const rec = useRecord(`read:${loaderId}`, loaderId);
+  auditHandover(rec, stream);
+  useLayoutEffect(() => {
+    auditRead(rec, stream);
+  }, [rec, stream]);
+}
+
+/** Wraps a boundary's fallback: mounted means the fallback is on screen. */
+export function AuditedFallback({
+  audit,
+  children,
+}: {
+  audit: BoundaryAudit;
+  children: ReactNode;
+}): ReactNode {
+  useLayoutEffect(() => auditFallback(audit), [audit]);
+  return children;
+}
+
+/** Wraps a segment's outlet children: the segment's mount (I4). */
+export function AuditedOutlet({
+  segmentId,
+  children,
+}: {
+  segmentId: string;
+  children: ReactNode;
+}): ReactNode {
+  useMount(useRecord(`outlet:${segmentId}`, segmentId));
+  return children;
+}