@rangojs/router 0.23.0 → 0.24.0

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

@@ -99,11 +99,8 @@ export interface PrefetchDeferral {
    * not stored and not held. Empty outside a prefetch.
    */
   readonly skipped: ReadonlySet<string>;
-  /**
-   * One of `skipped` is a chain entry: nothing below it runs, so the response
-   * has no content for it, a route cache() record included.
-   */
-  readonly skipsChain: boolean;
+  /** How this request may use the route's cache() record (recordUse). */
+  readonly record: RecordUse;
   /** Segment id of the handler unit this prefetch skipped. */
   deferredUnit?: string;
   /**
@@ -125,6 +122,31 @@ export interface PrefetchDeferral {
   deferredLoaders?: Map<string, DeferredLoader>;
 }
 
+/**
+ * How a request may use the route's cache() record, decided once per match
+ * (planPrefetchDeferral) for the cache middleware.
+ */
+export interface RecordUse {
+  /**
+   * withCacheLookup reads it. False when this prefetch skips a chain unit
+   * (PrefetchDeferral.skipped): the unit takes everything below it, so the
+   * read would replay the record's handle pushes for segments the response
+   * does not carry. Decided from what the client holds, never per tree: a
+   * prefetch that holds the flagged layout reads and writes the record like
+   * any other request.
+   */
+  readonly read: boolean;
+  /** withCacheStore writes it. False where `read` is: the record would be incomplete. */
+  readonly write: boolean;
+  /**
+   * A background re-render of the whole route may write it: the stale-hit
+   * refresh (withBackgroundRevalidation) and the proactive write a partial
+   * response needs (withCacheStore). False for a fill: the re-render runs
+   * the handlers of segments the client holds, which a fill does not run.
+   */
+  readonly refresh: boolean;
+}
+
 /** A loader this prefetch deferred: PrefetchDeferral.deferredLoaders. */
 export interface DeferredLoader {
   /**
@@ -329,7 +351,12 @@ export function planPrefetchDeferral(
       }
     }
   }
-  return { scope, mode, storedFrom, held, skipped, skipsChain };
+  const record: RecordUse = {
+    read: !skipsChain,
+    write: !skipsChain,
+    refresh: mode !== "fill",
+  };
+  return { scope, mode, storedFrom, held, skipped, record };
 }
 
 export function getPrefetchDeferral(
@@ -344,6 +371,30 @@ export function isFillRequest(ctx: HandlerContext<any, any>): boolean {
   return getPrefetchDeferral(ctx)?.mode === "fill";
 }
 
+/**
+ * A fill's whole revalidation rule (R5): send a segment the client does not
+ * hold, keep one it holds, and consult nothing else (no revalidate()
+ * predicate, no params or search comparison, no trace entry). Undefined on
+ * any other request, where revalidation decides. `held` is the set the
+ * deciding site resolves with.
+ */
+export function fillSends(
+  ctx: HandlerContext<any, any>,
+  segmentId: string,
+  held: ReadonlySet<string>,
+): boolean | undefined {
+  return isFillRequest(ctx) ? !held.has(segmentId) : undefined;
+}
+
+const RECORD_OPEN: RecordUse = { read: true, write: true, refresh: true };
+
+/** PrefetchDeferral.record, or all of it open when the match has no plan. */
+export function recordUse(
+  ctx: HandlerContext<any, any> | undefined,
+): RecordUse {
+  return getPrefetchDeferral(ctx)?.record ?? RECORD_OPEN;
+}
+
 /**
  * Register a loader this prefetch deferred, with the segment that registers
  * it and how to start it there (PrefetchDeferral.deferredLoaders). The first
@@ -481,17 +532,6 @@ export function firstUnitCandidate(
   return undefined;
 }
 
-/**
- * This prefetch skips a layout above the route cache's boundary, and with it
- * everything the record below holds: withCacheLookup and withCacheStore leave
- * the record alone for it. Decided per request, from what the client holds:
- * a prefetch of the same tree that holds the layout reads and writes the
- * record like any other request.
- */
-export function defersAboveRecord(ctx: HandlerContext<any, any>): boolean {
-  return getPrefetchDeferral(ctx)?.skipsChain === true;
-}
-
 /**
  * Record the handler unit this prefetch skipped. A `chain` entry takes what
  * the walk reaches after it (PrefetchDeferral.below); a slot is skipped

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

@@ -9,7 +9,10 @@
 import type { ReactNode } from "react";
 import { invariant } from "../../errors";
 import { revalidate } from "../loader-resolution.js";
-import { evaluateRevalidation } from "../revalidation.js";
+import {
+  evaluateRevalidation,
+  type EvaluateRevalidationOptions,
+} from "../revalidation.js";
 import {
   getParallelEntries,
   getParallelSlotEntries,
@@ -38,8 +41,8 @@ import { entryLoadingMasksLoaders } from "./loader-mask.js";
 import {
   defersLoader,
   deferUnit,
+  fillSends,
   getPrefetchDeferral,
-  isFillRequest,
   registerDeferredLoader,
 } from "./prefetch-deferral.js";
 import {
@@ -110,6 +113,28 @@ function emitRevalidationDecision(
   });
 }
 
+/**
+ * Whether a segment the client holds (`held`, the set resolution works on)
+ * renders again. A fill keeps it (prefetch-deferral.ts fillSends): no
+ * revalidate() predicate runs and nothing is traced or observed. Any other
+ * request asks the segment's revalidate() chain, and `onEvaluated` sees that
+ * answer.
+ */
+async function revalidateHeld<TEnv>({
+  held,
+  onEvaluated,
+  ...options
+}: EvaluateRevalidationOptions<TEnv> & {
+  held: ReadonlySet<string>;
+  onEvaluated?: (shouldRevalidate: boolean) => void;
+}): Promise<boolean> {
+  const fill = fillSends(options.context, options.segment.id, held);
+  if (fill !== undefined) return fill;
+  const shouldRevalidate = await evaluateRevalidation(options);
+  onEvaluated?.(shouldRevalidate);
+  return shouldRevalidate;
+}
+
 // ---------------------------------------------------------------------------
 // prefetch: false (prefetch-deferral.ts)
 // ---------------------------------------------------------------------------
@@ -194,7 +219,6 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   }));
 
   const matchedIds = loaderMeta.map((m) => m.segmentId);
