@rangojs/router 0.22.1 → 0.24.0

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.

package/src/rsc/loader-fetch.ts

@@ -12,6 +12,7 @@
  */
 
 import { requestHeaders } from "../server/request-headers.js";
+import { FORBIDDEN_KEYS } from "../context-var.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
 import { isDataNotFoundError } from "../errors.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
@@ -33,18 +34,57 @@ import {
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
+export interface LoaderErrorMeta<TEnv> {
+  request: Request;
+  url: URL;
+  env: TEnv;
+  loaderId: string;
+}
+
+/**
+ * A text/x-component Response carrying `{ loaderResult: null, loaderError }`,
+ * the payload `load()` turns into a rejection with `loaderError.message`. A
+ * plain-text body would reject with React's opaque "Connection closed.".
+ * Render failures report through onError("rendering").
+ */
+export function renderLoaderError<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  loaderError: { message: string; name: string },
+  status: number,
+  meta: LoaderErrorMeta<TEnv>,
+): Response {
+  const { request, url, env, loaderId } = meta;
+  const rscStream = ctx.renderToReadableStream(
+    { loaderResult: null, loaderError },
+    {
+      onError: (renderError: unknown) => {
+        ctx.callOnError(renderError, "rendering", {
+          request,
+          url,
+          env,
+          loaderName: loaderId,
+        });
+      },
+    },
+  );
+
+  return createResponseWithMergedHeaders(rscStream, {
+    status,
+    headers: { "content-type": "text/x-component;charset=utf-8" },
+  });
+}
+
 /**
  * Build the 500 RSC error Response for a failed fetchable loader. Shared by the
  * module-load-error catch (the import itself threw) and the loader-execution
- * error catch — both call onError("loader"), serialize the same dev-gated error
- * payload via renderToReadableStream (reporting render failures through
- * onError("rendering")), and return a 500 text/x-component Response. The only
- * per-site difference is the console.error label, passed in.
+ * error catch — both call onError("loader") and serialize the same dev-gated
+ * error payload. The only per-site difference is the console.error label,
+ * passed in.
  */
 function buildLoaderErrorResponse<TEnv>(
   ctx: HandlerContext<TEnv>,
   error: unknown,
-  meta: { request: Request; url: URL; env: TEnv; loaderId: string },
+  meta: LoaderErrorMeta<TEnv>,
   logLabel: string,
 ): Response {
   const { request, url, env, loaderId } = meta;
@@ -61,9 +101,9 @@ function buildLoaderErrorResponse<TEnv>(
   });
 
   const err = error instanceof Error ? error : new Error(String(error));
-  const errorPayload = {
-    loaderResult: null,
-    loaderError: {
+  return renderLoaderError(
+    ctx,
+    {
       message: isDev ? err.message : "An error occurred",
       // Gate err.name to dev. In production it leaks the consumer's error class
       // name (e.g. AuthError, PrismaClientKnownRequestError) to the client; the
@@ -71,22 +111,9 @@ function buildLoaderErrorResponse<TEnv>(
       // Matches sanitizeError's dev-only name contract.
       name: isDev ? err.name : "Error",
     },
-  };
-  const rscStream = ctx.renderToReadableStream(errorPayload, {
-    onError: (renderError: unknown) => {
-      ctx.callOnError(renderError, "rendering", {
-        request,
-        url,
-        env,
-        loaderName: loaderId,
-      });
-    },
-  });
-
-  return createResponseWithMergedHeaders(rscStream, {
-    status: 500,
-    headers: { "content-type": "text/x-component;charset=utf-8" },
-  });
+    500,
+    meta,
+  );
 }
 
 export async function handleLoaderFetch<TEnv>(
@@ -183,6 +210,21 @@ export async function handleLoaderFetch<TEnv>(
     }
   }
 
+  // The params become ctx.params, so they hold what a route param can: string
+  // keys and string values, never a reserved key (#1109). The message is the
+  // router's own, so production sends it too.
+  if (!isLoaderParams(loaderParams)) {
+    return renderLoaderError(
+      ctx,
+      {
+        message: `Invalid loader params: expected an object of string values without the reserved keys ${[...FORBIDDEN_KEYS].join(", ")}`,
+        name: "Error",
+      },
+      400,
+      { request, url, env, loaderId },
+    );
+  }
+
   // Execute the loader with middleware.
   // finalizeResponse drains onResponse callbacks that middleware short-circuits
   // may leave behind (executeLoaderMiddleware does not finalize them itself).
@@ -304,3 +346,16 @@ export async function handleLoaderFetch<TEnv>(
     );
   }
 }
