@rangojs/router 0.28.0 → 0.29.0

package/src/cache/cache-runtime.ts

@@ -22,6 +22,7 @@ import {
 } from "../deps/rsc-client.js";
 import {
   getRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../server/request-context.js";
 import { isUnderTestRunner } from "../runtime-env.js";
@@ -75,7 +76,6 @@ import {
   executionStart,
   invalidatedSince,
   predatesInvalidation,
-  runAsBackgroundRefresh,
   type ExecutionStart,
 } from "./tag-invalidation.js";
 import type { CacheItemResult } from "./types.js";
@@ -727,22 +727,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // user's value into the shared entry — with zero visibility to the
             // concurrent foreground.
 
-            try {
-              // Re-establish the request-context ALS so a "use cache" body that
-              // reads the ambient getRequestContext() (e.g.
-              // getRequestContext().env.ApiKey) resolves during the background
-              // revalidation instead of throwing "called outside of a request
-              // context". runAsBackgroundRefresh sets the store for fn's
-              // synchronous kickoff; its async continuations inherit it. No
-              // visitor made the invalidations it runs: they set no
-              // fresh-reads cookie.
-              //
-              // The span opens inside the request ALS and wraps the WHOLE task —
-              // fn kickoff through the store write — so its platform spans nest
-              // under rango.background and a slow or failing setItem is part of
-              // the traced revalidation, not an untraced tail.
-              await runAsBackgroundRefresh(requestCtx, () =>
-                observePhase(
+            // Re-establish the request-context ALS so a "use cache" body that
+            // reads the ambient getRequestContext() (e.g.
+            // getRequestContext().env.ApiKey) resolves during the background
+            // revalidation instead of throwing "called outside of a request
+            // context". runAsBackgroundWork sets the store for fn's synchronous
+            // kickoff; its async continuations inherit it. No visitor made the
+            // invalidations it runs (no fresh-reads cookie), and onError marks
+            // its errors `background`, the failure caught below included.
+            //
+            // The span opens inside the request ALS and wraps the WHOLE task —
+            // fn kickoff through the store write — so its platform spans nest
+            // under rango.background and a slow or failing setItem is part of
+            // the traced revalidation, not an untraced tail.
+            await runAsBackgroundWork(requestCtx, async () => {
+              try {
+                await observePhase(
                   PHASES.background("use-cache-revalidation"),
                   async () => {
                     const refreshArgs = args.map(refreshView);
@@ -796,20 +796,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                       noteWarmWrite(requestCtx, "item");
                     }
                   },
-                ),
-              );
-            } catch (bgError) {
-              bgCapture?.stop();
-              // Pass requestCtx explicitly: this runs in a detached background
-              // task where the ALS context is gone, so onError can only fire if
-              // we hand it the context captured up front.
-              reportCacheError(
-                bgError,
-                "stale-revalidation",
-                "[use cache] background revalidation failed",
-                requestCtx,
-              );
-            }
+                );
+              } catch (bgError) {
+                bgCapture?.stop();
+                reportCacheError(
+                  bgError,
+                  "stale-revalidation",
+                  "[use cache] background revalidation failed",
+                  requestCtx,
+                );
+              }
+            });
           }),
         );
         return result;

package/src/cache/document-cache.ts

@@ -22,7 +22,7 @@ import {
 import {
   createRequestContext,
   getRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../server/request-context.js";
 import { deriveRenderPass } from "../server/render-pass.js";
@@ -378,24 +378,25 @@ export function createDocumentCacheMiddleware<TEnv = any>(
           }),
         });
 
