@rangojs/router 0.20.0 → 0.21.0

package/src/server/request-context.ts

@@ -47,6 +47,7 @@ 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 { 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";
@@ -377,7 +378,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 +386,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 +449,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;
     /**
@@ -857,6 +858,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.
@@ -966,6 +976,7 @@ export type PublicRequestContext<
   | "_tracing"
   | "_basename"
   | "_routerId"
+  | "_versions"
   | "_setStatus"
   | "_rotateStateCookie"
   | "_setKeepCacheDirective"
@@ -1130,8 +1141,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;
 }
 
 /**
@@ -1159,7 +1175,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 +1210,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 +1230,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 +1467,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 +1543,7 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _versions: versions,
     _searchParamsFilter: searchParamsFilter,
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
@@ -1515,11 +1554,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,10 @@ 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 {
+  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 +122,17 @@ function createSsrEventController(opts: {
     flushRouteState: () => {},
     setHandleData: () => {},
     getHandleState: () => handleState,
+    freezeHydrationHandleState: () => {},
+    // The server render is the state the document is rendered with.
+    getHydrationHandleState: () => undefined,
     setRouteSegmentIds: () => {},
     setParams: (nextParams) => {
       params = nextParams;
     },
     getParams: () => params,
+    commitLocationState: () => {},
+    getLocationState: () => undefined,
+    takeTreelessLocationState: () => false,
     setLocation: () => {},
     startNavigation: () => {
       throw new Error("Navigation not supported during SSR");
@@ -294,7 +303,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     };
 
     // 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 +333,13 @@ 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}>
+          {content}
+        </LocationStateContext.Provider>
       </NavigationStoreContext.Provider>
     );
   };

package/src/testing/build-versions.ts

@@ -0,0 +1,64 @@
+/**
+ * Testing primitive for the per-router cache versions.
+ *
+ * A production build gives every `createRouter()` a data version and a
+ * document version (docs/design/per-app-cache-version.md) and ships them as a
+ * table in the `@rangojs/router:version` module. A test has no build, so the
+ * module is a stub and every router serves unversioned. `setBuildVersions`
+ * installs a table in its place; the request handler, `dispatch` and the cache
+ * stores then resolve versions through the same code path the built app uses.
+ * Calling it again is a deploy: the next request is served by a handler that
+ * resolved the new versions.
+ */
+import { installRouterVersionsTable } from "../server/build-version-table.js";
+import {
+  DEFAULT_ROUTER_VERSIONS_KEY,
+  type RouterVersions,
+  type RouterVersionsTable,
+} from "../router-versions.js";
+
+export type { RouterVersions };
+
+/**
+ * The versions a simulated build ships.
+ *
+ * - `data` and `document`: the versions of every router the test does not list
+ *   under `routers` (the build's whole-build pair).
+ * - `routers`: versions per router id (`router.id`), as a host-router build
+ *   computes them.
+ */
+export interface BuildVersions extends RouterVersions {
+  routers?: Record<string, RouterVersions>;
+}
+
+/**
+ * Install the cache versions of a simulated build, or remove them with no
+ * argument (routers serve unversioned again, the default in tests).
+ *
+ * A router that sets `createRouter({ version })` keeps that value for both
+ * versions, exactly as in production.
+ *
+ * @example A deploy that changes the client only keeps cached data
+ * ```ts
+ * setBuildVersions({ data: "d1", document: "h1" });
+ * await serveShellRequest(router, "/product/1", { cacheStore });
+ * setBuildVersions({ data: "d1", document: "h2" });
+ * const { shellStatus } = await serveShellRequest(router, "/product/1", {
+ *   cacheStore,
+ * });
+ * // shellStatus is "MISS": the stored HTML was keyed by document version h1.
+ * ```
+ */
+export function setBuildVersions(versions?: BuildVersions): void {
+  if (!versions) {
+    installRouterVersionsTable(undefined);
+    return;
+  }
+  const table: Record<string, readonly [string, string]> = {
+    [DEFAULT_ROUTER_VERSIONS_KEY]: [versions.data, versions.document],
+  };
+  for (const [routerId, pair] of Object.entries(versions.routers ?? {})) {
+    table[routerId] = [pair.data, pair.document];
+  }
+  installRouterVersionsTable(table satisfies RouterVersionsTable);
+}

package/src/testing/dispatch.ts

@@ -106,6 +106,7 @@ import {
   runWithRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import { resolveRouterVersions } from "../server/build-version-table.js";
 import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
 import type {
   MiddlewareEntry,
@@ -166,6 +167,8 @@ import { applyStreamIdleTimeout } from "../rsc/stream-idle.js";
 interface DispatchableRouter<TEnv> {
   id?: string;
   routerId?: string;
+  /** createRouter({ version }), the consumer-set version. */
+  version?: string;
   routeMap: Record<string, unknown>;
   middleware: MiddlewareEntry<TEnv>[];
   onError?: OnErrorCallback<TEnv>;
@@ -411,6 +414,9 @@ export async function dispatch<TEnv = any>(
     cacheStore,
     searchParamsFilter,
     cacheProfiles: router.cacheProfiles,
+    // The store keys with the router's versions, resolved as the production
+    // handler resolves them (rsc/handler.ts).
+    versions: resolveRouterVersions(routerId, router.version),
   });
   // Wire background error reporting so cache degradation (reportCacheError ->
   // _reportBackgroundError) reaches the router's onError, mirroring the production

package/src/testing/dom.entry.ts

@@ -18,5 +18,6 @@ export type {
   RenderRouteOptions,
   TestRouterHandle,
   RenderRouteResult,
+  RenderRouteHydrateResult,
   HandleDataSeed,
 } from "./render-route.js";

package/src/testing/flight.entry.ts

@@ -63,4 +63,5 @@ export {
 export type {
   ServeShellRequestOptions,
   ServeShellRequestResult,
+  ShellRequestHandles,
 } from "./serve-shell-request.js";

package/src/testing/index.ts

@@ -98,6 +98,9 @@ export type {
   ShellStatusTarget,
 } from "./shell-status.js";
 
+export { setBuildVersions } from "./build-versions.js";
+export type { BuildVersions, RouterVersions } from "./build-versions.js";
+
 export { collectHandle } from "./collect-handle.js";
 
 export { withLocationStateKey } from "./location-state-key.js";

package/src/testing/internal/context.ts

@@ -19,6 +19,7 @@ import { normalizeBasename } from "../../router/basename.js";
 import {
   seedVariables,
   resolveSeededStateCookieName,
+  seededVersions,
   type VarsInit,
   type StateCookieSeed,
 } from "./seed-vars.js";
@@ -164,7 +165,7 @@ export function createTestRequestContext<TEnv>(
     cacheStore: opts.cacheStore,
     cacheProfiles: opts.cacheProfiles,
     stateCookieName,
-    version: opts.stateCookie?.version,
+    versions: seededVersions(opts.stateCookie),
   });
   if (opts.basename !== undefined)
     ctx._basename = normalizeBasename(opts.basename);

package/src/testing/internal/seed-vars.ts

@@ -8,6 +8,7 @@
  */
 import { contextSet, type ContextVar } from "../../context-var.js";
 import { resolveStateCookieName } from "../../router/state-cookie-name.js";
+import { uniformVersions, type RouterVersions } from "../../router-versions.js";
 
 export interface StateCookieSeed {
   /**
@@ -22,8 +23,10 @@ export interface StateCookieSeed {
    */
   routerId?: string;
   /**
-   * Build version used as the rotated value's prefix (`{version}:{timestamp}`).
-   * Defaults to `"0"` (resolved inside createRequestContext).
+   * The app's version, as `createRouter({ version })` would set it: the
+   * rotated value's prefix (`{version}:{timestamp}`) and the version a cache
+   * store keys with. Defaults to `"0"` for the prefix (resolved inside
+   * createRequestContext) and to the build versions for the store.
    */
   version?: string;
 }
@@ -32,6 +35,15 @@ export function resolveSeededStateCookieName(seed?: StateCookieSeed): string {
   return resolveStateCookieName(seed?.prefix, seed?.routerId ?? "router_0");
 }
 
+/** The request context's `versions` for a seeded `stateCookie.version`. */
+export function seededVersions(
+  seed?: StateCookieSeed,
+): RouterVersions | undefined {
+  return seed?.version === undefined
+    ? undefined
+    : uniformVersions(seed.version);
+}
+
 export type VarsInit =
   | Record<string, unknown>
   | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;

package/src/testing/location-state-key.ts

@@ -1,12 +1,11 @@
 import {
+  isLocationStateKey,
+  LOCATION_STATE_KEY_PREFIX,
+  LOCATION_STATE_KEY_SUFFIX_SEPARATOR,
   peekLocationStateKey,
   type LocationStateDefinition,
 } from "../browser/react/location-state-shared.js";
 
-// Typed history.state slots must carry this prefix: buildHistoryState spreads
-// only `__rsc_ls_*` keys onto history.state (history-state.ts).
-const KEY_PREFIX = "__rsc_ls_";
-
 let syntheticKeyCounter = 0;
 
 /**
@@ -16,11 +15,15 @@ let syntheticKeyCounter = 0;
  * use (`MyState(value)`, `useLocationState(MyState)`, `.read()`).
  *
  * - `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState`
- *   (a name that already starts with `__rsc_ls_` is used as-is).
+ *   (a name that already starts with `__rsc_ls_` is used as-is). A definition
+ *   with `clearOnReload` appends its suffix, so read the stored key back from
+ *   `GridState.__rsc_ls_key` (`__rsc_ls_GridState~r`).
  * - Without a name, a key already set (by the plugin or an earlier call) is
  *   kept; otherwise the definition gets a synthetic `__rsc_ls_test_<n>` key,
  *   which then stays on it.
  *
+ * A name may not contain "~": that separator is reserved for the suffix.
+ *
  * Returns the definition.
  *
  * @example
@@ -35,11 +38,18 @@ export function withLocationStateKey<
   TDefinition extends LocationStateDefinition<any, any>,
 >(definition: TDefinition, name?: string): TDefinition {
   if (name !== undefined) {
-    definition.__rsc_ls_key = name.startsWith(KEY_PREFIX)
+    if (name.includes(LOCATION_STATE_KEY_SUFFIX_SEPARATOR)) {
+      throw new Error(
+        `withLocationStateKey: "${name}" contains "${LOCATION_STATE_KEY_SUFFIX_SEPARATOR}", ` +
+          "which is reserved for the key suffix of the `clearOnReload` option. " +
+          "Pass the name without a suffix; the definition appends its own.",
+      );
+    }
+    definition.__rsc_ls_key = isLocationStateKey(name)
       ? name
-      : KEY_PREFIX + name;
+      : LOCATION_STATE_KEY_PREFIX + name;
   } else if (!peekLocationStateKey(definition)) {
-    definition.__rsc_ls_key = `${KEY_PREFIX}test_${syntheticKeyCounter++}`;
+    definition.__rsc_ls_key = `${LOCATION_STATE_KEY_PREFIX}test_${syntheticKeyCounter++}`;
   }
   return definition;
 }

package/src/testing/render-handler.ts

@@ -37,6 +37,7 @@ import type { LoaderDefinition } from "../types.js";
 import {
   seedVariables,
   resolveSeededStateCookieName,
+  seededVersions,
   type VarsInit,
   type StateCookieSeed,
 } from "./internal/seed-vars.js";
@@ -253,7 +254,7 @@ export async function renderHandler<TEnv = any>(
     variables: seedVariables({}, opts.vars),
     build: opts.build,
     stateCookieName,
-    version: opts.stateCookie?.version,
+    versions: seededVersions(opts.stateCookie),
     cacheStore: opts.cacheStore,
     cacheProfiles: opts.cacheProfiles,
     themeConfig: