@rangojs/router 0.21.0 → 0.22.0

package/src/router/route-trie-builder.ts

@@ -37,6 +37,12 @@ export interface TrieLeaf {
   pr?: true;
   /** Passthrough: handler kept in bundle for live fallback on unknown params */
   pt?: true;
+  /**
+   * On-demand prerender eligible: the route opted into router.prerender()
+   * refresh. Distinct from `pr` — an od route may have no build-baked entry yet
+   * still needs a writable-overlay lookup at serve time.
+   */
+  od?: true;
   /** Response type for non-RSC routes (json, text, image, any) */
   rt?: string;
   /** Negotiate variants: response-type routes sharing this path */
@@ -72,6 +78,7 @@ export interface TrieNode {
  * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
  * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
  * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
+ * @param onDemandRouteNames - Optional set of on-demand-eligible route names (sets leaf.od)
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,
@@ -80,6 +87,7 @@ export function buildRouteTrie(
   prerenderRouteNames?: Set<string>,
   passthroughRouteNames?: Set<string>,
   responseTypeRoutes?: Record<string, string>,
+  onDemandRouteNames?: Set<string>,
 ): TrieNode {
   const root: TrieNode = {};
 
@@ -99,6 +107,7 @@ export function buildRouteTrie(
       ...(trailingSlash ? { ts: trailingSlash } : {}),
       ...(prerenderRouteNames?.has(routeName) ? { pr: true } : {}),
       ...(passthroughRouteNames?.has(routeName) ? { pt: true } : {}),
+      ...(onDemandRouteNames?.has(routeName) ? { od: true } : {}),
       ...(responseType ? { rt: responseType } : {}),
     });
   }

package/src/router/router-context.ts

@@ -100,6 +100,7 @@ export interface RouterContext<TEnv = any> {
       parent: any,
       fn: () => T,
     ) => T;
+    runIsolated: <T>(forRoute: string, fn: () => T) => T;
   };
 
   getMetricsStore: () => MetricsStore | undefined;

package/src/router/router-interfaces.ts