-        runBackground(requestCtx, async () => {
-          try {
-            // Re-establish the request-context ALS around the whole background
-            // task: next() re-runs the full handler pipeline, and on workerd a
-            // waitUntil task runs detached from the request's I/O context, so a
-            // handler/component reading getRequestContext() would otherwise
-            // throw. Same fix as the route-level/use-cache background
-            // revalidation paths. The rango.background span (kind=
-            // document-revalidation) wraps the re-render AND the store write so
-            // the task's spans — the re-run's own rango.* set and the drain/put
-            // platform spans — nest under one explanatory parent instead of
-            // dangling under the ended foreground phases. Running the put
-            // inside the ALS matches the MISS path, where putResponse already
-            // executes within the foreground request context. No visitor made
-            // the invalidations the re-run makes: the pass's fresh-reads
-            // writer is the sink's, which sets nothing.
-            await runWithRequestContext(rerunCtx, () =>
-              observePhase(
+        // Re-establish the request-context ALS around the whole background
+        // task: next() re-runs the full handler pipeline, and on workerd a
+        // waitUntil task runs detached from the request's I/O context, so a
+        // handler/component reading getRequestContext() would otherwise
+        // throw. Same fix as the route-level/use-cache background
+        // revalidation paths. The rango.background span (kind=
+        // document-revalidation) wraps the re-render AND the store write so
+        // the task's spans — the re-run's own rango.* set and the drain/put
+        // platform spans — nest under one explanatory parent instead of
+        // dangling under the ended foreground phases. Running the put
+        // inside the ALS matches the MISS path, where putResponse already
+        // executes within the foreground request context. No visitor made
+        // the invalidations the re-run makes: the pass's fresh-reads
+        // writer is the sink's, which sets nothing. onError marks the
+        // re-run's errors `background`, the failure caught below included.
+        runBackground(requestCtx, () =>
+          runAsBackgroundWork(rerunCtx, async () => {
+            try {
+              await observePhase(
                 PHASES.background("document-revalidation"),
                 async () => {
                   const fresh = await next();
@@ -425,24 +426,20 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                     `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
                   );
                 },
-              ),
-            );
-          } catch (error) {
-            // The route now rewrites (route middleware): nothing to refresh
-            // this entry with.
-            if (isRewrite(error)) return;
-            // Pass requestCtx explicitly: this runs in a detached waitUntil task
-            // where the ALS context is gone, so onError only fires if we hand it
-            // the captured context (reportCacheError falls back to _getRequestContext
-            // otherwise, which is null here).
-            reportCacheError(
-              error,
-              "cache-write",
-              "[DocumentCache] revalidation",
-              requestCtx,
-            );
-          }
-        });
+              );
+            } catch (error) {
+              // The route now rewrites (route middleware): nothing to refresh
+              // this entry with.
+              if (isRewrite(error)) return;
+              reportCacheError(
+                error,
+                "cache-write",
+                "[DocumentCache] revalidation",
+                requestCtx,
+              );
+            }
+          }),
+        );
 
         return drainOnResponseCallbacks(
           addCacheStatusHeader(cached.response, "STALE"),

package/src/cache/read-through-swr.ts

@@ -117,29 +117,31 @@ export async function readThroughItem<T>(
       // span cover the write too (a slow or failing store write is part of
       // the revalidation, not an untraced tail). The foreground miss below
       // stays unwrapped: its context is already established.
+      // Reported inside the task, within wrapBackground's frame, so onError
+      // marks it `background`; rethrown so the span records the failure.
       const revalidateTask = async () => {
-        const fresh = await execute();
-        const serialized = await serialize(fresh);
-        if (serialized !== null) {
-          await setItem(key, serialized, storeOptions);
+        try {
+          const fresh = await execute();
+          const serialized = await serialize(fresh);
+          if (serialized !== null) {
+            await setItem(key, serialized, storeOptions);
+          }
+        } catch (error) {
+          reportCacheError(
+            error,
+            "stale-revalidation",
+            "[read-through] background revalidation",
+            host ?? undefined,
+          );
+          throw error;
         }
       };
       runBackground(
         host,
-        async () => {
-          try {
-            await (wrapBackground
-              ? wrapBackground(revalidateTask)
-              : revalidateTask());
-          } catch (error) {
-            reportCacheError(
-              error,
-              "stale-revalidation",
-              "[read-through] background revalidation",
-              host ?? undefined,
-            );
-          }
-        },
+        () =>
+          (wrapBackground ? wrapBackground(revalidateTask) : revalidateTask())
+            // Reported above.
+            .catch(() => {}),
         true,
       );
       return data;

package/src/cache/tag-invalidation.ts

@@ -36,11 +36,9 @@
  * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
  */
 
-import { AsyncLocalStorage } from "node:async_hooks";
 import {
   _getRequestContext,
-  runWithRequestContext,
-  type RequestContext,
+  isBackgroundWork,
 } from "../server/request-context.js";
 import { reportingAsync } from "./cache-error.js";
 import { normalizeTags } from "./cache-tag.js";
@@ -134,20 +132,6 @@ function warnPartialTagStore(fn: string, incapable: number): void {
   );
 }
 
-const backgroundRefresh = new AsyncLocalStorage<true>();
-
-/**
- * Run a stale entry's background refresh on the visitor's request context: a
- * "use cache" function's (cache-runtime.ts) or a cached loader's
- * (loader-cache.ts). No visitor made the invalidations in it, so they set no
- * fresh-reads cookie, as in a stale cache() HIT's re-render or a document
- * cache entry's re-run, whose passes take a sink's no-op writer
- * (server/render-pass.ts).
- */
-export function runAsBackgroundRefresh<T>(ctx: RequestContext, fn: () => T): T {
-  return runWithRequestContext(ctx, () => backgroundRefresh.run(true, fn));
-}
-
 /**
  * Set the fresh-reads cookie on this request's response for as long as the
  * invalidated stores' isolate memos can stay stale (isolate-tag-memo.ts), so
@@ -155,7 +139,8 @@ export function runAsBackgroundRefresh<T>(ctx: RequestContext, fn: () => T): T {
  */
 function markFreshReads(stores: SegmentCacheStore[]): void {
   const ctx = _getRequestContext();
-  if (!ctx?._setFreshReadsCookie || backgroundRefresh.getStore()) return;
+  // No visitor made an invalidation in background work (runAsBackgroundWork).
+  if (!ctx?._setFreshReadsCookie || isBackgroundWork()) return;
   let windowMs = 0;
   for (const store of stores) {
     windowMs = Math.max(windowMs, store.freshReadsWindowMs ?? 0);

package/src/router/error-handling.ts

@@ -8,6 +8,10 @@
 import { createElement, type ReactNode } from "react";
 import type { EntryData } from "../server/context.js";
 import { runIdentityExempt } from "../cache/cache-exec-scope.js";
+import {
+  _getRequestContext,
+  isBackgroundWork,
+} from "../server/request-context.js";
 import type {
   ResolvedSegment,
   ErrorInfo,
@@ -39,7 +43,7 @@ export interface InvokeOnErrorContext<TEnv = any> {
   isPartial?: boolean;
   handledByBoundary?: boolean;
   metadata?: Record<string, unknown>;
-  /** Request start time from performance.now() for duration calculation */
+  /** performance.now() at request entry; the request context's by default. */
   requestStartTime?: number;
 }
 
@@ -50,6 +54,12 @@ export interface InvokeOnErrorContext<TEnv = any> {
  * This is a shared utility used by both the router and RSC handler to ensure
  * consistent error callback behavior across the codebase.
  *
+ * `background` is set inside runAsBackgroundWork (server/request-context.ts),
+ * and `duration` and `env` come from the request context on the ALS
+ * (`_handlerStart`, `env`) when the call site leaves them out, so no call
+ * site has to know. A Prerender pass's ctx.env throws without buildEnv, so
+ * the walk never reads it eagerly.
+ *
  * @param onError - The onError callback to invoke (may be undefined)
  * @param error - The error that occurred
  * @param phase - The phase where the error occurred
@@ -66,9 +76,10 @@ export function invokeOnError<TEnv = any>(
   if (!onError) return;
 
   const errorObj = error instanceof Error ? error : new Error(String(error));
-  const duration = context.requestStartTime
-    ? performance.now() - context.requestStartTime
-    : undefined;
+  const reqCtx = _getRequestContext();
+  const background = isBackgroundWork() || undefined;
+  const start = context.requestStartTime ?? reqCtx?._handlerStart;
+  const duration = start !== undefined ? performance.now() - start : undefined;
 
   const errorContext: OnErrorContext<TEnv> = {
     error: errorObj,
@@ -84,10 +95,11 @@ export function invokeOnError<TEnv = any>(
     loaderName: context.loaderName,
     middlewareId: context.middlewareId,
     actionId: context.actionId,
-    env: context.env,
+    env: context.env ?? (reqCtx?.env as TEnv | undefined),
     duration,
     isPartial: context.isPartial,
-    handledByBoundary: context.handledByBoundary,
+    background,
+    handledByBoundary: background ? false : context.handledByBoundary,
     stack: errorObj.stack,
     metadata: context.metadata,
   };

package/src/router/intercept-resolution.ts

@@ -164,15 +164,16 @@ export function findInterceptForRoute(
 /**
  * An intercept handler's throw or notFound() renders the declaring entry's
  * boundary as the slot component (catchSegmentError, as for route handlers on
- * partial navigations: 500/404 status, onError "handler"). Responses rethrow.
- * The background re-render (`background`) reports the error the same way and
- * then rethrows it, so a failed re-render aborts its cache write instead of
- * storing the fallback.
+ * partial navigations: 500/404 status, onError "handler" naming the slot).
+ * Responses rethrow. The background re-render (`background`) reports the
+ * error the same way and then rethrows it, so a failed re-render aborts its
+ * cache write instead of storing the fallback.
  */
 function renderInterceptHandlerError<TEnv>(
   pass: ResolutionPass<TEnv>,
   error: unknown,
   parentEntry: EntryData,
+  slotSegmentId: string,
   background: boolean | undefined,
 ): ReactNode {
   if (error instanceof Response) throw error;
@@ -193,6 +194,7 @@ function renderInterceptHandlerError<TEnv>(
       telemetry,
     },
     pass.context.pathname,
+    { id: slotSegmentId, type: "parallel" },
   );
   if (background) throw error;
   return component;
@@ -363,6 +365,7 @@ export async function resolveInterceptEntry<TEnv>(
       pass,
       error,
       parentEntry,
+      slotSegmentId,
       options?.background,
     );
   }
@@ -402,6 +405,7 @@ export async function resolveInterceptEntry<TEnv>(
       context,
       routeKey: interceptEntry.routeName,
       params,
+      isPartial: true,
       recover: !options?.background,
     });
 
@@ -429,6 +433,7 @@ export async function resolveInterceptEntry<TEnv>(
           pass,
           error,
           parentEntry,
+          slotSegmentId,
           options?.background,
         );
       }

package/src/router/match-api.ts

@@ -514,6 +514,7 @@ export async function createMatchContextForPartial<TEnv>(
     clientSegmentIds: nav.clientSegmentIds,
     clientSegmentSet,
     stale: nav.stale,
+    heldBoundary: nav.heldBoundary,
     prevUrl: nav.prevUrl,
     prevParams: nav.prevParams,
     prevMatch: nav.prevMatch,

package/src/router/match-context.ts

@@ -136,6 +136,8 @@ export interface MatchContext<TEnv = any> {
   clientSegmentIds: string[];
   clientSegmentSet: Set<string>;
   stale: boolean;
+  /** NavigationSnapshot.heldBoundary: the walk stops above it. */
+  heldBoundary?: string;
 
   // Previous navigation state
   prevUrl: URL;
@@ -219,6 +221,7 @@ export function resolutionPassInput<TEnv>(
     routeKey: ctx.routeKey,
     actionContext: ctx.actionContext,
     stale: ctx.stale,
+    heldBoundary: ctx.heldBoundary,
   };
 }
 

package/src/router/match-middleware/background-revalidation.ts

@@ -113,7 +113,7 @@ import { getContext } from "../../server/context.js";
 import { executionStart } from "../../cache/tag-invalidation.js";
 import {
   createRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../../server/request-context.js";
 import { deriveRenderPass } from "../../server/render-pass.js";
@@ -141,8 +141,9 @@ import {
  * each field and why. The DSL store below has `metrics` unset too (track()
  * reads that one), so nothing lands on the foreground's perf timeline;
  * ctx.Store.run closes over ctx.Store, so the derived store needs its own run.
- * runWithRequestContext also re-establishes the request ALS, which a waitUntil
- * task on workerd loses; the DSL store is a different ALS (build context).
+ * runAsBackgroundWork also re-establishes the request ALS, which a waitUntil
+ * task on workerd loses, and marks the pass's onError reports `background`;
+ * the DSL store is a different ALS (build context).
  */
 export async function rerenderAndCacheRoute<TEnv>(
   ctx: MatchContext<TEnv>,
@@ -172,7 +173,7 @@ export async function rerenderAndCacheRoute<TEnv>(
       store.parent,
       fn,
     );
-  return runWithRequestContext(renderCtx, async () => {
+  return runAsBackgroundWork(renderCtx, async () => {
     const handlerContext = routerCtx.createHandlerContext(
       ctx.matched.params,
       ctx.request,

package/src/router/match-middleware/cache-lookup.ts

@@ -431,13 +431,15 @@ async function* serveStoredSegments<TEnv>(
   // route is the same case, served from the overlay first (an overlay entry
   // is newer than the build one, and may be the only one). Passthrough
   // routes keep a liveHandler, so a live render (rendersLive) re-renders
-  // them fresh. A thrown action's boundary pass walks live too
-  // (ActionContext.boundary).
+  // them fresh. A pass cut at an error boundary walks live too
+  // (ActionContext.boundary, a follow-up's held one): the evicted handler is
+  // under the cut.
   if (
     (prerenderStoreShortCircuits(ctx.matched.pr, ctx.request) ||
       overlayEligible) &&
     (!rendersLive(ctx) || !isPassthroughPrerenderRoute) &&
-    !ctx.actionContext?.boundary
+    !ctx.actionContext?.boundary &&
+    !ctx.heldBoundary
   ) {
     await ensurePrerenderDeps();
     stored = await readPrerenderSource(

package/src/router/navigation-snapshot.ts

@@ -18,6 +18,13 @@ export interface NavigationSnapshot {
   filteredSegmentIds: string[];
 
   stale: boolean;
+  /**
+   * The id of an action's error boundary on screen that a stale request holds
+   * (`_rsc_boundary`, the action follow-up): read only beside `stale`, so it
+   * has every stale guarantee (a live render, no route-cache or document-cache
+   * read or store, no PPR replay).
+   */
+  heldBoundary?: string;
 
   isSameRouteNavigation: boolean;
 
@@ -136,6 +143,8 @@ export async function resolveNavigation(
   const clientSegmentIds =
     url.searchParams.get(WIRE.segments)?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get(WIRE.stale) === "true";
+  const heldBoundary =
+    (stale && url.searchParams.get(WIRE.boundary)) || undefined;
   const previousUrl = getNavigationContextHeader(request, url.origin);
   const interceptSourceUrl = getInterceptSourceHeader(request);
   const isHmr = !!requestHeaders(request).get("X-RSC-HMR");
@@ -198,6 +207,7 @@ export async function resolveNavigation(
     clientSegmentSet,
     filteredSegmentIds,
     stale,
+    heldBoundary,
     isSameRouteNavigation,
     effectiveFromUrl,
     effectiveFromMatch,

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

@@ -204,15 +204,49 @@ export interface ErrorReportContext {
   routeKey?: string;
   env?: any;
   isPartial?: boolean;
-  requestStartTime?: number;
   telemetry?: TelemetrySink;
 }
 
+type Thrower = { id: string; type: ErrorInfo["segmentType"] };
+
+/**
+ * Note that `id` threw `error`, for an error its owning entry's boundary
+ * catches (a parallel slot's sync throw, an orphan layout's): onError names
+ * the segment that threw, as a streamed slot's rejection does. Kept on the
+ * request context, never the module: a reused error object (a constant, a
+ * memoized rejection) can be thrown by another request, or by a Prerender
+ * pass that rethrows before catchSegmentError reads it. Returns `error`, to
+ * rethrow.
+ */
+export function noteThrower(
+  error: unknown,
+  id: string,
+  type: ErrorInfo["segmentType"],
+): unknown {
+  const reqCtx = _getRequestContext();
+  if (reqCtx && error !== null && typeof error === "object") {
+    (reqCtx._throwers ??= new WeakMap()).set(error, { id, type });
+  }
+  return error;
+}
+
+/** The segment noteThrower recorded for `error`, read once. */
+function takeThrower(error: unknown): Thrower | undefined {
+  const throwers = _getRequestContext()?._throwers;
+  if (!throwers || error === null || typeof error !== "object") return;
+  const noted = throwers.get(error) as Thrower | undefined;
+  throwers.delete(error);
+  return noted;
+}
+
 /**
  * Handle a caught error during segment resolution by creating an
  * error or not-found segment with the nearest boundary.
  *
  * Called by resolveWithErrorBoundary to produce error/notFound segments.
+ * `entry` is where the boundary is looked up; `thrower` names the segment
+ * that threw when it is not `entry` (an intercept's slot, under its declaring
+ * entry), for the report, the server print and the client's ErrorInfo.
  */
 export function catchSegmentError<TEnv>(
   error: unknown,
@@ -221,7 +255,11 @@ export function catchSegmentError<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   report?: ErrorReportContext,
   pathname?: string,
+  thrower?: Thrower,
 ): ResolvedSegment {
+  const named = thrower ?? takeThrower(error);
+  const segmentId = named?.id ?? entry.shortCode;
+  const segmentType: ErrorInfo["segmentType"] = named?.type ?? entry.type;
   const reportError = (
     handledByBoundary: boolean,
     metadata?: Record<string, unknown>,
@@ -232,13 +270,12 @@ export function catchSegmentError<TEnv>(
       url: report.url,
       routeKey: report.routeKey,
       params,
-      segmentId: entry.shortCode,
-      segmentType: entry.type as any,
+      segmentId,
+      segmentType: segmentType as any,
       env: report.env,
       isPartial: report.isPartial,
       handledByBoundary,
       metadata,
-      requestStartTime: report.requestStartTime,
     });
     if (report.telemetry) {
       const errorObj =
@@ -247,8 +284,8 @@ export function catchSegmentError<TEnv>(
         type: "handler.error",
         timestamp: performance.now(),
         requestId: report.request ? getRequestId(report.request) : undefined,
-        segmentId: entry.shortCode,
-        segmentType: entry.type,
+        segmentId,
+        segmentType,
         error: errorObj,
         handledByBoundary,
         pathname,
@@ -274,8 +311,8 @@ export function catchSegmentError<TEnv>(
 
     const notFoundInfo = createNotFoundInfo(
       error,
-      entry.shortCode,
-      entry.type,
+      segmentId,
+      segmentType,
       pathname,
     );
 
@@ -285,7 +322,7 @@ export function catchSegmentError<TEnv>(
     });
 
     debugLog("segment", "notFound boundary handled error", {
-      segmentId: entry.shortCode,
+      segmentId,
       message: notFoundInfo.message,
     });
 
@@ -302,19 +339,18 @@ export function catchSegmentError<TEnv>(
   // The client gets the masked ErrorInfo; the original prints here.
   printServerError(
     error,
-    { label: "Handler error", name: entry.shortCode, pathname },
+    { label: "Handler error", name: segmentId, pathname },
     _getRequestContext(),
   );
 
   const fallback = deps.findNearestErrorBoundary(entry);
-  const segmentType: ErrorInfo["segmentType"] = entry.type;
-  const errorInfo = createErrorInfo(error, entry.shortCode, segmentType);
+  const errorInfo = createErrorInfo(error, segmentId, segmentType);
   const effectiveFallback = fallback ?? DefaultErrorFallback;
 
   reportError(!!effectiveFallback);
 
   debugLog("segment", "error boundary handled error", {
-    segmentId: entry.shortCode,
+    segmentId,
     boundary: fallback ? "custom" : "default",
     message: errorInfo.message,
   });