@rangojs/router 0.28.0 → 0.29.0

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

@@ -72,6 +72,7 @@ import { runIdentityExempt } from "../../cache/cache-exec-scope.js";
 import {
   getRequestContext,
   _getRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../../server/request-context.js";
 import { observePhase, PHASES } from "../instrument.js";
@@ -92,7 +93,6 @@ import { isWarmReplace, noteWarmWrite } from "../../prerender/warm-request.js";
 import {
   executionStart,
   predatesInvalidation,
-  runAsBackgroundRefresh,
 } from "../../cache/tag-invalidation.js";
 import {
   maskNestedContainerThenables,
@@ -815,10 +815,11 @@ function executeLoaderData<TEnv>(
       // under the ended foreground phases. Inside the request context so
       // observePhase can read tracing on workerd (ALS detaches in waitUntil).
       // No visitor made the invalidations it runs: they set no fresh-reads
-      // cookie (runAsBackgroundRefresh).
+      // cookie, and onError marks its errors `background`
+      // (runAsBackgroundWork).
       wrapBackground: (run) => {
         revalidating = true;
-        return runAsBackgroundRefresh(requestCtxForExecute, () =>
+        return runAsBackgroundWork(requestCtxForExecute, () =>
           observePhase(PHASES.background("loader-revalidation"), run),
         );
       },

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

@@ -51,6 +51,8 @@ export interface ResolutionPassInput<TEnv = any> {
   readonly routeKey: string;
   readonly actionContext?: ActionContext;
   readonly stale?: boolean;
+  /** NavigationSnapshot.heldBoundary: the walk cuts there, sending no segment. */
+  readonly heldBoundary?: string;
   /**
    * No loader is started and no loader segment is emitted: build time
    * (prerender-match.ts) and the background re-render of a route record

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

@@ -62,6 +62,7 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
   buildLoaderErrorContext,
+  noteThrower,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { isLayoutLoaderCopy } from "../../client-urls/layout-loader-copies.js";
@@ -801,28 +802,34 @@ async function resolveParallelSlotComponent<TEnv>(
               handler,
               slotContext,
             );
-      if (hasLoadingFallback) {
-        const result = run();
-        if (result instanceof Promise) {
-          warnOnStreamedResponse(result, parallelId);
-          result.finally(doneHandler).catch(() => {});
-          component = trackStreamedHandler(deps, result, {
-            boundaryEntry,
-            segmentId: parallelId,
-            segmentType: "parallel",
-            context,
-            routeKey,
-            params,
-            recover: !pass.throwOnError,
-          });
+      // A throw before the slot streams reaches the owning entry's boundary.
+      try {
+        if (hasLoadingFallback) {
+          const result = run();
+          if (result instanceof Promise) {
+            warnOnStreamedResponse(result, parallelId);
+            result.finally(doneHandler).catch(() => {});
+            component = trackStreamedHandler(deps, result, {
+              boundaryEntry,
+              segmentId: parallelId,
+              segmentType: "parallel",
+              context,
+              routeKey,
+              params,
+              isPartial: reportsPartial(pass),
+              recover: !pass.throwOnError,
+            });
+          } else {
+            doneHandler();
+            component = result as ReactNode;
+          }
         } else {
+          // A static value (a Promise included) goes to render as is.
+          component = typeof handler === "function" ? await run() : handler;
           doneHandler();
-          component = result as ReactNode;
         }
-      } else {
-        // A static value (a Promise included) goes to render as is.
-        component = typeof handler === "function" ? await run() : handler;
-        doneHandler();
+      } catch (error) {
+        throw noteThrower(error, parallelId, "parallel");
       }
     }
   }
@@ -1180,6 +1187,7 @@ async function resolveRouteComponent<TEnv>(
           context,
           routeKey,
           params,
+          isPartial: reportsPartial(pass),
           recover: !pass.throwOnError,
         }),
       };
@@ -1504,6 +1512,9 @@ export async function resolveOrphanLayout<TEnv>(
       const doneHandler = track(`handler:${orphan.id}`, 2);
       try {
         component = await resolveLayoutComponent(orphan, context);
+      } catch (error) {
+        // Its owning entry's boundary catches it.
+        throw noteThrower(error, orphan.shortCode, orphan.type);
       } finally {
         internal._currentSegmentId = pinned;
       }
@@ -1598,6 +1609,15 @@ export interface RevalidatingWalkOptions {
   readonly chain?: readonly EntryData[];
 }
 
+/**
+ * The onError `isPartial` of an error the walk catches. FRESH: a full match
+ * reports it unset. A re-render a navigation started reports it true
+ * (partialRequest).
+ */
+function reportsPartial(pass: ResolutionPass<any>): true | undefined {
+  return pass.client !== FRESH || pass.partialRequest ? true : undefined;
+}
+
 /** An entry's error or not-found segment, as its whole result. */
 function boundaryResult(seg: ResolvedSegment): SegmentRevalidationResult {
   return { segments: [seg], matchedIds: [seg.id] };
@@ -1633,14 +1653,12 @@ export async function resolveAllSegments<TEnv>(
   try {
     telemetry = getRouterContext()?.telemetry;
   } catch {}
-  // FRESH: a full match reports an entry's error without isPartial, and a
-  // build-time pass rethrows it (throwOnError). A re-render a navigation
-  // started reports it with isPartial (partialRequest).
+  // A build-time pass rethrows an entry's error (throwOnError).
   const report = {
     request,
     url: context.url,
     routeKey,
-    isPartial: pass.client !== FRESH || pass.partialRequest ? true : undefined,
+    isPartial: reportsPartial(pass),
     telemetry,
   };
   const fillMatch = {
@@ -1650,16 +1668,19 @@ export async function resolveAllSegments<TEnv>(
   };
 
   const boundary = pass.actionContext?.boundary;
-  const boundaryId = boundary?.id;
+  const cutId = boundary?.id ?? pass.heldBoundary;
+  let cut = false;
   for (const entry of entries) {
-    if (entry.shortCode === boundaryId) {
+    if (entry.shortCode === cutId) {
       // The outlet's loader ids stay claimed. _handlerRan makes the browser
-      // clear the outlet's handle values.
-      allSegments.push({ ...boundary!, _handlerRan: true });
-      matchedIds.push(boundaryId);
+      // clear the outlet's handle values. A held boundary sends no segment:
+      // the client keeps its own, with its handle values.
+      if (boundary) allSegments.push({ ...boundary, _handlerRan: true });
+      matchedIds.push(cutId);
       entry.loader?.forEach((loaderEntry, i) =>
         matchedIds.push(`${entry.shortCode}D${i}.${loaderEntry.loader.$$id}`),
       );
+      cut = true;
       break;
     }
     if (entry.type === "route" && interceptResult) {
@@ -1721,6 +1742,14 @@ export async function resolveAllSegments<TEnv>(
     }
   }
 
+  // A held boundary that names no entry (HMR rewrote the routes since the
+  // page rendered): the page renders whole, as without one.
+  if (pass.heldBoundary && !cut && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[@rangojs/router] A refetch held the error boundary "${pass.heldBoundary}", ` +
+        `which is not on the route's chain (${routeKey}): the page renders whole.`,
+    );
+  }
   deliverStartedLoaders(context, allSegments);
   return { segments: allSegments, matchedIds };
 }

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

@@ -44,6 +44,8 @@ export interface StreamedHandlerOptions<TEnv> {
   context: HandlerContext<any, TEnv>;
   routeKey?: string;
   params: Record<string, string>;
+  /** onError's `isPartial`, as the walk reports a sync handler's error. */
+  isPartial: true | undefined;
   /** False where the rejection must reach the caller (prerender, intercept background re-render). */
   recover: boolean;
 }
@@ -64,6 +66,7 @@ export function trackStreamedHandler<TEnv>(
   const tracked = deps.trackHandler(result as Promise<ReactNode>, {
     segmentId,
     segmentType,
+    isPartial: options.isPartial,
   });
   observeStreamedHandler(
     tracked,

package/src/router/types.ts

@@ -57,7 +57,6 @@ export interface SegmentResolutionDeps<TEnv = any> {
       params?: Record<string, string>;
       env?: TEnv;
       isPartial?: boolean;
-      requestStartTime?: number;
     },
     /** An `ssr: false` loader on a document or capture render. */
     useDefaultErrorBoundary?: boolean,
@@ -67,6 +66,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
     errorContext?: {
       segmentId?: string;
       segmentType?: string;
+      isPartial?: boolean;
     },
   ) => Promise<T>;
   findNearestErrorBoundary: (

package/src/router.ts

@@ -44,6 +44,7 @@ import { createHandleStore, type HandleStore } from "./server/handle-store.js";
 import {
   getRequestContext,
   _getRequestContext,
+  reportedErrorsOf,
 } from "./server/request-context.js";
 import type {
   ErrorPhase,
@@ -315,7 +316,8 @@ export function createRouter<TEnv = any>(
    * Wrapper for invokeOnError that binds the router's onError callback.
    * Uses the shared utility from router/error-handling.ts for consistent behavior.
    *
-   * Deduplicates via per-request WeakSet stored on the ALS request context.
+   * Deduplicates via per-request WeakSet stored on the ALS request context
+   * (background work keeps its own, reportedErrorsOf).
    * A closure-level WeakSet would silently swallow errors if the same object
    * instance is thrown across separate requests (e.g. a singleton error).
    */
@@ -325,7 +327,8 @@ export function createRouter<TEnv = any>(
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
     if (error != null && typeof error === "object") {
-      const reportedErrors = _getRequestContext()?._reportedErrors;
+      const reqCtx = _getRequestContext();
+      const reportedErrors = reqCtx && reportedErrorsOf(reqCtx);
       if (reportedErrors) {
         if (reportedErrors.has(error)) return;
         reportedErrors.add(error);
@@ -488,6 +491,7 @@ export function createRouter<TEnv = any>(
     errorContext?: {
       segmentId?: string;
       segmentType?: string;
+      isPartial?: boolean;
     },
   ): Promise<T> => {
     // One ALS read serves both the store lookup and the onError closure.
@@ -520,6 +524,7 @@ export function createRouter<TEnv = any>(
           env: reqCtx.env as TEnv,
           segmentId: errorContext?.segmentId,
           segmentType: errorContext?.segmentType as any,
+          isPartial: errorContext?.isPartial,
           handledByBoundary: true,
         });
       });
@@ -542,7 +547,6 @@ export function createRouter<TEnv = any>(
       params?: Record<string, string>;
       env?: TEnv;
       isPartial?: boolean;
-      requestStartTime?: number;
     },
     useDefaultErrorBoundary?: boolean,
   ): Promise<LoaderDataResult<T>> {
@@ -592,7 +596,6 @@ export function createRouter<TEnv = any>(
               env: errorContext.env,
               isPartial: errorContext.isPartial,
               handledByBoundary: ctx.handledByBoundary,
-              requestStartTime: errorContext.requestStartTime,
             });
             if (emitTelemetry) {
               const errorObj =

package/src/rsc/request-stages.ts

@@ -22,6 +22,7 @@ import type { MiddlewareEntry } from "../router/middleware-types.js";
 import {
   _getRequestContext,
   getRequestContext,
+  reportedErrorsOf,
   setRequestContextParams,
   type RequestContext,
 } from "../server/request-context.js";
@@ -158,8 +159,9 @@ export function createErrorReporter<TEnv>(router: {
     // case — the error is from a cancelled stream, not a real failure.
     const reqCtx = _getRequestContext();
     if (error != null && typeof error === "object" && reqCtx) {
-      if (reqCtx._reportedErrors.has(error)) return;
-      reqCtx._reportedErrors.add(error);
+      const reportedErrors = reportedErrorsOf(reqCtx);
+      if (reportedErrors.has(error)) return;
+      reportedErrors.add(error);
     }
     invokeOnError(router.onError, error, phase, context, "RSC");
   };

package/src/rsc/shell-capture.ts

@@ -48,6 +48,7 @@ import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import type { TraceSpan } from "../router/tracing.js";
 import {
+  runAsBackgroundWork,
   runWithRequestContext,
   setRequestContextParams,
   UNTRACKED_BACKGROUND_TASK,
@@ -1279,69 +1280,73 @@ export function planShellCapture(input: ShellCaptureInput): void {
   // (observed in production: ~24s of zero I/O before capture start).
   // observePhase reads tracing off the ALS context captured when runBackground
   // registered the task — the foreground request context, tracing intact.
+  // onError marks every error of the capture `background`, the task's own
+  // failure (captureTask's catch) included.
   const serializedTask = async () => {
-    await observePhase(PHASES.background("shell-capture"), async (span) => {
-      span.setAttribute("rango.shell_key", key);
-      // A production page can enqueue several navigation-only captures through
-      // viewport prefetching. Let a later document MISS overtake that queued
-      // speculative work so it can become a shell HIT before the 15s queue
-      // budget expires. Never preempts the active capture. Priority and the
-      // backlog ahead at enqueue ride the span (and the skip event below), so
-      // a skip-queue-timeout diagnoses itself instead of needing a trace dive.
-      const queuePriority = descriptor.navigationOnly
-        ? ("navigation" as const)
-        : ("document" as const);
-      const depths = captureQueueDepths();
-      const queueAhead =
-        (depths.running ? 1 : 0) +
-        depths.document +
-        (queuePriority === "navigation" ? depths.navigation : 0);
-      span.setAttribute("rango.background.queue_priority", queuePriority);
-      span.setAttribute("rango.background.queue_ahead", queueAhead);
-      const queueStart = performance.now();
-      try {
-        await enqueueSerializedCapture(
-          () => {
+    await runAsBackgroundWork(reqCtx, () =>
+      observePhase(PHASES.background("shell-capture"), async (span) => {
+        span.setAttribute("rango.shell_key", key);
+        // A production page can enqueue several navigation-only captures through
+        // viewport prefetching. Let a later document MISS overtake that queued
+        // speculative work so it can become a shell HIT before the 15s queue
+        // budget expires. Never preempts the active capture. Priority and the
+        // backlog ahead at enqueue ride the span (and the skip event below), so
+        // a skip-queue-timeout diagnoses itself instead of needing a trace dive.
+        const queuePriority = descriptor.navigationOnly
+          ? ("navigation" as const)
+          : ("document" as const);
+        const depths = captureQueueDepths();
+        const queueAhead =
+          (depths.running ? 1 : 0) +
+          depths.document +
+          (queuePriority === "navigation" ? depths.navigation : 0);
+        span.setAttribute("rango.background.queue_priority", queuePriority);
+        span.setAttribute("rango.background.queue_ahead", queueAhead);
+        const queueStart = performance.now();
+        try {
+          await enqueueSerializedCapture(
+            () => {
+              span.setAttribute(
+                "rango.background.queue_wait_ms",
+                Math.round(performance.now() - queueStart),
+              );
+              return captureTask(span);
+            },
+            { priority: queuePriority },
+          );
+        } catch (error) {
+          if (error instanceof CaptureQueueFullError) {
+            releaseCaptureGuard(key, guardToken);
+            span.setAttribute("rango.background.outcome", "skip-capacity");
+            publishCaptureDebugEvent(descriptor, {
+              key,
+              outcome: "skip-capacity",
+            });
+            return;
+          }
+          if (error instanceof CaptureQueueWaitTimeoutError) {
+            // Dropped unrun after waiting past the queue budget: no backoff (the
+            // route is not doomed, the isolate was busy) — a later request
+            // re-probes the key.
+            releaseCaptureGuard(key, guardToken);
+            span.setAttribute("rango.background.outcome", "skip-queue-timeout");
             span.setAttribute(
               "rango.background.queue_wait_ms",
-              Math.round(performance.now() - queueStart),
+              Math.round(error.waitedMs),
             );
-            return captureTask(span);
-          },
-          { priority: queuePriority },
-        );
-      } catch (error) {
-        if (error instanceof CaptureQueueFullError) {
-          releaseCaptureGuard(key, guardToken);
-          span.setAttribute("rango.background.outcome", "skip-capacity");
-          publishCaptureDebugEvent(descriptor, {
-            key,
-            outcome: "skip-capacity",
-          });
-          return;
-        }
-        if (error instanceof CaptureQueueWaitTimeoutError) {
-          // Dropped unrun after waiting past the queue budget: no backoff (the
-          // route is not doomed, the isolate was busy) — a later request
-          // re-probes the key.
-          releaseCaptureGuard(key, guardToken);
-          span.setAttribute("rango.background.outcome", "skip-queue-timeout");
-          span.setAttribute(
-            "rango.background.queue_wait_ms",
-            Math.round(error.waitedMs),
-          );
-          publishCaptureDebugEvent(descriptor, {
-            key,
-            outcome: "skip-queue-timeout",
-            queueWaitMs: Math.round(error.waitedMs),
-            queuePriority,
-            queueAhead,
-          });
-          return;
+            publishCaptureDebugEvent(descriptor, {
+              key,
+              outcome: "skip-queue-timeout",
+              queueWaitMs: Math.round(error.waitedMs),
+              queuePriority,
+              queueAhead,
+            });
+            return;
+          }
+          throw error;
         }
-        throw error;
-      }
-    });
+      }),
+    );
   };
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),

package/src/server/request-context.ts

@@ -833,6 +833,13 @@ export interface RequestContext<
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
+  /**
+   * @internal The segment a parallel slot's or orphan layout's error came
+   * from, for the owning entry's catch (segment-resolution/helpers.ts
+   * noteThrower). Per request: an error object can be thrown by several.
+   */
+  _throwers?: WeakMap<object, { id: string; type: string }>;
+
   /**
    * @internal The errors this request printed to the server console, so a
    * failure prints once where it originated (server/print-server-error.ts). A derived context shares it through the prototype.
@@ -1005,6 +1012,7 @@ export type PublicRequestContext<
   | "_inActionRevalidation"
   | "_actionRan"
   | "_reportedErrors"
+  | "_throwers"
   | "_printedErrors"
   | "_renderErrors"
   | "_recoveredHandlerErrors"
@@ -1140,6 +1148,46 @@ export function runWithRequestContext<TEnv, T>(
   return requestContextStorage.run(context, fn);
 }
 
+/** Inside background work: the errors its onError reports named. */
+const backgroundWork = new AsyncLocalStorage<WeakSet<object>>();
+
+/**
+ * Run work whose output goes only to a cache, never to the response of the
+ * request that started it, on `context`: a stale entry's refresh (a "use
+ * cache" function, a cached loader, a cache() record, a document), a
+ * navigation's proactive cache() write, a PPR shell capture. No visitor made
+ * the invalidations in it, so they set no fresh-reads cookie
+ * (cache/tag-invalidation.ts), and onError marks every error reported inside
+ * it `background` (router/error-handling.ts invokeOnError). Its failure is
+ * reported inside it too: a catch outside runs on the visitor's frame.
+ */
+export function runAsBackgroundWork<TEnv, T>(
+  context: RequestContext<TEnv>,
+  fn: () => T,
+): T {
+  const reported = backgroundWork.getStore() ?? new WeakSet<object>();
+  return requestContextStorage.run(context, () =>
+    backgroundWork.run(reported, fn),
+  );
+}
+
+/** Whether the caller runs inside runAsBackgroundWork. */
+export function isBackgroundWork(): boolean {
+  return backgroundWork.getStore() !== undefined;
+}
+
+/**
+ * The set onError's dedupe records a reported error in. Background work keeps
+ * its own: an error object both the visitor's render and background work
+ * reach (a memoized rejection, a thrown constant) is reported by each, so a
+ * background report never takes the place of the visitor's.
+ */
+export function reportedErrorsOf(
+  context: RequestContext<any>,
+): WeakSet<object> {
+  return backgroundWork.getStore() ?? context._reportedErrors;
+}
+
 /**
  * Get the current request context
  * Throws if called outside of a request context
@@ -1745,6 +1793,7 @@ export function createRequestContext<TEnv>(
     _locationState: undefined,
 
     _reportedErrors: new WeakSet<object>(),
+    _throwers: undefined,
     _printedErrors: new WeakSet<object>(),
     _renderErrors: [],
     _metricsStore: undefined,

package/src/testing/dispatch.ts

@@ -345,6 +345,9 @@ export async function dispatch<TEnv = any>(
     cacheProfiles: router.cacheProfiles,
     versions,
   });
+  // The request's start, as the production handler sets it: onError's
+  // `duration` counts from here.
+  requestContext._handlerStart = performance.now();
   // Cache degradation (reportCacheError -> _reportBackgroundError) reaches the
   // router's onError, as in the production handler.
   stages.reportBackgroundErrors(requestContext, req, url, ctx.callOnError);