@rangojs/router 0.27.0 → 0.29.0

package/src/router/match-context.ts

@@ -63,7 +63,6 @@
  *
  * Handler Context:
  *   - handlerContext: Context passed to loaders
- *   - loaderPromises: Memoized loader promises
  *
  * Intercepts:
  *   - interceptResult: Detected intercept (if soft navigation)
@@ -118,16 +117,8 @@ import type {
 import type { HandlerContext, ResolvedSegment } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { InterceptResult } from "./router-context.js";
-
-/**
- * Action context passed to matchPartial
- */
-export interface ActionContext {
-  actionId?: string;
-  actionUrl?: URL;
-  actionResult?: any;
-  formData?: FormData;
-}
+import type { ResolutionPassInput } from "./segment-resolution/resolution-pass.js";
+import type { ActionContext } from "./types.js";
 
 /**
  * Match context containing all state for the match pipeline
@@ -145,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;
@@ -160,7 +153,6 @@ export interface MatchContext<TEnv = any> {
 
   // Handler context (for loaders)
   handlerContext: HandlerContext<any, TEnv>;
-  loaderPromises: Map<string, Promise<any>>;
 
   // Route map for server-side ctx.reverse() resolution
   routeMap: Record<string, string>;
@@ -214,6 +206,25 @@ export function rendersLive(
   return ctx.isAction || ctx.stale;
 }
 
+/** This match as the input of a revalidating resolution pass (resolution-pass.ts). */
+export function resolutionPassInput<TEnv>(
+  ctx: MatchContext<TEnv>,
+): ResolutionPassInput<TEnv> {
+  return {
+    context: ctx.handlerContext,
+    client: ctx.clientSegmentSet,
+    params: ctx.matched.params,
+    prevParams: ctx.prevParams,
+    request: ctx.request,
+    prevUrl: ctx.prevUrl,
+    nextUrl: ctx.url,
+    routeKey: ctx.routeKey,
+    actionContext: ctx.actionContext,
+    stale: ctx.stale,
+    heldBoundary: ctx.heldBoundary,
+  };
+}
+
 /**
  * Mutable state that flows through the pipeline
  */

package/src/router/match-handlers.ts

@@ -13,14 +13,10 @@ import {
   type InterceptEntry,
   type InterceptSelectorContext,
 } from "../server/context.js";
-import type { MatchApiDeps } from "./types.js";
+import type { ActionContext, MatchApiDeps } from "./types.js";
 import type { RouterContext } from "./router-context.js";
 import { runWithRouterContext } from "./router-context.js";
-import {
-  type ActionContext,
-  type MatchContext,
-  createPipelineState,
-} from "./match-context.js";
+import { type MatchContext, createPipelineState } from "./match-context.js";
 import { createMatchPartialPipeline } from "./match-pipelines.js";
 import { collectMatchResult } from "./match-result.js";
 import {
@@ -194,11 +190,8 @@ export interface MatchHandlers<TEnv = any> {
       handler: MiddlewareFn;
       params: Record<string, string>;
     }>;
-    responseType?: string;
-    handler?: Function;
     params?: Record<string, string>;
-    negotiated?: boolean;
-    manifestEntry?: EntryData;
+    routeKey?: string;
   } | null>;
 }
 
