@rangojs/router 0.23.0 → 0.24.0

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

package/src/rsc/rewrite-passes.ts

@@ -0,0 +1,203 @@
+/**
+ * The pass loop that honors `throw rewrite()` (route-definition/rewrite.ts):
+ * one catch around the global middleware chain moves the same request
+ * context to the target (server/request-context.ts rebaseRequestContext) and
+ * runs the request again from the top, as a direct visit to the target
+ * would run it. Shared by the request handler (rsc/handler.ts) and the
+ * dispatch testing primitive, so the two cannot drift.
+ */
+
+import { RewriteLoopError } from "../errors.js";
+import {
+  describeRewriteTarget,
+  isRewrite,
+  rewriteNotSupported,
+  type Rewrite,
+} from "../route-definition/rewrite.js";
+import { prefixBasename } from "../router/basename.js";
+import { createReverseFunction } from "../router/handler-context.js";
+import { stripInternalParams } from "../router/internal-params.js";
+import {
+  rebaseRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { recordRewriteHop } from "../server/rewrite-trail.js";
+
+/** Response header naming the route path a rewritten request rendered. */
+export const REWRITE_HEADER = "x-rango-rewrite";
+
+/**
+ * Resolve a rewrite's target against the router's route map (global names,
+ * no param auto-fill, as middleware `ctx.reverse`) and the request origin.
+ * A path is basename-prefixed like `redirect()` and must stay under the
+ * basename once normalized (`/../admin` cannot step out of it). The
+ * target's own `_rsc*` params are dropped: only the visitor's transport
+ * params carry over. Throws for an unknown name, a missing param, another
+ * origin or a path outside the basename.
+ */
+export function resolveRewriteTarget(
+  rewrite: Rewrite,
+  routeMap: Record<string, string>,
+  base: URL,
+  basename?: string,
+): URL {
+  const { target } = rewrite;
+  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)(
+          target.name,
+          target.params ?? {},
+          target.search,
+        );
+  const resolved = stripInternalParams(new URL(path, base.origin));
+  if (resolved.origin !== base.origin) {
+    throw new TypeError(
+      `${describeRewriteTarget(target)} must name a path in this app, not another origin.`,
+    );
+  }
+  if (
+    basename &&
+    resolved.pathname !== basename &&
+    !resolved.pathname.startsWith(basename + "/")
+  ) {
+    throw new TypeError(
+      `${describeRewriteTarget(target)} resolves to ${resolved.pathname}, outside the router's basename ${basename}.`,
+    );
+  }
+  resolved.hash = "";
+  return resolved;
+}
+
+/**
+ * The raw URL of a rewritten pass: the target's path and search plus the
+ * visitor's internal `_rsc*` transport params, so a navigation stays a
+ * navigation (same segments, version, partial flag).
+ */
+function rewriteTransportUrl(target: URL, visitorRaw: URL): URL {
+  const raw = new URL(target);
+  visitorRaw.searchParams.forEach((value, key) => {
+    if (key.startsWith("_rsc")) raw.searchParams.append(key, value);
+  });
+  return raw;
+}
+
+/** The next pass of a rewritten request. */
+export interface RewritePass {
+  request: Request;
+  /** The pass's raw URL, `_rsc*` params included. */
+  url: URL;
+  /** The target's clean URL. */
+  target: URL;
+  hops: number;
+}
+
+/**
+ * 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.
+ */
+export function applyRewrite(
+  rewrite: Rewrite,
+  passRequest: Request,
+  reqCtx: RequestContext<any>,
+  routeMap: Record<string, string>,
+  basename: string | undefined,
+): RewritePass {
+  // A loader fetch first: `load()` with a body is a POST, and its refusal
+  // is the loader fetch's.
+  if (reqCtx.originalUrl.searchParams.has("_rsc_loader")) {
+    throw rewriteNotSupported(rewrite, "loader-fetch");
+  }
+  if (passRequest.method !== "GET" && passRequest.method !== "HEAD") {
+    throw rewriteNotSupported(rewrite, "mutation");
+  }
+  const target = resolveRewriteTarget(rewrite, routeMap, reqCtx.url, basename);
+  const hops = recordRewriteHop(reqCtx, reqCtx.url, target);
+  const url = rewriteTransportUrl(target, reqCtx.originalUrl);
+  const request = new Request(url, passRequest);
+  rebaseRequestContext(reqCtx, request, url);
+  return { request, url, target, hops };
+}
+
+/** The response to a rewrite loop. */
+export function loopDetectedResponse(): Response {
+  return new Response("Loop Detected", {
+    status: 508,
+    headers: { "content-type": "text/plain;charset=utf-8" },
+  });
+}
+
+export interface RewritePassesOptions {
+  reqCtx: RequestContext<any>;
+  /** The visitor's request and raw URL: the first pass. */
+  request: Request;
+  url: URL;
+  routeMap: () => Record<string, string>;
+  basename: string | undefined;
+  /** One pass: the global chain matched on `url`'s path around the core handler. */
+  runPass: (request: Request, url: URL) => Promise<Response>;
+  /** After a hop moved the context to its target. */
+  onHop?: (pass: RewritePass) => void;
+  /** Report a rewrite the request cannot take (onError, phase "routing"). */
+  report: (error: unknown, at: { request: Request; url: URL }) => void;
+  /**
+   * The response for a refused rewrite other than a loop (a loader fetch's
+   * error response); undefined rethrows the error.
+   */
+  refuse?: (error: unknown, rewrite: Rewrite) => Response | undefined;
+}
+
+export interface RewritePassesResult {
+  response: Response;
+  /** The pathname the final pass rendered, when a rewrite took the request there. */
+  rewrittenTo?: string;
+}
+
+/**
+ * Run the request pass by pass until one produces a response. A `Rewrite`
+ * that unwinds a pass moves the context to its target and runs the next;
+ * a loop answers 508; a rewrite the request cannot take is reported and
+ * becomes `refuse`'s response, or is thrown.
+ */
+export async function runRewritePasses(
+  opts: RewritePassesOptions,
+): Promise<RewritePassesResult> {
+  let request = opts.request;
+  let url = opts.url;
+  let rewrittenTo: string | undefined;
+  for (;;) {
+    let rewrite: Rewrite;
+    try {
+      return { response: await opts.runPass(request, url), rewrittenTo };
+    } catch (error) {
+      if (!isRewrite(error)) throw error;
+      rewrite = error;
+    }
+    let pass: RewritePass;
+    try {
+      pass = applyRewrite(
+        rewrite,
+        request,
+        opts.reqCtx,
+        opts.routeMap(),
+        opts.basename,
+      );
+    } catch (error) {
+      opts.report(error, { request, url });
+      if (error instanceof RewriteLoopError) {
+        return { response: loopDetectedResponse() };
+      }
+      const refused = opts.refuse?.(error, rewrite);
+      if (refused) return { response: refused };
+      throw error;
+    }
+    request = pass.request;
+    url = pass.url;
+    rewrittenTo = pass.target.pathname;
+    opts.onHop?.(pass);
+  }
+}

