@rangojs/router 0.27.0 → 0.29.0

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,
   });

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

@@ -72,7 +72,7 @@ import { runIdentityExempt } from "../../cache/cache-exec-scope.js";
 import {
   getRequestContext,
   _getRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../../server/request-context.js";
 import { observePhase, PHASES } from "../instrument.js";
@@ -458,8 +458,8 @@ function recordOwnerKey(cachedLoaderId: string): () => string {
  * PPR loader lane rule — the canonical source statement; other sites point
  * here (consumer docs: skills/ppr/SKILL.md "The loader lane rule";
  * docs/design/loader-container-bake.md). This is the single funnel every
- * loader segment path routes through (fresh resolveLoaders, cache-hit
- * resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation, and
+ * loader segment path routes through (resolveOwnerLoaders: the full match's
+ * FRESH pass, cache-hit and revalidation resolveLoadersOnly, and
  * intercept loaders in intercept-resolution.ts, which pass no bake key and
  * never run under a shell capture), so the lane is decided here, per LOADER,
  * never by the entry's loading():
@@ -473,7 +473,7 @@ function recordOwnerKey(cachedLoaderId: string): () => string {
  *   plain objects, arrays and JSX props are masked (mask-nested.ts) and stay
  *   live holes at the consumer's own Suspense — per-request material must be
  *   promise-shaped (the #692 cross-session scar). The masked container
- *   registers on `_shellCaptureLoaderRecords`: it holds the capture gate
+ *   registers on `_shellCaptureState.loaderRecords`: it holds the capture gate
  *   (bounded by `ppr.captureTimeout`) and pins into the snapshot's loader
  *   family, and on a HIT the recorded container is overlaid onto the fresh
  *   run (below) so the payload matches the frozen prelude outside the holes.
@@ -511,7 +511,10 @@ export function resolveLoaderData<TEnv>(
         maskNestedContainerThenables(container),
       );
       maskedPromise.catch(() => {});
-      reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+      reqCtx?._shellCaptureState?.loaderRecords.set(
+        bakeSegmentKey,
+        maskedPromise,
+      );
       // Its data bakes into the shell, so its tags tag the shell.
       linkLoaderTagsTo(SHELL_BAKE_TAG_OWNER, loaderEntry.loader.$$id, reqCtx);
       return maskedPromise;
@@ -629,14 +632,14 @@ function executeLoaderData<TEnv>(
 
   // Dedup the cache read-through across repeated resolutions of the SAME
   // loaderId in one request. An orphan layout with parallel slots inherits its
-  // parent route's loaders, so resolveOrphanLayout (fresh.ts) re-resolves the
+  // parent route's loaders, so resolveOrphanLayout re-resolves the
   // parent's loaders under a different shortCode — calling resolveLoaderData
   // again for the same loaderId. The cache key (loader:{loaderId}:{host}
   // {pathname}:{sortedParams}) does not include the shortCode and ctx/params
   // are identical, so both resolutions produce the same data. Reuse the already
   // in-flight dataPromise instead of issuing a second getItem/setItem (e.g. a
   // second KV round-trip) for one logical cached loader. The shortCode only
-  // affects the emitted segmentId in resolveLoaders, not the cached value.
+  // affects the emitted segmentId in resolveOwnerLoaders, not the cached value.
   const existing = overrides.get(loaderId);
   if (existing) return existing;
 
@@ -809,11 +812,14 @@ function executeLoaderData<TEnv>(
       // (read-through-swr routes the full task through wrapBackground) — so
       // the loader's rango.loader span, its fetch/KV platform spans, and the
       // store write all nest under one explanatory parent instead of dangling
-      // under the ended foreground phases. Inside runWithRequestContext so
+      // 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, and onError marks its errors `background`
+      // (runAsBackgroundWork).
       wrapBackground: (run) => {
         revalidating = true;
-        return runWithRequestContext(requestCtxForExecute, () =>
+        return runAsBackgroundWork(requestCtxForExecute, () =>
           observePhase(PHASES.background("loader-revalidation"), run),
         );
       },

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

@@ -7,11 +7,11 @@
  * consuming Suspense subtree postpones as a hole, and the serve pass runs them
  * fresh into it.
  *
- * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
+ * Capture mode is signalled by `requestCtx._shellCaptureState.run`, set ONLY on
  * the derived request context of the background capture task (shell-capture.ts);
- * the foreground render never sets it. This module is the single home for the
+ * the foreground render never has it. This module is the single home for the
  * mask so every loader execution site gates the same way (loader-cache.ts
- * `resolveLoaderData`, fresh.ts `resolveLoaders`).
+ * `resolveLoaderData`, revalidation.ts `resolveOwnerLoaders`).
  */
 
 import {
@@ -22,7 +22,7 @@ import { isRenderableLoading } from "../../types/boundaries.js";
 
 /**
  * True when the current render is the active PPR shell capture and route loaders
- * must be masked rather than executed. Reads `_shellCaptureRun` off the ALS
+ * must be masked rather than executed. Reads `_shellCaptureState` off the ALS
  * request context (the capture task re-establishes its derived context via
  * runWithRequestContext), so it is accurate at the loader resolution sites, which
  * run synchronously inside the pipeline's context frame.
@@ -30,7 +30,7 @@ import { isRenderableLoading } from "../../types/boundaries.js";
 export function isShellCaptureActive(
   reqCtx: RequestContext<any> | undefined = _getRequestContext(),
 ): boolean {
-  return reqCtx?._shellCaptureRun === true;
+  return reqCtx?._shellCaptureState?.run === true;
 }
 
 // createMaskedLoaderPromise lives in the leaf module mask-nested.ts, beside

package/src/router/segment-resolution/prefetch-deferral.ts

@@ -36,7 +36,8 @@ import {
 import { requestHeaders } from "../../server/request-headers.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import type { CacheScope } from "../../cache/cache-scope.js";
-import { FILL_PARAM, PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { WIRE } from "../../wire-params.js";
 import { isInterceptSegment } from "../../browser/intercept-utils.js";
 
 /**
@@ -50,7 +51,7 @@ export function requestKind(
   request: Request,
   rawUrl: URL,
 ): "prefetch" | "fill" | undefined {
-  if (rawUrl.searchParams.has(FILL_PARAM)) return "fill";
+  if (rawUrl.searchParams.has(WIRE.fill)) return "fill";
   return requestHeaders(request).has(PREFETCH_HEADER) ? "prefetch" : undefined;
 }
 
@@ -114,14 +115,6 @@ export interface PrefetchDeferral {
    * a navigation to the page lists.
    */
   below?: true;
-  /**
-   * The loaders this prefetch deferred, by `$$id` (registerDeferredLoader).
-   * A deferred loader runs only if something reads it: a handler's or another
-   * loader's ctx.use() starts it through its registration
-   * (startDeferredLoader), and revalidation.ts deliverStartedLoaders delivers
-   * what was started by the end of resolution.
-   */
-  deferredLoaders?: Map<string, DeferredLoader>;
 }
 
 /**
@@ -149,7 +142,14 @@ export interface RecordUse {
   readonly refresh: boolean;
 }
 
-/** A loader this prefetch deferred: PrefetchDeferral.deferredLoaders. */
+/**
+ * A DSL loader registered and not started (InternalHandlerContext
+ * ._deferredLoaders): a prefetch deferred it, or a pass that skips loaders
+ * (`skipLoaders`) did not run it. It runs only if something reads it: a
+ * handler's or another loader's ctx.use() starts it through its registration
+ * (startDeferredLoader), and revalidation.ts deliverStartedLoaders delivers
+ * what a prefetch started by the end of resolution.
+ */
 export interface DeferredLoader {
   /**
    * The segment that registers it. Its run files its handle pushes there,
@@ -232,7 +232,7 @@ export function resolveDeferralScope(
       loaderIds.add(loaderEntry.loader.$$id);
     }
     for (const parallelEntry of getParallelEntries(entry.parallel)) {
-      // A slot's segment id, as resolveParallelSegmentsWithRevalidation
+      // A slot's segment id, as resolveParallelSegments
       // (revalidation.ts) forms it.
       const slotIds = flagsLoading(parallelEntry)
         ? getParallelSlotEntries(entry.parallel)
@@ -245,7 +245,7 @@ export function resolveDeferralScope(
     for (const orphan of entry.layout) {
       if (chain.has(orphan)) continue;
       // An orphan layout's handler is awaited after its owner's ran
-      // (revalidation.ts resolveOrphanLayoutWithRevalidation): never a unit,
+      // (revalidation.ts resolveOrphanLayout): never a unit,
       // its loaders are still behind its fallback.
       collect(
         orphan,
@@ -446,8 +446,8 @@ export function recordUse(
 }
 
 /**
- * Register a loader this prefetch deferred, with the segment that registers
- * it and how to start it there (PrefetchDeferral.deferredLoaders). The first
+ * Register a loader resolution does not start, with the segment that
+ * registers it and how to start it there (DeferredLoader). The first
  * registration wins, as the loader's one run per request does.
  */
 export function registerDeferredLoader(
@@ -456,18 +456,21 @@ export function registerDeferredLoader(
   owner: string,
   start: () => Promise<unknown>,
 ): void {
-  const plan = getPrefetchDeferral(ctx);
-  if (plan && !plan.deferredLoaders?.has(loaderId)) {
-    (plan.deferredLoaders ??= new Map()).set(loaderId, { owner, start });
+  const internal = ctx as InternalHandlerContext<any, any>;
+  if (!internal._deferredLoaders?.has(loaderId)) {
+    (internal._deferredLoaders ??= new Map()).set(loaderId, { owner, start });
   }
 }
 
 /**
- * A reader asks for a loader this prefetch deferred and nothing has started:
- * start it through its registration and return the run, or undefined when
- * the read takes the ordinary path. Without this the reader ran the loader
- * bare, without its cache() binding, and the segment delivered afterwards
- * read the binding: two values on one page and an extra run on a HIT.
+ * A reader asks for a registered loader (registerDeferredLoader) and nothing
+ * has started it: start it through its registration and return the run, or
+ * undefined when the read takes the ordinary path. Without this the reader
+ * ran the loader bare, as a handler-invoked loader: in a prefetch without its
+ * cache() binding, so the segment delivered afterwards read the binding (two
+ * values on one page, an extra run on a HIT); in a route record's background
+ * re-render outside its DSL scope, so the record kept its handle pushes and
+ * every HIT showed them twice.
  *
  * A started cache() binding of the loader (`_loaderCacheOverrides`) is never
  * redirected here: the read is that binding's own MISS execution, and
@@ -478,7 +481,7 @@ export function startDeferredLoader(
   loaderId: string,
 ): Promise<unknown> | undefined {
   const internal = ctx as InternalHandlerContext<any, any>;
-  const deferred = internal._prefetchDeferral?.deferredLoaders?.get(loaderId);
+  const deferred = internal._deferredLoaders?.get(loaderId);
   if (
     !deferred ||
     deferred.started ||
@@ -492,8 +495,8 @@ export function startDeferredLoader(
 
 /**
  * The segment a run of `loaderId` files its handle pushes under: the one
- * that registers it when this prefetch deferred it, else the segment being
- * resolved.
+ * that registers it when it is registered (registerDeferredLoader), else the
+ * segment being resolved.
  */
 export function loaderOwner(
   ctx: HandlerContext<any, any>,
@@ -501,7 +504,7 @@ export function loaderOwner(
 ): string | undefined {
   const internal = ctx as InternalHandlerContext<any, any>;
   return (
-    internal._prefetchDeferral?.deferredLoaders?.get(loaderId)?.owner ??
+    internal._deferredLoaders?.get(loaderId)?.owner ??
     internal._currentSegmentId
   );
 }

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

@@ -0,0 +1,139 @@
+/**
+ * ResolutionPass: what one walk over a matched chain reads.
+ *
+ * Every function of the segment walker (revalidation.ts, intercept-resolution.ts)
+ * resolves against the same request: the handler context, the segments the
+ * client holds, the previous and next location, the action, the staleness and
+ * the router's deps. They take this one object instead of threading the same
+ * ten values through each signature in a fixed order, where two adjacent
+ * `URL`s or `Record<string, string>`s could swap without a type error.
+ *
+ * A full match (a document, the background re-render of a route record, a
+ * build-time prerender) is a FRESH pass: see FRESH below.
+ */
+
+import type { HandlerContext } from "../../types.js";
+import type { ActionContext, SegmentResolutionDeps } from "../types.js";
+import { NOTHING_HELD } from "./prefetch-deferral.js";
+
+/**
+ * The segment ids the client holds, the set resolution works on (match-api.ts
+ * may delete a route's id from the listed set to force a render). Empty on a
+ * full refetch.
+ */
+export type ClientHeld = ReadonlySet<string>;
+
+/**
+ * The client of a full match: it holds nothing and asks for nothing to be
+ * kept. Compared by identity (`pass.client === FRESH`), never by size: a
+ * partial request whose client holds nothing (NOTHING_HELD, an empty
+ * `_rsc_segments`) still asks the revalidate() rules. On a FRESH pass every
+ * segment is new without a decision, trace entry or `revalidation.decision`
+ * event, and the walker takes the full match's branches (revalidation.ts,
+ * each marked FRESH).
+ */
+export const FRESH: ClientHeld = new Set<string>();
+
+/**
+ * A pass without the router's deps: what match middleware knows about the
+ * request. createSegmentWrappers (segment-wrappers.ts) binds the deps.
+ */
+export interface ResolutionPassInput<TEnv = any> {
+  readonly context: HandlerContext<any, TEnv>;
+  readonly client: ClientHeld;
+  /** The matched route's params, stamped on every segment the walk emits. */
+  readonly params: Record<string, string>;
+  readonly prevParams: Record<string, string>;
+  /** Undefined only on a build-time FRESH pass (freshPassInput). */
+  readonly request: Request | undefined;
+  readonly prevUrl: URL;
+  readonly nextUrl: URL;
+  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
+   * (background-revalidation.ts), whose records never hold loaders.
+   * resolveOwnerLoaders registers each loader instead: in the re-render a
+   * handler's read starts it as its declaration; at build time a read
+   * throws (setupBuildUse).
+   */
+  readonly skipLoaders?: boolean;
+  /**
+   * A render error rethrows instead of rendering the error boundary, and a
+   * streamed handler's rejection is not recovered. Build time only, so a
+   * failure (or `throw new Skip()`) reaches the build instead of being baked
+   * into a frozen 200 (issue #587).
+   */
+  readonly throwOnError?: boolean;
+  /**
+   * The request is a navigation, though the pass is FRESH: the background
+   * re-render of a record a navigation read stale or wrote
+   * (background-revalidation.ts). An entry's error reports isPartial, as the
+   * navigation's own pass does.
+   */
+  readonly partialRequest?: boolean;
+}
+
+export interface ResolutionPass<TEnv = any> extends ResolutionPassInput<TEnv> {
+  readonly deps: SegmentResolutionDeps<TEnv>;
+}
+
+/**
+ * The input of a full match's pass (FRESH). At build time the prerender
+ * context's `request` is a throwing getter (handler-context.ts
+ * createPrerenderContext): the pass carries undefined instead.
+ */
+export function freshPassInput<TEnv>(
+  context: HandlerContext<any, TEnv>,
+  routeKey: string,
+  params: Record<string, string>,
+  options?: {
+    skipLoaders?: boolean;
+    throwOnError?: boolean;
+    partialRequest?: boolean;
+  },
+): ResolutionPassInput<TEnv> {
+  let request: Request | undefined;
+  try {
+    request = context.request;
+  } catch {}
+  return {
+    context,
+    client: FRESH,
+    params,
+    prevParams: {},
+    request,
+    prevUrl: context.url,
+    nextUrl: context.url,
+    routeKey,
+    ...options,
+  };
+}
+
+/**
+ * The input of a pass whose client holds nothing: every segment is new and
+ * renders. The background re-render of an intercept (background-revalidation.ts)
+ * resolves with it.
+ */
+export function heldNothingPassInput<TEnv>(
+  context: HandlerContext<any, TEnv>,
+  routeKey: string,
+  params: Record<string, string>,
+  options?: { skipLoaders?: boolean },
+): ResolutionPassInput<TEnv> {
+  return {
+    context,
+    client: NOTHING_HELD,
+    params,
+    prevParams: {},
+    request: context.request,
+    prevUrl: context.url,
+    nextUrl: context.url,
+    routeKey,
+    ...options,
+  };
+}