-  const fill = isFillRequest(ctx);
 
   const revalidationChecks = await Promise.all(
     loaderMeta.map(
@@ -221,8 +245,6 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               }
               return true;
             }
-            // Fill: a held segment is skipped outright, no predicate runs.
-            if (fill) return false;
 
             const dummySegment: ResolvedSegment = {
               id: segmentId,
@@ -235,7 +257,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               belongsToRoute,
             };
 
-            return await evaluateRevalidation({
+            return await revalidateHeld({
               segment: dummySegment,
               prevParams,
               getPrevSegment: null,
@@ -251,6 +273,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               actionContext,
               stale,
               traceSource: "loader",
+              held: clientSegmentIds,
             });
           },
           async () => true,
@@ -704,10 +727,12 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
     // runs: a prefetch sends what the slot declares instead of running its
     // handler.
     let deferred = deferUnit(context, parallelId, "below");
+    // A fill sends exactly the slots the client lacks, ahead of every rule
+    // below (fillSends).
+    const fill = fillSends(context, parallelId, clientSegmentIds);
     let shouldResolve: boolean;
-    if (isFillRequest(context)) {
-      // Fill: only what the client does not hold renders, no predicate runs.
-      shouldResolve = !clientSegmentIds.has(parallelId);
+    if (fill !== undefined) {
+      shouldResolve = fill;
     } else if (deferred) {
       shouldResolve = true;
     } else if (isFullRefetch) {
@@ -880,8 +905,6 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         }
         return true;
       }
-      // Fill: a held segment is skipped outright, no predicate runs.
-      if (isFillRequest(context)) return false;
 
       const dummySegment: ResolvedSegment = {
         id: entry.shortCode,
@@ -900,7 +923,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
       };
 
-      const shouldRevalidate = await evaluateRevalidation({
+      return revalidateHeld({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -917,18 +940,20 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         stale,
         traceSource:
           entry.type === "route" ? "route-handler" : "layout-handler",
+        held: clientSegmentIds,
+        onEvaluated: (shouldRevalidate) => {
+          emitRevalidationDecision(
+            entry.shortCode,
+            context.pathname,
+            routeKey,
+            shouldRevalidate,
+          );
+          debugLog("segment.revalidate", "entry revalidation decision", {
+            segmentId: entry.shortCode,
+            shouldRevalidate,
+          });
+        },
       });
-      emitRevalidationDecision(
-        entry.shortCode,
-        context.pathname,
-        routeKey,
-        shouldRevalidate,
-      );
-      debugLog("segment.revalidate", "entry revalidation decision", {
-        segmentId: entry.shortCode,
-        shouldRevalidate,
-      });
-      return shouldRevalidate;
     },
     async () => {
       // Only an entry the client lacks (defersUnit). Its handler would
@@ -1308,8 +1333,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         }
         return true;
       }
-      // Fill: a held segment is skipped outright, no predicate runs.
-      if (isFillRequest(context)) return false;
 
       const dummySegment: ResolvedSegment = {
         id: orphan.shortCode,
@@ -1323,7 +1346,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
       };
 
-      const shouldRevalidate = await evaluateRevalidation({
+      return revalidateHeld({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -1339,14 +1362,15 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "orphan-layout",
+        held: clientSegmentIds,
+        onEvaluated: (shouldRevalidate) =>
+          emitRevalidationDecision(
+            orphan.shortCode,
+            context.pathname,
+            routeKey,
+            shouldRevalidate,
+          ),
       });
-      emitRevalidationDecision(
-        orphan.shortCode,
-        context.pathname,
-        routeKey,
-        shouldRevalidate,
-      );
-      return shouldRevalidate;
     },
     async () => {
       // Below a unit a prefetch skipped: the orphan goes with it.

package/src/rsc/full-payload.ts

@@ -14,7 +14,11 @@ import type { HandlerContext } from "./handler-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { Theme } from "../theme/types.js";
-import { documentCacheStoresRender } from "../cache/document-cache.js";
+import {
+  rendersForSharedAudience,
+  rewriteTrail,
+  visitorUrl,
+} from "../server/rewrite-trail.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
 import { publicRouteName } from "../route-name.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
@@ -38,7 +42,7 @@ export function buildFullPayload(
 ): RscPayload {
   return {
     metadata: {
-      pathname: url.pathname,
+      pathname: renderedLocation(reqCtx, url).pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
       segments: attachTransitionWhen(m.segments, reqCtx),
@@ -84,6 +88,36 @@ export function buildFullPayload(
   };
 }
 
+/**
+ * The URL a render shows as the page's location (payload `pathname`, the SSR
+ * search and origin seed). For a request middleware rewrote, the visitor's
+ * URL, so the server markup and the hydrating client (which reads the address
+ * bar) agree on `usePathname()` and `useSearchParams()`. A render other
+ * visitors may be served shows `url`, the target, as a direct visit does: a
+ * shell capture, and a render the document cache stores (its key is the
+ * target). A render that shows the visitor's URL marks
+ * `_payloadVisitorLocation`, and the document cache does not store it.
+ */
+export function renderedLocation(
+  reqCtx:
+    | Pick<
+        RequestContext<any>,
+        | "_variables"
+        | "_shellCaptureRun"
+        | "_documentCacheRender"
+        | "_payloadVisitorLocation"
+        | "res"
+      >
+    | undefined,
+  url: URL,
+): URL {
+  if (!reqCtx || !rewriteTrail(reqCtx) || rendersForSharedAudience(reqCtx)) {
+    return url;
+  }
+  reqCtx._payloadVisitorLocation = true;
+  return visitorUrl(reqCtx, url);
+}
+
 /**
  * The theme a document payload carries as `metadata.initialTheme` (the
  * ThemeProvider's first state), read with no identity guard: it is the
@@ -116,9 +150,7 @@ export function payloadInitialTheme(
 ): Theme | undefined {
   const config = reqCtx._themeConfig;
   if (!config) return undefined;
-  if (reqCtx._shellCaptureRun || documentCacheStoresRender(reqCtx)) {
-    return config.defaultTheme;
-  }
+  if (rendersForSharedAudience(reqCtx)) return config.defaultTheme;
   const theme = reqCtx._readTheme();
   if (theme !== config.defaultTheme) reqCtx._payloadVisitorTheme = true;
   return theme;

package/src/rsc/handler.ts

@@ -17,6 +17,8 @@ import {
   createRequestContext,
   captureRequestEntryContext,
 } from "../server/request-context.js";
+import { REWRITE_HEADER, runRewritePasses } from "./rewrite-passes.js";
+import { renderedLocation } from "./full-payload.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc/server";
 import type {
   RscPayload,
@@ -25,6 +27,7 @@ import type {
   SSRModule,
 } from "./types.js";
 import {
+  createReloadResponse,
   createResponseWithMergedHeaders,
   finalizeResponse,
   interceptRedirectForPartial,
@@ -41,6 +44,7 @@ import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import {
   isWebSocketUpgradeResponse,
   appendVaryAccept,
+  trySetHeader,
 } from "../response-utils.js";
 import {
   handleResponseRoute,
@@ -57,10 +61,7 @@ import {
   invokeOnError,
   resolveDefaultNotFound,
 } from "../router/error-handling.js";
-import {
-  createReverseFunction,
-  stripInternalParams,
-} from "../router/handler-context.js";
+import { createReverseFunction } from "../router/handler-context.js";
 import { contextSet } from "../context-var.js";
 import {
   hasCachedManifest,
@@ -82,7 +83,7 @@ import {
   revalidateAfterAction,
   type ActionContinuation,
 } from "./server-action.js";
-import { handleLoaderFetch } from "./loader-fetch.js";
+import { handleLoaderFetch, renderLoaderError } from "./loader-fetch.js";
 import { applyStreamIdleTimeout } from "./stream-idle.js";
 import {
   checkRequestOrigin,
@@ -113,6 +114,7 @@ import {
   mayNeedSSR,
   isRscRequest,
   SSR_SETUP_VAR,
+  type SSRSetup,
 } from "./ssr-setup.js";
 import {
   classifyRequest,
@@ -155,21 +157,6 @@ import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
  * ```
  */
 
-/**
- * Response that tells the client to do a full document navigation. Shared by
- * the terminal reload plans (version-mismatch and app-switch): an empty 200
- * carrying X-RSC-Reload, which the client turns into window.location.href.
- */
-function createReloadResponse(reloadUrl: string) {
-  return createResponseWithMergedHeaders(null, {
-    status: 200,
-    headers: {
-      "X-RSC-Reload": reloadUrl,
-      "content-type": "text/x-component;charset=utf-8",
-    },
-  });
-}
-
 export function createRSCHandler<
   TEnv = unknown,
   TRoutes extends Record<string, string> = Record<string, string>,
@@ -703,24 +690,70 @@ export function createRSCHandler<
         // latter is reserved for the low-cardinality template (OTel convention).
         span.setAttribute("url.path", url.pathname);
 
-        // Core handler logic (wrapped by middleware)
-        const coreHandler = async (): Promise<Response> => {
-          return coreRequestHandler(request, env, url, variables, nonce);
-        };
-
-        // Execute middleware chain if any, otherwise call core handler
-        // directly; the response is finalized below, inside the response span.
-        const hasMiddleware = matchedMiddleware.length > 0;
-        const downstream = hasMiddleware
-          ? await executeMiddleware(
-              matchedMiddleware,
-              request,
+        // One pass per URL: the global middleware chain matched on the pass's
+        // path, wrapping the core handler. A `throw rewrite()` from global or
+        // route middleware unwinds the pass, and the next one runs the same
+        // request as the target from the top, as a direct visit would
+        // (rsc/rewrite-passes.ts). The response is finalized below, inside the
+        // response span.
+        let passIndex = 0;
+        let hasMiddleware = false;
+        const { response: downstream, rewrittenTo } = await runRewritePasses({
+          reqCtx: requestContext,
+          request,
+          url,
+          routeMap: getRequiredRouteMap,
+          basename: router.basename,
+          runPass: (passRequest, passUrl) => {
+            const passMiddleware =
+              passIndex++ === 0
+                ? matchedMiddleware
+                : matchMiddleware(
+                    requestContext.url.pathname,
+                    router.middleware,
+                  );
+            hasMiddleware = passMiddleware.length > 0;
+            const coreHandler = (): Promise<Response> =>
+              coreRequestHandler(passRequest, env, passUrl, variables, nonce);
+            return hasMiddleware
+              ? executeMiddleware(
+                  passMiddleware,
+                  passRequest,
+                  env,
+                  variables,
+                  coreHandler,
+                  createReverseFunction(getRequiredRouteMap()),
+                )
+              : coreHandler();
+          },
+          onHop: (pass) => {
+            span.setAttribute("rango.rewrite.target", pass.target.pathname);
+            span.setAttribute("rango.rewrite.hops", pass.hops);
+          },
+          report: (error, at) => {
+            callOnError(error, "routing", {
+              request: at.request,
+              url: at.url,
               env,
-              variables,
-              coreHandler,
-              createReverseFunction(getRequiredRouteMap()),
-            )
-          : await coreHandler();
+              handledByBoundary: false,
+            });
+          },
+          // A loader fetch answers with the error `load()` rejects with.
+          refuse: (error) =>
+            url.searchParams.has("_rsc_loader")
+              ? renderLoaderError(
+                  handlerCtx,
+                  { message: (error as Error).message, name: "Error" },
+                  500,
+                  {
+                    request,
+                    url,
+                    env,
+                    loaderId: url.searchParams.get("_rsc_loader") ?? "",
+                  },
+                )
+              : undefined,
+        });
 
         // Final response construction + host handoff, wrapped in rango.response
         // — the explicit stream-handoff marker. The callback is synchronous, so
@@ -787,14 +820,9 @@ export function createRSCHandler<
           }
 
           const fullTiming = timingParts.join(", ");
-          if (fullTiming && !isWebSocketUpgradeResponse(response)) {
-            try {
-              response.headers.set("Server-Timing", fullTiming);
-            } catch {
-              // Immutable headers (e.g. a passed-through platform Response) — drop
-              // the timing header, never the response. Instrumentation must not
-              // 500 a request.
-            }
+          if (fullTiming) trySetHeader(response, "Server-Timing", fullTiming);
+          if (rewrittenTo !== undefined) {
+            trySetHeader(response, REWRITE_HEADER, rewrittenTo);
           }
 
           // Single open-redirect chokepoint: every response (PE, full-page,
@@ -956,18 +984,19 @@ export function createRSCHandler<
       // which returns { redirect: url }. Fall through to full-render.
     }
 
+    // A reload points at the visitor's URL, never a rewrite target's.
     if (plan.mode === "version-mismatch") {
       console.log(
         `[RSC] Version mismatch: client=${url.searchParams.get("_rsc_v")}, server=${version}. Forcing reload.`,
       );
-      return createReloadResponse(plan.reloadUrl);
+      return createReloadResponse(getRequestContext(), plan.reloadUrl);
     }
 
     if (plan.mode === "app-switch") {
       // Cross-app SPA navigation crossed a host-router app boundary. Force a
       // real document navigation so the target app's document is re-established
       // (stylesheets, theme, warmup, prefetch-TTL). See request-classification.
-      return createReloadResponse(plan.reloadUrl);
+      return createReloadResponse(getRequestContext(), plan.reloadUrl);
     }
 
     // ---- 3. Origin guard (gate for action/loader/PE modes) ----
@@ -1137,6 +1166,9 @@ export function createRSCHandler<
       (mayNeedSSR(request, url) &&
         !isRscRequest(request, url, plan.mode === "partial-render"));
     if (plan.mode !== "loader" && willRenderHtml) {
+      // A rewritten pass keeps the SSR module the earlier pass started
+      // loading; the stream mode is resolved for the request it renders.
+      const earlier = variables[SSR_SETUP_VAR] as Promise<SSRSetup> | undefined;
       const ssrSetup = startSSRSetup(
         handlerCtx,
         request,
@@ -1145,6 +1177,7 @@ export function createRSCHandler<
         router.debugPerformance
           ? () => getRequestContext()._metricsStore
           : undefined,
+        earlier?.then(([ssrModule]) => ssrModule),
       );
       variables[SSR_SETUP_VAR] = ssrSetup;
 
@@ -1348,13 +1381,7 @@ export function createRSCHandler<
               `[RSC] Route handler at ${url.pathname} returned a Response during client-side navigation. ` +
                 `Falling back to hard navigation. Use data-external on the <Link> to avoid the extra round-trip.`,
             );
-            return createResponseWithMergedHeaders(null, {
-              status: 200,
-              headers: {
-                "X-RSC-Reload": stripInternalParams(url).toString(),
-                "content-type": "text/x-component;charset=utf-8",
-              },
-            });
+            return createReloadResponse(getRequestContext(), url);
           }
 
           if (treatAsPartial) {
@@ -1396,7 +1423,7 @@ export function createRSCHandler<
 
           const payload: RscPayload = {
             metadata: {
-              pathname: url.pathname,
+              pathname: renderedLocation(getRequestContext(), url).pathname,
               routerId: router.id,
               basename: router.basename,
               segments: [notFoundSegment],

package/src/rsc/helpers.ts

@@ -24,6 +24,7 @@ import {
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import { formatCacheSignalHeader } from "../router/telemetry.js";
 import type { RscPayload } from "./types.js";
+import { rewriteTrail, visitorUrl } from "../server/rewrite-trail.js";
 import type { HandlerContext } from "./handler-context.js";
 
 /**
@@ -157,6 +158,29 @@ export function createResponseWithMergedHeaders(
   return drainOnResponseCallbacks(ctx, response);
 }
 
+/**
+ * An empty 200 carrying X-RSC-Reload: the client turns it into a document
+ * navigation (window.location.href). It points at the visitor's URL: the
+ * first URL of a rewritten request (server/rewrite-trail.ts visitorUrl),
+ * else `url` with the internal `_rsc*` params stripped, or `url` as given
+ * when it is a string the caller resolved (an action's referer).
+ */
+export function createReloadResponse(
+  reqCtx: RequestContext<any> | undefined,
+  url: URL | string,
+): Response {
+  const target =
+    rewriteTrail(reqCtx)?.[0] ??
+    (typeof url === "string" ? url : visitorUrl(undefined, url).href);
+  return createResponseWithMergedHeaders(null, {
+    status: 200,
+    headers: {
+      "X-RSC-Reload": target,
+      "content-type": "text/x-component;charset=utf-8",
+    },
+  });
+}
+
 /**
  * Rebuild a Response returned or thrown by a response-route handler so request
  * effects merge consistently in production and the public dispatch primitive.