@@ -225,6 +225,29 @@ export interface Rango<
    * ```
    */
   fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+
+  /**
+   * Bind `{ env, ctx }` and get the on-demand (ISR-style) prerender runner, to refresh from a running app —
+   * fetch handler, cron, queue, workflow, webhook, or server action.
+   *
+   * Requestless: the producer renders with route params and env only, never the
+   * caller's cookies/headers/session. Only routes that opted in via
+   * `Prerender(..., { onDemand })` are persistable; others return a skipped
+   * result. Configure the store via the `prerender` router option.
+   *
+   * @example
+   * ```ts
+   * const prerender = router.prerender({ env, ctx });
+   * await prerender("/products/42");
+   * await prerender(
+   *   { route: "products.detail", params: { id: "42" } },
+   *   { throwOnError: true },
+   * );
+   * await prerender.many(targets, { concurrency: 4 });
+   * await prerender.markStale(["product:42"]);
+   * ```
+   */
+  prerender: import("../prerender/on-demand.js").PrerenderFn<TEnv, TRoutes>;
 }
 
 /**
@@ -332,6 +355,13 @@ export interface RangoInternal<
    */
   readonly cache?: RangoOptions<TEnv>["cache"];
 
+  /**
+   * Prerender store configuration (the writable durable overlay for on-demand
+   * prerender). Stored separately from the `prerender` trigger method so the RSC
+   * handler can resolve it per request. @internal
+   */
+  readonly _prerenderConfig?: RangoOptions<TEnv>["prerender"];
+
   /**
    * Not found component to render when no route matches
    */
@@ -620,6 +650,9 @@ export interface RangoInternal<
    * Handle an RSC request.
    */
   fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+
+  /** On-demand prerender binder: router.prerender({ env, ctx }) returns the runner. */
+  prerender: import("../prerender/on-demand.js").PrerenderFn<TEnv, TRoutes>;
 }
 
 /**

package/src/router/router-options.ts

@@ -341,6 +341,36 @@ export interface RangoOptions<TEnv = any> {
         searchParams?: CacheSearchParams;
       });
 
+  /**
+   * Writable prerender store for on-demand (ISR-style) prerender refresh.
+   *
+   * A durable overlay in front of the bundled build manifest. When provided,
+   * `router.prerender(target, { env, ctx })` renders a route requestlessly and
+   * writes a versioned payload here; the serve path reads the overlay before the
+   * bundled manifest. Same union shape as `cache`: a plain config object or a
+   * factory resolved per request/per call (never at `createRouter()` time), so
+   * multi-tenant apps never memoize one request's binding for another.
+   *
+   * @example Cloudflare KV overlay with SWR revalidation
+   * ```typescript
+   * import { createKVPrerenderStore } from "@rangojs/router/prerender/cloudflare";
+   *
+   * const router = createRouter<AppEnv>({
+   *   prerender: (env) => ({
+   *     store: createKVPrerenderStore(env.PRERENDER_KV),
+   *     ttl: 3600,
+   *     onRevalidate: (target, e) => e.PRERENDER_QUEUE.send({ target }),
+   *   }),
+   * });
+   * ```
+   */
+  prerender?:
+    | import("../prerender/on-demand.js").PrerenderConfig<TEnv>
+    | ((
+        env: TEnv,
+        ctx?: ExecutionContext,
+      ) => import("../prerender/on-demand.js").PrerenderConfig<TEnv>);
+
   /**
    * Named cache profiles for "use cache" directive.
    * Profile names map to TTL/SWR configuration.

package/src/router/segment-resolution/fresh.ts

@@ -36,7 +36,7 @@ import {
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { _getRequestContext } from "../../server/request-context.js";
 import { getRouterContext } from "../router-context.js";
-import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import { observeSegmentHandler } from "../instrument.js";
 import {
   track,
@@ -280,6 +280,13 @@ export interface ResolveSegmentOptions {
    * #918: resolved twice on a MISS, once and discarded on a HIT).
    */
   chain?: readonly EntryData[];
+  /**
+   * The matched chain entry being resolved: where the sync path catches a
+   * handler error, so a streamed handler (or slot owned by a routeless layout)
+   * recovers into the same boundary. resolveSegment sets it for the entry it
+   * resolves; nested resolutions keep the outer value.
+   */
+  boundaryEntry?: EntryData;
 }
 
 /**
@@ -298,6 +305,8 @@ export async function resolveSegment<TEnv>(
   options?: ResolveSegmentOptions,
 ): Promise<ResolvedSegment[]> {
   const segments: ResolvedSegment[] = [];
+  const boundaryEntry = options?.boundaryEntry ?? entry;
+  if (!options?.boundaryEntry) options = { ...options, boundaryEntry };
 
   if (entry.type === "layout" || entry.type === "cache") {
     if (!options?.skipLoaders) {
@@ -398,19 +407,15 @@ export async function resolveSegment<TEnv>(
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
-          const tracked = deps.trackHandler(result, {
+          component = trackStreamedHandler(deps, result, {
+            boundaryEntry,
             segmentId: entry.shortCode,
             segmentType: entry.type,
-          });
-          observeStreamedHandler(
-            tracked,
-            entry.shortCode,
-            entry.type,
-            context.pathname,
+            context,
             routeKey,
             params,
-          );
-          component = tracked;
+            recover: !options?.throwOnError,
+          });
         } else {
           doneRouteHandler();
           component = result;
@@ -679,19 +684,15 @@ export async function resolveParallelEntry<TEnv>(
             : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
-          const tracked = deps.trackHandler(result, {
+          component = trackStreamedHandler(deps, result, {
+            boundaryEntry: options?.boundaryEntry ?? parallelEntry,
             segmentId: `${parentShortCode}.${slot}`,
             segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            `${parentShortCode}.${slot}`,
-            "parallel",
-            context.pathname,
+            context,
             routeKey,
             params,
-          );
-          component = tracked as ReactNode;
+            recover: !options?.throwOnError,
+          });
         } else {
           doneParallelHandler();
           component = result as ReactNode;

package/src/router/segment-resolution/loader-cache.ts

@@ -9,7 +9,8 @@
  *   1. options.key(requestCtx) — full override, stored namespaced as
  *      loader:{loaderId}:key:{encodeURIComponent(result)} (#1009)
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
- *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
+ *   3. loader:{loaderId}:{routerId}@{host}{pathname}:{sortedParams} — default
+ *      (a loader's ctx is one router's: cache-key-utils.ts, the router rule)
  *
  * Values are serialized via RSC Flight (serializeResult/deserializeResult),
  * supporting ReactNode, Promises, null, and all RSC-serializable types.
@@ -77,7 +78,7 @@ import {
 import { observePhase, PHASES } from "../instrument.js";
 import {
   KEY_PART_PREFIX,
-  sortedRouteParams,
+  requestKeyBase,
 } from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
@@ -88,6 +89,7 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import { isWarmReplace, noteWarmWrite } from "../../prerender/warm-request.js";
 import {
   executionStart,
   predatesInvalidation,
@@ -138,17 +140,6 @@ function debugLoaderCacheLog(message: string): void {
   }
 }
 
-function getDefaultLoaderCacheKey(
-  loaderId: string,
-  host: string,
-  pathname: string,
-  params: Record<string, string>,
-): string {
-  const paramStr = sortedRouteParams(params);
-  const base = paramStr ? `${pathname}:${paramStr}` : pathname;
-  return `loader:${loaderId}:${host}${base}`;
-}
-
 /**
  * A loader's own `key()` result as its entry key (#1009). The result is
  * often request input, and the item family (`getItem`/`setItem`) has no
@@ -159,7 +150,7 @@ function getDefaultLoaderCacheKey(
  * - an encoded result holds no `:`, so the key reads unambiguously from
  *   the right (result, `key:`, loader id), and two namespaced keys are
  *   equal only for the same loader and result;
- * - a default key `loader:<id>:<host><pathname>...` holds a `/` past its
+ * - a default key `loader:<id>:[<router>@]<host><pathname>...` holds a `/` past its
  *   id, and an encoded result holds none, so the two are equal only if one
  *   loader's id is literally `<other id>:<host>/<path>...`. Loader ids can
  *   hold `:` (a dev id is a root-relative path, absolute `D:/...` on
@@ -188,8 +179,9 @@ async function resolveLoaderKey(
   // (cache-runtime pushes ctx.url.host). Without it, a multi-tenant host router
   // serving the same pathname for different hosts would leak one host's cached
   // loader data to another.
-  const host = getRequestContext()?.url?.host ?? "localhost";
-  const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
+  const requestCtx = getRequestContext();
+  const host = requestCtx?.url?.host ?? "localhost";
+  const defaultKey = `loader:${loaderId}:${requestKeyBase(requestCtx, host, pathname, undefined, params)}`;
   if (options === false) return { key: defaultKey, declared: false };
   const keyFn = options.key;
   return {
@@ -768,7 +760,11 @@ function executeLoaderData<TEnv>(
     };
 
     const data = await readThroughItem({
-      getItem: (k) => store.getItem!(k),
+      // A router.prerender() warm takes the miss path: the body runs and
+      // setItem replaces the entry.
+      getItem: isWarmReplace(requestCtxForExecute)
+        ? async () => null
+        : (k) => store.getItem!(k),
       // Handles ride the entry like "use cache" (encodeHandles: Flight, pending
       // pushes awaited up to its timeout, the whole blob dropped on a timeout
       // or a thrown encode). Encoded here, inside the deferred write, so a
@@ -795,7 +791,9 @@ function executeLoaderData<TEnv>(
             ...o,
             tags: entryTags.length > 0 ? entryTags : undefined,
             ...(handles ? { handles } : {}),
+            startedAt: start?.at,
           });
+          noteWarmWrite(requestCtxForExecute, "item");
         }),
       key,
       execute: async () => {

package/src/router/segment-resolution/revalidation.ts

@@ -47,7 +47,7 @@ import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { observeEvent, observeSegmentHandler } from "../instrument.js";
 import { runInSegmentTagScope } from "../../cache/cache-tag.js";
-import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import {
   track,
   RangoContext,
@@ -441,6 +441,8 @@ async function resolveParallelSlotComponent<TEnv>(args: {
   deps: SegmentResolutionDeps<TEnv>;
   routeKey: string;
   params: Record<string, string>;
+  /** Matched chain entry (where the sync path catches), else the slot's owner. */
+  boundaryEntry: EntryData;
 }): Promise<{ component: ReactNode | undefined; handlerRan: boolean }> {
   const {
     shouldResolve,
@@ -452,6 +454,7 @@ async function resolveParallelSlotComponent<TEnv>(args: {
     deps,
     routeKey,
     params,
+    boundaryEntry,
   } = args;
 
   let component: ReactNode | undefined;
@@ -484,19 +487,15 @@ async function resolveParallelSlotComponent<TEnv>(args: {
             : handler;
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, parallelId);
-          const tracked = deps.trackHandler(result, {
+          component = trackStreamedHandler(deps, result, {
+            boundaryEntry,
             segmentId: parallelId,
             segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            parallelId,
-            "parallel",
-            context.pathname,
+            context,
             routeKey,
             params,
-          );
-          component = tracked as ReactNode;
+            recover: true,
+          });
         } else {
           component = result as ReactNode;
         }
@@ -547,6 +546,8 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
      * to it: loader sub-ids are filtered out and slots are re-grouped by parent).
      */
     loaderOrder?: "after" | "before";
+    /** Matched chain entry being resolved; see ResolveSegmentOptions.boundaryEntry. */
+    boundaryEntry?: EntryData;
   },
 ): Promise<SegmentRevalidationResult> {
   const segments: ResolvedSegment[] = [];
@@ -696,6 +697,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       deps,
       routeKey,
       params,
+      boundaryEntry: options?.boundaryEntry ?? entry,
     });
 
     segments.push({
@@ -865,19 +867,17 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, routeEntry.id);
           result.finally(doneHandler).catch(() => {});
-          const tracked = deps.trackHandler(result, {
-            segmentId: entry.shortCode,
-            segmentType: entry.type,
-          });
-          observeStreamedHandler(
-            tracked,
-            entry.shortCode,
-            entry.type,
-            context.pathname,
-            routeKey,
-            params,
-          );
-          return { content: tracked };
+          return {
+            content: trackStreamedHandler(deps, result, {
+              boundaryEntry: entry,
+              segmentId: entry.shortCode,
+              segmentType: entry.type,
+              context,
+              routeKey,
+              params,
+              recover: true,
+            }),
+          };
         }
         doneHandler();
         return { content: result };
@@ -1098,6 +1098,8 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         deps,
         actionContext,
         stale,
+        undefined,
+        entry,
       );
       segments.push(...orphanResult.segments);
       matchedIds.push(...orphanResult.matchedIds);
@@ -1126,6 +1128,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   stale?: boolean,
   /** Parent route entry — its loaders are inherited so parallel slots can access them. */
   parentRouteEntry?: EntryData,
+  /** Matched chain entry being resolved (see ResolveSegmentOptions.boundaryEntry); defaults to parentRouteEntry. */
+  boundaryEntry: EntryData | undefined = parentRouteEntry,
 ): Promise<SegmentRevalidationResult> {
   invariant(
     orphan.type === "layout" || orphan.type === "cache",
@@ -1286,7 +1290,11 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     deps,
     actionContext,
     stale,
-    { parentChainDefault: "force-render", loaderOrder: "before" },
+    {
+      parentChainDefault: "force-render",
+      loaderOrder: "before",
+      boundaryEntry,
+    },
   );
   segments.push(...parallelResult.segments);
   matchedIds.push(...parallelResult.matchedIds);
@@ -1307,6 +1315,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       deps,
       actionContext,
       stale,
+      undefined,
+      boundaryEntry,
     );
     segments.push(...nestedResult.segments);
     matchedIds.push(...nestedResult.matchedIds);

package/src/router/segment-resolution/streamed-handler-boundary.ts

@@ -0,0 +1,133 @@
+/**
+ * Streamed handlers (loading()): track, observe, and recover a rejection into
+ * the declared errorBoundary() / notFoundBoundary() fallback.
+ *
+ * Invariants:
+ * - No status write and no onError call: the status is committed at first
+ *   flush, and trackHandler already reports each rejection once.
+ * - The recovered promise resolves, so Flight reports no error. The writers
+ *   that refuse a failed render through Flight errors need the failure
+ *   recorded here: `_renderErrors` for the document cache and a prerender
+ *   warm, `_recoveredHandlerErrors` for cacheRoute (cache(), and the doc record
+ *   a PPR capture needs). The shell capture and the SWR re-render own both,
+ *   so a derived render never writes into (or reads) the foreground's.
+ * - Nothing to render to rethrows the original rejection: no boundary found, a
+ *   thrown Response (redirect), a Skip, a throwing fallback.
+ * - No recovery when `recover` is false (prerender throwOnError, the intercept
+ *   background re-render): those lanes must reject so nothing is baked/cached.
+ */
+
+import type { ReactNode } from "react";
+import { isDataNotFoundError } from "../../errors.js";
+import {
+  createErrorInfo,
+  createNotFoundInfo,
+  renderErrorFallback,
+  renderNotFoundFallback,
+  resolveNotFoundFallback,
+} from "../error-handling.js";
+import { _getRequestContext } from "../../server/request-context.js";
+import type { EntryData } from "../../server/context.js";
+import type { ErrorInfo, HandlerContext } from "../../types/index.js";
+import type { SegmentResolutionDeps } from "../types.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+
+export interface StreamedHandlerOptions<TEnv> {
+  /**
+   * Entry to look boundaries up from: the matched chain entry being resolved
+   * (where the sync path catches, whatever routeless layout owns a slot), or
+   * the intercept's declaring entry.
+   */
+  boundaryEntry: EntryData;
+  segmentId: string;
+  segmentType: ErrorInfo["segmentType"];
+  context: HandlerContext<any, TEnv>;
+  routeKey?: string;
+  params: Record<string, string>;
+  /** False where the rejection must reach the caller (prerender, intercept background re-render). */
+  recover: boolean;
+}
+
+const NOOP = (): void => {};
+
+/**
+ * Track a streamed handler promise and return the segment component: the
+ * tracked promise itself when there is nothing to recover to, else a promise
+ * that resolves to the declared fallback on rejection.
+ */
+export function trackStreamedHandler<TEnv>(
+  deps: SegmentResolutionDeps<TEnv>,
+  result: Promise<unknown>,
+  options: StreamedHandlerOptions<TEnv>,
+): ReactNode {
+  const { segmentId, segmentType, context } = options;
+  const tracked = deps.trackHandler(result as Promise<ReactNode>, {
+    segmentId,
+    segmentType,
+  });
+  observeStreamedHandler(
+    tracked,
+    segmentId,
+    segmentType,
+    context.pathname,
+    options.routeKey,
+    options.params,
+  );
+
+  if (!options.recover) return tracked as ReactNode;
+  const { boundaryEntry } = options;
+  const hasBoundary =
+    deps.findNearestErrorBoundary(boundaryEntry) != null ||
+    deps.findNearestNotFoundBoundary(boundaryEntry) != null ||
+    deps.notFoundComponent !== undefined;
+  if (!hasBoundary) return tracked as ReactNode;
+
+  // Captured now: the rejection can settle outside the request's ALS frame.
+  const reqCtx = _getRequestContext();
+  const recovered = tracked.catch((error: unknown): ReactNode => {
+    const node = renderBoundary(error, deps, options, boundaryEntry);
+    if (node === undefined) throw error;
+    if (reqCtx)
+      (reqCtx._recoveredHandlerErrors ??= new Map()).set(segmentId, error);
+    reqCtx?._renderErrors?.push(error);
+    return node;
+  });
+  // A dropped segment (never rendered) must not become an unhandledRejection.
+  recovered.catch(NOOP);
+  return recovered as ReactNode;
+}
+
+function renderBoundary<TEnv>(
+  error: unknown,
+  deps: SegmentResolutionDeps<TEnv>,
+  options: StreamedHandlerOptions<TEnv>,
+  boundaryEntry: EntryData,
+): ReactNode | undefined {
+  if (error instanceof Response) return undefined;
+  if ((error as { name?: string } | null)?.name === "Skip") return undefined;
+  const { segmentId, segmentType, context } = options;
+  try {
+    if (isDataNotFoundError(error)) {
+      const boundary = deps.findNearestNotFoundBoundary(boundaryEntry);
+      if (boundary == null && deps.notFoundComponent === undefined) {
+        return undefined;
+      }
+      return renderNotFoundFallback(
+        resolveNotFoundFallback(
+          boundary,
+          deps.notFoundComponent,
+          context.pathname,
+        ),
+        createNotFoundInfo(error, segmentId, segmentType, context.pathname),
+      );
+    }
+    const fallback = deps.findNearestErrorBoundary(boundaryEntry);
+    if (fallback == null) return undefined;
+    return renderErrorFallback(
+      fallback,
+      createErrorInfo(error, segmentId, segmentType),
+    );
+  } catch {
+    return undefined;
+  }
+}

package/src/router/trie-matching.ts

@@ -25,6 +25,8 @@ export interface TrieMatchResult {
   pr?: true;
   /** Passthrough: handler kept for live fallback on unknown params */
   pt?: true;
+  /** On-demand prerender eligible (router.prerender() refreshable) */
+  od?: true;
   /** Response type for non-RSC routes (json, text, image, any) */
   responseType?: string;
   /** Negotiate variants: response-type routes sharing this path */
@@ -343,6 +345,7 @@ function validateAndBuild(
   if (redirectTo) result.redirectTo = redirectTo;
   if (leaf.pr) result.pr = true;
   if (leaf.pt) result.pt = true;
+  if (leaf.od) result.od = true;
   if (leaf.rt) result.responseType = leaf.rt;
   if (leaf.nv) result.negotiateVariants = leaf.nv;
   if (leaf.rf) result.rscFirst = true;