package/src/rsc/rsc-rendering.ts

@@ -51,7 +51,7 @@ import {
 import type { HandlerContext } from "./handler-context.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
 import { publicRouteName } from "../route-name.js";
-import { buildFullPayload } from "./full-payload.js";
+import { buildFullPayload, renderedLocation } from "./full-payload.js";
 import {
   capShellWindow,
   lastStoredCaptureSeq,
@@ -845,7 +845,7 @@ function* preparePayloadPlan<TEnv>(
       kind: "payload",
       payload: {
         metadata: {
-          pathname: url.pathname,
+          pathname: renderedLocation(reqCtx, url).pathname,
           // 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
@@ -1867,6 +1867,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;
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).

package/src/rsc/ssr-setup.ts

@@ -22,6 +22,7 @@ import {
   RSC_WIRE_MIME,
 } from "../router/content-negotiation.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { renderedLocation } from "./full-payload.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
 
@@ -38,6 +39,8 @@ export const SSR_SETUP_VAR = "__ssrSetup";
  * lazily so stores created after kickoff are still captured). Without a
  * getter the promises run bare — no `.then()` microtasks, no
  * `performance.now()` calls — keeping the non-debug hot path lean.
+ * `ssrModule` reuses a load already started (a rewritten request's earlier
+ * pass).
  */
 export function startSSRSetup<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -45,16 +48,17 @@ export function startSSRSetup<TEnv>(
   env: TEnv,
   url: URL,
   getMetricsStore?: () => MetricsStore | undefined,
+  ssrModule?: Promise<SSRModule>,
 ): Promise<SSRSetup> {
   if (!getMetricsStore) {
     return Promise.all([
-      ctx.loadSSRModule(),
+      ssrModule ?? ctx.loadSSRModule(),
       ctx.resolveStreamMode(request, env, url),
     ]);
   }
   const start = performance.now();
   return Promise.all([
-    ctx.loadSSRModule().then((mod) => {
+    (ssrModule ?? ctx.loadSSRModule()).then((mod) => {
       appendMetric(
         getMetricsStore(),
         "ssr:module-load",
@@ -110,7 +114,9 @@ export function createSsrHtmlStage<TEnv>(
       options.url,
       options.metricsStore,
     );
-    const renderErrors = _getRequestContext()?._renderErrors;
+    const reqCtx = _getRequestContext();
+    const renderErrors = reqCtx?._renderErrors;
+    const location = renderedLocation(reqCtx, options.url);
     return {
       render: () =>
         // search: the LIVE request's query string, threaded out-of-band into
@@ -121,11 +127,11 @@ export function createSsrHtmlStage<TEnv>(
         ssrModule.renderHTML(flight.stream, {
           ...options.render,
           streamMode,
-          search: options.url.search,
+          search: location.search,
           // origin: same out-of-band channel — seeds the SSR store location
           // so origin-dependent markup (Link's data-external) agrees with the
           // browser's window.location across hydration.
-          origin: options.url.origin,
+          origin: location.origin,
           // A component that throws inside a Suspense boundary leaves an
           // errored boundary in a completed document; the document cache
           // reads the list before storing it.

package/src/server/cookie-parse.ts

@@ -10,23 +10,47 @@
 export function parseCookiesFromHeader(
   cookieHeader: string | null,
 ): Record<string, string> {
-  if (!cookieHeader) return {};
-
   const cookies: Record<string, string> = {};
-  const pairs = cookieHeader.split(";");
 
-  for (const pair of pairs) {
-    const [name, ...rest] = pair.trim().split("=");
-    if (name) {
-      const raw = rest.join("=");
-      try {
-        cookies[name] = decodeURIComponent(raw);
-      } catch {
-        // Malformed percent-encoding: fall back to raw value
-        cookies[name] = raw;
+  if (cookieHeader) {
+    for (const pair of cookieHeader.split(";")) {
+      const [name, ...rest] = pair.trim().split("=");
+      if (name) {
+        const raw = rest.join("=");
+        let value: string;
+        try {
+          value = decodeURIComponent(raw);
+        } catch {
+          // Malformed percent-encoding: fall back to raw value
+          value = raw;
+        }
+        setCookie(cookies, name, value);
       }
     }
   }
 
+  // Null prototype (#1109): cookie names come from the request, so a lookup
+  // must never answer `constructor` or `toString` with an inherited member.
+  // Set once at the end: Object.create(null) starts in dictionary mode, which
+  // makes a spread of the jar several times slower.
+  Object.setPrototypeOf(cookies, null);
   return cookies;
 }
+
+/** `cookies[name] = value`, a cookie named `__proto__` as an own key too. */
+function setCookie(
+  cookies: Record<string, string>,
+  name: string,
+  value: string,
+): void {
+  if (name === "__proto__") {
+    Object.defineProperty(cookies, name, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  } else {
+    cookies[name] = value;
+  }
+}

package/src/server/cookie-store.ts

@@ -367,12 +367,16 @@ function createCookieStore(
 
     getAll(name?: string): Cookie[] {
       recordLoaderIdentityRead("cookies()");
-      const all = ctx._readCookies();
       if (name !== undefined) {
-        const value = all[name];
+        // The single-name read, not an index into the plain object
+        // _readCookies() returns: that would answer an inherited member.
+        const value = ctx._readCookie(name);
         return value !== undefined ? [{ name, value }] : [];
       }
-      return Object.entries(all).map(([n, v]) => ({ name: n, value: v }));
+      return Object.entries(ctx._readCookies()).map(([n, v]) => ({
+        name: n,
+        value: v,
+      }));
     },
 
     has(name: string): boolean {