@@ -259,12 +252,7 @@ export function createMatchHandlers<TEnv = any>(
   async function createMatchContextForPartial(
     request: Request,
     env: TEnv,
-    actionContext?: {
-      actionId?: string;
-      actionUrl?: URL;
-      actionResult?: any;
-      formData?: FormData;
-    },
+    actionContext?: ActionContext,
   ): Promise<MatchContext<TEnv> | null> {
     return _createMatchContextForPartial(
       request,
@@ -277,13 +265,13 @@ export function createMatchHandlers<TEnv = any>(
 
   async function match(request: Request, env: TEnv): Promise<MatchResult> {
     // Silence telemetry for the PPR background shell capture: it re-runs match()
-    // under a derived request context flagged _shellCaptureRun (shell-capture.ts
+    // under a derived request context with _shellCaptureState (shell-capture.ts
     // attemptCapture), re-using the foreground Request — a second request.start/
     // cache.decision/request.end stamped with the same WeakMap-keyed requestId
     // would double-count dashboards. Derived here (inside the capture's active
     // request-context ALS) so the read sees the derived context, not module state.
     const emitTelemetry =
-      hasTelemetry && !_getRequestContext()?._shellCaptureRun;
+      hasTelemetry && !_getRequestContext()?._shellCaptureState?.run;
     const requestId = emitTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext({ request, transaction: "match" }, () => {
       const routerCtx = buildRouterContext();
@@ -409,9 +397,9 @@ export function createMatchHandlers<TEnv = any>(
     actionContext?: ActionContext,
   ): Promise<MatchResult | null> {
     // See match() above: the PPR shell capture re-runs matchPartial() under a
-    // _shellCaptureRun context and must stay invisible to the sink.
+    // _shellCaptureState context and must stay invisible to the sink.
     const emitTelemetry =
-      hasTelemetry && !_getRequestContext()?._shellCaptureRun;
+      hasTelemetry && !_getRequestContext()?._shellCaptureState?.run;
     const partialRequestId = emitTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext(
       { request, transaction: "matchPartial" },

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

@@ -36,7 +36,7 @@
  *         |
  *         v
  *   +---------------------------+
- *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
+ *   | FRESH segment pass      |  Fresh resolution (no revalidation)
  *   | + resolveIntercepts()   |  Ensures complete components
  *   +---------------------------+
  *         |
@@ -94,14 +94,17 @@
  * FRESH RESOLUTION (NO REVALIDATION)
  * ===================================
  *
- * Both full and partial requests use resolveAllSegments() (without
+ * Both full and partial requests resolve with a FRESH pass (without
  * revalidation logic) to ensure all segments have complete components.
  * Using revalidation-aware resolution would produce null components
- * for skipped segments, which would corrupt the cache entry.
+ * for skipped segments, which would corrupt the cache entry. Under an
+ * intercept the walk still skips the intercepted route's entry, as the MISS
+ * does: an intercept: record never holds the route's page.
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
+import { interceptRecordKey } from "../intercept-resolution.js";
 import type { CacheScope } from "../../cache/cache-scope.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
@@ -109,12 +112,16 @@ import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { getContext } from "../../server/context.js";
 import { executionStart } from "../../cache/tag-invalidation.js";
 import {
-  bindRes,
   createRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../../server/request-context.js";
+import { deriveRenderPass } from "../../server/render-pass.js";
 import { recordUse } from "../segment-resolution/prefetch-deferral.js";
+import {
+  freshPassInput,
+  heldNothingPassInput,
+} from "../segment-resolution/resolution-pass.js";
 
 /**
  * Re-render a cached route in the background and write it with
@@ -129,25 +136,14 @@ import { recordUse } from "../segment-resolution/prefetch-deferral.js";
  * MAX_REVALIDATION_INTERVAL, as after a refresh that throws.
  *
  * Runs on a DERIVED request context that owns the per-render state the
- * foreground reads while it is still producing the page (a stale HIT re-runs
- * its loaders; a proactive render starts once the Response exists, while its
- * body streams):
- *   - _handleStore: read late (loader pushes and aux-lane tracking in
- *     loader-resolution.ts, nested cache restores and captures in
- *     cache-scope.ts), so a swap sent live pushes into this render.
- *     setupLoaderAccess binds the store at setup, so it runs inside the
- *     derived context too.
- *   - _metricsStore: undefined, and the DSL store below has `metrics` unset
- *     (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.
- *   - response writes (headers, cookies, status, onResponse callbacks) go to
- *     a throwaway context (whose status gates the write, above) and are
- *     dropped: a layout above the cache() boundary is outside the header
- *     guard and an error boundary sets a status, so they would otherwise
- *     reach the live response.
- * runWithRequestContext also re-establishes the request ALS, which a waitUntil
- * task on workerd loses; the DSL store is a different ALS (build context).
+ * foreground reads while it is still producing the page:
+ * RENDER_PASS_FIELDS["background-revalidation"] (server/render-pass.ts) lists
+ * 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.
+ * 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>,
@@ -157,8 +153,7 @@ export async function rerenderAndCacheRoute<TEnv>(
 ): Promise<number> {
   const start = executionStart();
   const handleStore = routerCtx.createHandleStore();
-  // Response writes land in a throwaway context nothing merges or drains. Its
-  // mutators are closures over its own stub, and they keep the same guards.
+  // Response writes land in a throwaway context nothing merges or drains.
   const sink = createRequestContext({
     env: ctx.env,
     request: ctx.request,
@@ -166,26 +161,10 @@ export async function rerenderAndCacheRoute<TEnv>(
     variables: {},
     themeConfig: requestCtx._themeConfig,
   });
-  const renderCtx: RequestContext<TEnv> = Object.assign(
-    Object.create(requestCtx),
-    {
-      _handleStore: handleStore,
-      _metricsStore: undefined,
-      _renderErrors: [],
-      _recoveredHandlerErrors: undefined,
-      _onResponseCallbacks: [],
-      header: sink.header,
-      setCookie: sink.setCookie,
-      deleteCookie: sink.deleteCookie,
-      setStatus: sink.setStatus,
-      _setStatus: sink._setStatus,
-      setTheme: sink.setTheme,
-      _rotateStateCookie: sink._rotateStateCookie,
-      _setKeepCacheDirective: sink._setKeepCacheDirective,
-    },
-  );
-  // ctx.res reads the sink's stub, not the live request's.
-  bindRes(renderCtx, () => sink.res);
+  const renderCtx = deriveRenderPass(requestCtx, "background-revalidation", {
+    handleStore,
+    sink,
+  });
   const store = Object.assign(Object.create(ctx.Store), { metrics: undefined });
   const runInStore = <T>(fn: () => T): T =>
     getContext().runWithStore(
@@ -194,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,
@@ -210,26 +189,36 @@ export async function rerenderAndCacheRoute<TEnv>(
     const loaderPromises = new Map<string, Promise<any>>();
     routerCtx.setupLoaderAccess(handlerContext, loaderPromises);
 
-    const segments = await runInStore(() =>
+    const { segments } = await runInStore(() =>
       routerCtx.resolveAllSegments(
+        freshPassInput(handlerContext, ctx.routeKey, ctx.matched.params, {
+          skipLoaders: true,
+          partialRequest: !ctx.isFullMatch,
+        }),
         ctx.entries,
-        ctx.routeKey,
-        ctx.matched.params,
-        handlerContext,
-        loaderPromises,
-        { skipLoaders: true },
+        // Under an intercept the route's own entry is skipped, as on a MISS.
+        {
+          interceptResult: ctx.interceptResult,
+          localRouteName: ctx.localRouteName,
+          pathname: handlerContext.pathname,
+        },
       ),
     );
     if (ctx.interceptResult) {
       segments.push(
         ...(await runInStore(() =>
           routerCtx.resolveInterceptEntry(
+            // Nothing held: render fresh. Its loaders are skipped as the
+            // route's are: the record drops them.
+            heldNothingPassInput(
+              handlerContext,
+              ctx.interceptResult!.intercept.routeName,
+              ctx.matched.params,
+              { skipLoaders: true },
+            ),
             ctx.interceptResult!.intercept,
             ctx.interceptResult!.entry,
-            ctx.matched.params,
-            handlerContext,
             true, // belongsToRoute
-            undefined, // no revalidationContext: render fresh
             // A handler error rejects, so the failure is never cached.
             { background: true },
           ),
@@ -251,7 +240,7 @@ export async function rerenderAndCacheRoute<TEnv>(
       ctx.pathname,
       ctx.matched.params,
       segments,
-      ctx.isIntercept,
+      interceptRecordKey(ctx.interceptResult),
       start,
     );
     return segments.length;