+
+function isLoaderParams(value: unknown): value is Record<string, string> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN_KEYS.has(key)) return false;
+    if (typeof (value as Record<string, unknown>)[key] !== "string") {
+      return false;
+    }
+  }
+  return true;
+}

package/src/rsc/response-cache-serve.ts

@@ -19,6 +19,7 @@
  * type-only import (erased at build).
  */
 
+import { isRewrite } from "../route-definition/rewrite.js";
 import type { CacheScope } from "../cache/cache-scope.js";
 import {
   _getRequestContext,
@@ -159,10 +160,13 @@ export async function serveResponseRouteWithCache(
   // Finding #3 as document-cache.ts shouldCacheResponse.
   // Only store GET: HEAD may branch on method; sharing a write slot with GET
   // can poison subsequent GET bodies. HEAD still reads the GET key below.
+  // Nor a body a rewritten request built from the visitor's URL
+  // (ctx.rewrittenFrom, server/rewrite-trail.ts): the key is the target's.
   const canStore = (response: Response): boolean =>
     method === "GET" &&
     isCacheableStatus(response.status) &&
-    !hasPerClientSignal(response.headers);
+    !hasPerClientSignal(response.headers) &&
+    !reqCtx._payloadVisitorLocation;
 
   // Reject unsafe persisted entries on read (pre-upgrade poison / store bugs).
   const canServeCached = (response: Response): boolean =>
@@ -206,6 +210,8 @@ export async function serveResponseRouteWithCache(
           const fresh = finalizeResponse(await executeHandler());
           if (canStore(fresh)) await putFresh(store, fresh, start);
         } catch (error) {
+          // The route now rewrites: nothing to refresh this entry with.
+          if (isRewrite(error)) return;
           reportCacheError(
             error,
             "stale-revalidation",
@@ -227,7 +233,17 @@ export async function serveResponseRouteWithCache(
 
   // Cache miss: execute the handler and cache the result when storeable.
   const start = executionStart();
-  const response = finalizeResponse(await executeHandler());
+  let response: Response;
+  try {
+    response = finalizeResponse(await executeHandler());
+  } catch (error) {
+    // Route middleware rewrote: the request runs again as the target, whose
+    // response runs these pre-handler callbacks.
+    if (isRewrite(error)) {
+      reqCtx._onResponseCallbacks.unshift(...savedCallbacks);
+    }
+    throw error;
+  }
   if (canStore(response)) {
     // Clone SYNCHRONOUSLY here, before returning. The original `response` is
     // handed back to the middleware chain, where mergeResponse rebuilds it as

package/src/rsc/response-route-handler.ts

@@ -10,6 +10,7 @@ import { RouterError } from "../errors.js";
 import { getRequestContext } from "../server/request-context.js";
 import { contextGet, isNonCacheable } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
 import { createCacheScope } from "../cache/cache-scope.js";
 import { serveResponseRouteWithCache } from "./response-cache-serve.js";
@@ -26,6 +27,7 @@ import {
 import type { HandlerContext } from "./handler-context.js";
 import { createProblemDetails } from "./response-error.js";
 import {
+  createReloadResponse,
   createResponseWithMergedHeaders,
   finalizeResponse,
   isCacheableStatus,
@@ -67,13 +69,7 @@ export async function handleResponseRoute<TEnv>(
   // Partial requests (client-side navigation) to response routes
   // get X-RSC-Reload to trigger hard navigation in the browser
   if (isPartial) {
-    return createResponseWithMergedHeaders(null, {
-      status: 200,
-      headers: {
-        "X-RSC-Reload": stripInternalParams(url).toString(),
-        "content-type": "text/x-component;charset=utf-8",
-      },
-    });
+    return createReloadResponse(getRequestContext(), url);
   }
 
   // Build lightweight context for response handler
@@ -101,6 +97,7 @@ export async function handleResponseRoute<TEnv>(
   };
   // Brand with taint symbol so "use cache" detects it as request-scoped
   // and extracts route-identifying properties (params, pathname, _responseType)
+  defineRewrittenFrom(responseHandlerCtx, reqCtx);
   (responseHandlerCtx as any)[NOCACHE_SYMBOL] = true;
 
   // Call handler directly, wrapped by route middleware if present