@rangojs/router 0.24.4 → 0.25.0

package/src/rsc/rewrite-passes.ts

@@ -21,7 +21,11 @@ import {
   rebaseRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
-import { recordRewriteHop } from "../server/rewrite-trail.js";
+import { bodylessRequest } from "../server/request-headers.js";
+import {
+  recordRewriteHop,
+  recordRewriteShell,
+} from "../server/rewrite-trail.js";
 
 /** Response header naming the route path a rewritten request rendered. */
 export const REWRITE_HEADER = "x-rango-rewrite";
@@ -45,11 +49,9 @@ export function resolveRewriteTarget(
   const path =
     "path" in target
       ? prefixBasename(target.path, basename)
-      : // `{}`, not undefined: a route with params then throws for the
-        // missing ones instead of resolving to its raw pattern.
-        createReverseFunction(routeMap)(
+      : createReverseFunction(routeMap)(
           target.name,
-          target.params ?? {},
+          target.params,
           target.search,
         );
   const resolved = stripInternalParams(new URL(path, base.origin));
@@ -94,11 +96,38 @@ export interface RewritePass {
   hops: number;
 }
 
+let lateLockReported = false;
+
+/**
+ * `.disallowMutations()` thrown after the action ran cannot refuse it. Dev
+ * warns on every throw; production logs one error per isolate, so a lock
+ * that never refused anything is not silent there.
+ */
+function reportLateLock(rewrite: Rewrite): void {
+  const message = `[rango] ${describeRewriteTarget(rewrite.target)}.disallowMutations() came after the server action or form post ran, so it cannot refuse it: route middleware, and global middleware on a later rewritten pass, run only after the action. The render moves to the target. To refuse mutations, throw it from global middleware (router.use()) matched on the URL the form posts to.`;
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(message);
+  } else if (!lateLockReported) {
+    lateLockReported = true;
+    console.error(message);
+  }
+}
+
 /**
  * Move the request context to `rewrite`'s target for the next pass: check
  * that this request can be rewritten, resolve the target, count the hop,
- * then rebase the context. Throws the site error for a mutation or a loader
- * fetch, a resolution error, and RewriteLoopError.
+ * then rebase the context. Throws the site error for a loader fetch, a
+ * refused mutation or one whose body middleware read before its action ran,
+ * a resolution error, and RewriteLoopError.
+ *
+ * A mutation moves too (#1145). Before its action ran (a rewrite from global
+ * middleware) it moves with its body, and the target's pass runs the action
+ * after the target's global middleware, as a direct post there would. After
+ * it ran (route middleware wraps only the re-render), the target's pass
+ * re-renders from `reqCtx._actionRan`. `disallowMutations()` refuses the
+ * first, so a lock never runs a mutation; the second is already committed,
+ * and refusing it reports an error for a write that happened, so the caller
+ * retries it.
  */
 export function applyRewrite(
   rewrite: Rewrite,
@@ -113,12 +142,30 @@ export function applyRewrite(
     throw rewriteNotSupported(rewrite, "loader-fetch");
   }
   if (passRequest.method !== "GET" && passRequest.method !== "HEAD") {
-    throw rewriteNotSupported(rewrite, "mutation");
+    if (!reqCtx._actionRan) {
+      if (rewrite.mutationsDisallowed) {
+        throw rewriteNotSupported(rewrite, "mutation");
+      }
+      // The target's pass hands the body to the action: one middleware read
+      // would run it with no arguments.
+      if (passRequest.bodyUsed) throw rewriteNotSupported(rewrite, "body-read");
+    } else if (rewrite.mutationsDisallowed) {
+      reportLateLock(rewrite);
+    }
   }
   const target = resolveRewriteTarget(rewrite, routeMap, reqCtx.url, basename);
   const hops = recordRewriteHop(reqCtx, reqCtx.url, target);
+  recordRewriteShell(reqCtx, rewrite.shellAudience);
   const url = rewriteTransportUrl(target, reqCtx.originalUrl);
-  const request = new Request(url, passRequest);
+  // A mutation keeps its body: one whose action has not run yet, and a no-JS
+  // form post, since the PE handler reads a clone, so a form-field check
+  // reads it on every pass. A JS action that ran consumed it
+  // (`new Request(url, used)` throws): the same request without it or its
+  // content-type, so a body check gated on the content-type passes over this
+  // pass, which never runs the action.
+  const request = passRequest.bodyUsed
+    ? bodylessRequest(url, passRequest, passRequest.method)
+    : new Request(url, passRequest);
   rebaseRequestContext(reqCtx, request, url);
   return { request, url, target, hops };
 }

package/src/rsc/rsc-rendering.ts

@@ -40,6 +40,7 @@ import {
   renderRscFlightStage,
   renderRscResponse,
 } from "./render-pipeline.js";
+import { markPrefetchOnRenderError } from "./prefetch-render-error.js";
 import {
   createRoutineTrace,
   handoff,
@@ -51,7 +52,7 @@ import {
 import type { HandlerContext } from "./handler-context.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
 import { publicRouteName } from "../route-name.js";
-import { buildFullPayload, renderedLocation } from "./full-payload.js";
+import { buildFullPayload, payloadLocation } from "./full-payload.js";
 import {
   capShellWindow,
   lastStoredCaptureSeq,
@@ -94,6 +95,8 @@ import {
   type DevShellLookup,
 } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
+import { rewriteShellAudience, rewriteTrail } from "../server/rewrite-trail.js";
+import { visitorShellKey } from "./shell-capture-constants.js";
 import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import {
   isWarmReplace,
@@ -155,10 +158,52 @@ function describePprReplayStatus(status: PprReplayStatus): string {
     : `bypass:${status.reason}`;
 }
 
+/**
+ * The shell key before the route's own partition, or undefined: a request
+ * middleware rewrote reads and captures no shell unless its rewrite chose
+ * `.shell()`, so a URL's shared shell is read and written only by requests
+ * on that URL (#1146).
+ */
+interface RequestShellBase {
+  baseKey: string;
+  /** shellSearchSeed of the URL the key names. */
+  searchSeed: string;
+  /** A visitor-keyed shell's location (ShellCacheEntry.pathname). */
+  pathname?: string;
+}
+
+function requestShellBase(
+  ctx: HandlerContext<any>,
+  reqCtx: RequestContext<any>,
+  url: URL,
+): RequestShellBase | undefined {
+  const filter = reqCtx._searchParamsFilter;
+  const trail = rewriteTrail(reqCtx);
+  const shell = rewriteShellAudience(reqCtx);
+  if (trail && shell === "visitor") {
+    const visitor = new URL(trail[0]!);
+    return {
+      baseKey: visitorShellKey(
+        ctx.router.id,
+        visitor,
+        new URL(trail[trail.length - 1]!),
+        filter,
+      ),
+      searchSeed: shellSearchSeed(visitor, filter),
+      pathname: visitor.pathname,
+    };
+  }
+  if (trail && shell !== "target") return undefined;
+  return {
+    baseKey: buildShellKey(ctx.router.id, url, filter),
+    searchSeed: shellSearchSeed(url, filter),
+  };
+}
+
 function createShellCaptureDescriptor(
   ctx: HandlerContext<any>,
   key: string,
-  searchSeed: string,
+  base: RequestShellBase,
   originSeed: string,
   pprConfig: ResolvedPprConfig,
   store: SegmentCacheStore<any>,
@@ -166,7 +211,8 @@ function createShellCaptureDescriptor(
 ): ShellCaptureDescriptor {
   return {
     key,
-    searchSeed,
+    searchSeed: base.searchSeed,
+    pathname: base.pathname,
     // Derived from the same request URL as the key (the callers compute
     // both next to each other, so they cannot drift): seeding the origin
     // keeps origin-dependent static markup (Link's data-external)
@@ -499,13 +545,15 @@ function* shellServePlan<TEnv>(
   // no shell read, no capture, so it can never degrade again. The handler
   // stripped the marker from the request and left this flag.
   if (reqCtx._shellForcedMiss) return { kind: "pass" };
+  const base = requestShellBase(ctx, reqCtx, url);
+  if (!base) return { kind: "pass" };
 
   // A per-request CSP nonce pins the route to axis 1: a shared shell would
   // freeze the capture request's nonce and CSP would reject it for every
   // other visitor. Every step below, a HIT included, therefore runs without
   // one.
   const store = reqCtx._cacheStore;
-  const baseKey = buildShellKey(ctx.router.id, url, reqCtx._searchParamsFilter);
+  const { baseKey } = base;
   if (activeRequestNonce(nonce, reqCtx) !== undefined) {
     // Declared intent that cannot be honored deserves a diagnostic (unlike an
     // undeclared route, which is silent): a ppr route gated off by an active
@@ -596,7 +644,7 @@ function* shellServePlan<TEnv>(
   const descriptor = createShellCaptureDescriptor(
     ctx,
     key,
-    shellSearchSeed(url, reqCtx._searchParamsFilter),
+    base,
     url.origin,
     pprConfig,
     store,
@@ -626,10 +674,13 @@ function* shellServePlan<TEnv>(
   // A HIT replays the handler layer from the entry's doc record (`docKey`),
   // or, for a Prerender route, from the prerender store. An entry that has
   // neither is a MISS: serving it would run handlers after the commit.
+  // The entry must have rendered this request's location: the browser
+  // hydrates against the address bar.
   if (
     cached &&
     !cached.entry.navigationOnly &&
     (cached.entry.docKey !== undefined || route?.matched?.pr === true) &&
+    cached.entry.pathname === base.pathname &&
     isValidShellHit(cached.entry, ctx.version)
   ) {
     const document = openShellDocumentMetered(reqCtx, cached);
@@ -713,7 +764,9 @@ function* shellServePlan<TEnv>(
   // compile-time constant).
   const devShellLookup = resolveDevShellLookup(reqCtx, pprConfig);
   let buildHit: Awaited<ReturnType<typeof lookupBuildShell>> = null;
-  if (key !== baseKey) {
+  if (base.pathname !== undefined) {
+    // A build shell is the target's: never served under a visitor key.
+  } else if (key !== baseKey) {
     // Probed once per path without a build shell, and not again once the
     // route warned. A search-bearing URL never reads one: nothing to probe.
     const routeName = reqCtx._classifiedRoute?.routeKey;
@@ -845,7 +898,7 @@ function* preparePayloadPlan<TEnv>(
       kind: "payload",
       payload: {
         metadata: {
-          pathname: renderedLocation(reqCtx, url).pathname,
+          ...payloadLocation(reqCtx, url),
           // routerId is serialized on every payload (including within-session
           // ones) so the frontend can read the current app/router identity. It
           // always equals the current app's id: a cross-app navigation is
@@ -1209,16 +1262,6 @@ function renderPreparedRscResponse<TEnv>(
   if (sourceScoped) {
     rscHeaders["x-rsc-prefetch-scope"] = "source";
   }
-  // Enable browser HTTP caching for prefetch responses only.
-  // Requires a prefetch request (X-Rango-Prefetch, sent by Link prefetch
-  // fetch), a source-agnostic response (see sourceScoped above), and a
-  // configured cache-control value (false disables caching).
-  if (reqCtx._requestKind === "prefetch" && isPartial && !sourceScoped) {
-    const cc = ctx.router.prefetchCacheControl;
-    if (cc) {
-      rscHeaders["cache-control"] = cc;
-    }
-  }
   // prefetch: false (docs/design/prefetch-false.md, R7). A response that
   // carries deferred units answers one page's prefetch, and a fill is the
   // second half of one adoption: neither is reused by a shared cache or the
@@ -1248,7 +1291,7 @@ function renderPreparedRscResponse<TEnv>(
       reqCtx._activeRoutine &&
       createRenderStageTraceBridge(reqCtx._activeRoutine),
   };
-  return renderRscResponse(
+  const rendered = renderRscResponse(
     {
       ctx,
       request,
@@ -1272,6 +1315,11 @@ function renderPreparedRscResponse<TEnv>(
           }),
         },
   );
+  // A prefetch whose render reported an error is not kept (#1170).
+  if (reqCtx._requestKind !== "prefetch" || !isPartial) return rendered;
+  return rendered.then((response) =>
+    markPrefetchOnRenderError(response, reqCtx._renderErrors ?? []),
+  );
 }
 
 /**
@@ -1286,6 +1334,8 @@ function scheduleNavigationShellCapture<TEnv>(
   const { ctx, request, env, url, reqCtx } = input;
   const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry)!;
   const store = reqCtx._cacheStore!;
+  const base = requestShellBase(ctx, reqCtx, url);
+  if (!base) return;
   scheduleShellCapture(
     ctx,
     request,
@@ -1305,7 +1355,7 @@ function scheduleNavigationShellCapture<TEnv>(
     createShellCaptureDescriptor(
       ctx,
       captureKey,
-      shellSearchSeed(url, reqCtx._searchParamsFilter),
+      base,
       url.origin,
       pprConfig,
       store,
@@ -1464,10 +1514,13 @@ async function matchPartialWithPprReplay<TEnv>(
     return runMatch({ outcome: "BYPASS", reason: "cache-disabled" });
   }
 
+  const base = requestShellBase(ctx, reqCtx, url);
+  if (!base) return runMatch({ outcome: "BYPASS", reason: "rewritten" });
+
   // The visitor's own partition (resolveShellPartition): replay never
   // crosses into another partition's shell.
   const key = await resolveRequestShellKey(
-    buildShellKey(ctx.router.id, url, reqCtx._searchParamsFilter),
+    base.baseKey,
     routeSnapshot,
     store,
     reqCtx,
@@ -1806,6 +1859,9 @@ function serveShellHit(
   descriptor: ShellCaptureDescriptor,
 ): Response {
   const { entry, prelude: preludeBytes } = document;
+  // A visitor-keyed shell shows the visitor's URL: the document cache keys
+  // this response by the target.
+  if (entry.pathname !== undefined) reqCtx._payloadVisitorLocation = true;
   const metricsStore = reqCtx._metricsStore;
   // Per-stage tail timing for the `ppr:tail` Server-Timing mirror and the
   // perf console line: always in dev, in production only when this request
@@ -1867,8 +1923,8 @@ function serveShellHit(
       payload.metadata.initialTheme = entry.initialTheme as
         | import("../theme/types.js").Theme
         | undefined;
-      // Same for the location: the capture rendered the target's.
-      payload.metadata.pathname = url.pathname;
+      // Same for the location: the key's URL, or a visitor-keyed shell's.
+      payload.metadata.pathname = entry.pathname ?? url.pathname;
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).
@@ -1911,7 +1967,7 @@ function serveShellHit(
         nonce: undefined,
         // The shell key's own search — identical to the capture seed for
         // this key, so the resume tree matches the captured tree.
-        search: shellSearchSeed(url, reqCtx._searchParamsFilter),
+        search: descriptor.searchSeed,
         // The HIT request's origin — same host as the capture's (key-scoped).
         origin: url.origin,
         // The document cache reads the list before storing this composite.

package/src/rsc/server-action.ts

@@ -24,6 +24,7 @@ import { observePhase, PHASES } from "../router/instrument.js";
 import { resolveActionRefId } from "../router/is-action.js";
 import type { TraceSpan } from "../router/tracing.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
+import { payloadLocation } from "./full-payload.js";
 import { publicRouteName } from "../route-name.js";
 import type { RscPayload } from "./types.js";
 import {
@@ -323,6 +324,28 @@ export async function executeServerAction<TEnv>(
   };
 }
 
+/**
+ * The continuation for a rewrite pass after the action ran (#1145): a failed
+ * action's error boundary is re-matched on the target, since the one pass 1
+ * matched (or missed) is the rewriting route's.
+ */
+export async function continuationForRewritePass<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  continuation: ActionContinuation,
+): Promise<ActionContinuation> {
+  if (continuation.returnValue.ok) return continuation;
+  const errorBoundary =
+    (await ctx.router.matchError(
+      request,
+      { env },
+      continuation.actionContext.actionResult,
+      "route",
+    )) ?? undefined;
+  return { ...continuation, errorBoundary };
+}
+
 /**
  * Phase 2: Revalidate after action.
  *
@@ -513,7 +536,7 @@ function renderActionBoundaryResponse<TEnv>(
 
   const errorPayload: RscPayload = {
     metadata: {
-      pathname: url.pathname,
+      ...payloadLocation(reqCtx, url),
       // routerId exposed for the frontend (current app identity); see
       // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,
@@ -576,7 +599,7 @@ function renderRevalidationResponse<TEnv>(
 
   const payload: RscPayload = {
     metadata: {
-      pathname: url.pathname,
+      ...payloadLocation(reqCtx, url),
       // routerId exposed for the frontend (current app identity); see
       // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,

package/src/rsc/shell-capture-constants.ts

@@ -67,6 +67,8 @@ export const PPR_REPLAY_BYPASS_REASONS = [
   "no-segment-snapshot",
   "snapshot-miss",
   "explicit-cache-hit",
+  // A rewritten request whose rewrite chose no `.shell()`.
+  "rewritten",
 ] as const;
 
 /** One of {@link PPR_REPLAY_BYPASS_REASONS}. */
@@ -126,6 +128,26 @@ export function partitionShellKey(key: string, partition: string): string {
   return `${key}|${encodeURIComponent(partition)}`;
 }
 
+/**
+ * The shell key of a `rewrite(...).shell("visitor")` request: the visitor's
+ * URL, partitioned by `rw:` + the target's path and search (both searches
+ * filtered and sorted, shellSearchSeed). The visitor's URL keeps two public
+ * URLs of one target apart; the target keeps a conditional rewrite (an A/B
+ * arm, a lock) apart from the URL's own shell. The route's own partition
+ * composes after it.
+ */
+export function visitorShellKey(
+  routerId: string,
+  visitor: URL,
+  target: URL,
+  filter?: SearchParamsFilter,
+): string {
+  return partitionShellKey(
+    buildShellKey(routerId, visitor, filter),
+    `rw:${target.pathname}${shellSearchSeed(target, filter)}`,
+  );
+}
+
 /**
  * The navigation-only entry beside a document shell key (a cold partial
  * request's capture, rsc-rendering.ts). A suffix after the (encoded)

package/src/rsc/shell-capture.ts

@@ -1063,6 +1063,13 @@ export interface ShellCaptureDescriptor {
   debugSink?: (event: ShellCaptureDebugEvent) => void;
   /** Store the snapshot for navigation replay, never the captured HTML prelude. */
   navigationOnly?: true;
+  /**
+   * Set for a shell keyed by the visitor's URL (`rewrite(...).shell("visitor")`,
+   * visitorShellKey): the capture renders the visitor's location
+   * (`RequestContext._shellCaptureForVisitor`) and stores it as
+   * ShellCacheEntry.pathname.
+   */
+  pathname?: string;
   /**
    * lastStoredCaptureSeq(key) when a document request read the store and
    * missed. The request schedules its capture only after rendering the MISS,
@@ -1878,6 +1885,9 @@ async function attemptCapture(
     descriptor.navigationOnly ? { request, url } : undefined,
   );
   const { derivedCtx, freshHandleStore } = derivation;
+  if (descriptor.pathname !== undefined) {
+    derivedCtx._shellCaptureForVisitor = true;
+  }
   // The capture generation starts before matching or any snapshot read
   // (ShellCacheEntry.createdAt): a tag invalidated after it wins.
   const captureStartedAt = Date.now();
@@ -2647,6 +2657,7 @@ async function captureAndStoreShell(
           // default, #971). The serve tail replays it so the resume tree
           // matches the frozen prelude — see ShellCacheEntry.initialTheme.
           initialTheme: payloadInitialTheme(reqCtx),
+          pathname: capture.pathname,
           snapshot,
           prunedRecords: snapshot.length > 0 ? prunedRecords : undefined,
           // The canonical doc segment record's key, published by the doc

package/src/rsc/types.ts

@@ -18,6 +18,11 @@ import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 export interface RscPayload {
   metadata?: {
     pathname: string;
+    /**
+     * Path and search of the URL the route rendered for, when middleware
+     * rewrote the request there (full-payload.ts payloadLocation).
+     */
+    rewriteTarget?: string;
     segments: ResolvedSegment[];
     /** Router instance ID. When this changes between navigations, the client
      *  discards cached segments and does a full tree replacement (app switch). */