@rangojs/router 0.0.0-experimental.125 → 0.0.0-experimental.126

package/src/route-definition/redirect.ts

@@ -4,6 +4,7 @@ import {
   getRequestContext,
   _getRequestContext,
 } from "../server/request-context.js";
+import { markExternalRedirect } from "../redirect-origin.js";
 
 /**
  * Create a soft redirect Response for middleware short-circuit
@@ -39,6 +40,11 @@ import {
  *   status: 303,
  *   state: [Flash({ text: "Session expired" })],
  * });
+ *
+ * // Off-host redirect (opt out of the same-origin guard). Without
+ * // `external: true`, a cross-origin target is blocked and replaced with the
+ * // app root, matching the client's open-redirect protection.
+ * return redirect('https://accounts.example.com/oauth', { external: true });
  * ```
  */
 export function redirect(url: string, status?: number): Response;
@@ -47,13 +53,18 @@ export function redirect(
   options: {
     status?: number;
     state?: LocationStateEntry | LocationStateEntry[];
+    external?: boolean;
   },
 ): Response;
 export function redirect(
   url: string,
   statusOrOptions?:
     | number
-    | { status?: number; state?: LocationStateEntry | LocationStateEntry[] },
+    | {
+        status?: number;
+        state?: LocationStateEntry | LocationStateEntry[];
+        external?: boolean;
+      },
 ): Response {
   const status =
     typeof statusOrOptions === "number"
@@ -61,6 +72,8 @@ export function redirect(
       : (statusOrOptions?.status ?? 302);
   const state =
     typeof statusOrOptions === "object" ? statusOrOptions?.state : undefined;
+  const external =
+    typeof statusOrOptions === "object" ? statusOrOptions?.external : undefined;
 
   if (state) {
     const ctx = requireRequestContext();
@@ -101,11 +114,22 @@ export function redirect(
     resolvedUrl = url === "/" ? bn : bn + url;
   }
 
-  return new Response(null, {
-    status,
-    headers: {
-      Location: resolvedUrl,
-      "X-RSC-Redirect": "soft",
-    },
-  });
+  const headers: Record<string, string> = {
+    Location: resolvedUrl,
+    "X-RSC-Redirect": "soft",
+  };
+
+  const response = new Response(null, { status, headers });
+
+  // Mark an explicit off-host redirect with an out-of-band brand so the
+  // same-origin guard (rsc/redirect-guard.ts) lets it through. The brand is a
+  // WeakSet membership on this Response object -- NOT a wire header -- so the
+  // opt-in cannot be forged by an attacker-controlled upstream response a
+  // proxy-style response route might copy. The internal redirect-rebuild paths
+  // transfer the brand; the guard reads and clears it (see markExternalRedirect).
+  if (external) {
+    markExternalRedirect(response);
+  }
+
+  return response;
 }

package/src/route-definition/resolve-handler-use.ts

@@ -139,6 +139,12 @@ export function mergeHandlerUse(
   mountSite: string,
 ): (() => any[]) | undefined {
   if (!handlerUse && !explicitUse) return undefined;
+  // Validation asymmetry (intentional, pre-1.0): only handler.use() items are
+  // checked against the mount-site allow-list (validateHandlerUseItems below).
+  // Explicit use() items pass through unvalidated on both the explicit-only
+  // branch here and the merged branch, so a structurally-valid-but-prohibited
+  // item (e.g. middleware() inside a parallel slot) is not rejected at this seam.
+  // Documented rather than enforced for now; revisit before 1.0 (#569).
   if (!handlerUse) return explicitUse;
   if (!explicitUse) {
     return () => {

package/src/router/find-match.ts

@@ -110,7 +110,6 @@ export function createFindMatch<TEnv = any>(
             entry,
             routeKey: trieResult.routeKey,
             params: trieResult.params,
-            optionalParams: new Set(trieResult.optionalParams || []),
             redirectTo: trieResult.redirectTo,
             ...(trieResult.pr ? { pr: true } : {}),
             ...(trieResult.pt ? { pt: true } : {}),

package/src/router/loader-resolution.ts

@@ -20,6 +20,7 @@ import type {
   ErrorInfo,
 } from "../types";
 import { isHandle, collectHandleData, type Handle } from "../handle.js";
+import { withDefer } from "../defer.js";
 import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
@@ -444,28 +445,28 @@ export function setupLoaderAccess<TEnv>(
         );
       }
 
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        if (!store) return;
-
-        if (typeof dataOrFn === "function") {
-          // Run the callback inside the push-callback scope so ctx.use(loader)
-          // calls it makes — including after its own awaits, for an async
-          // callback — are not registered as handler-to-loader deps and do not
-          // trip the deadlock guard. A pushed promise value is not tracked by
-          // handleStore.settled and does not block segment resolution, so it
-          // cannot form a rendered() deadlock. The ALS scope (not a plain
-          // boolean) is what survives the callback's awaits.
-          const result = runInsidePushCallbackScope(() =>
-            (dataOrFn as () => Promise<unknown>)(),
-          );
-          store.push(handle.$$id, segmentId, result);
-          return;
-        }
+      return withDefer(
+        (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+          if (!store) return;
+
+          if (typeof dataOrFn === "function") {
+            // Run the callback inside the push-callback scope so ctx.use(loader)
+            // calls it makes — including after its own awaits, for an async
+            // callback — are not registered as handler-to-loader deps and do not
+            // trip the deadlock guard. A pushed promise value is not tracked by
+            // handleStore.settled and does not block segment resolution, so it
+            // cannot form a rendered() deadlock. The ALS scope (not a plain
+            // boolean) is what survives the callback's awaits.
+            const result = runInsidePushCallbackScope(() =>
+              (dataOrFn as () => Promise<unknown>)(),
+            );
+            store.push(handle.$$id, segmentId, result);
+            return;
+          }
 
-        store.push(handle.$$id, segmentId, dataOrFn);
-      };
+          store.push(handle.$$id, segmentId, dataOrFn);
+        },
+      );
     }
 
     // Deadlock guard and handler-to-loader dependency tracking.

package/src/router/match-middleware/cache-lookup.ts

@@ -93,7 +93,7 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import { getRouterContext } from "../router-context.js";
+import { getRouterContext, type RouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import { treeHasStreaming } from "./segment-resolution.js";
@@ -150,6 +150,81 @@ async function ensurePrerenderDeps() {
  * Deserializes segments, replays handle data, yields segments with partial
  * navigation nullification, and resolves fresh loaders.
  */
+// Resolve loaders fresh on a cache hit (loaders are NEVER cached) and yield
+// the loader segments, updating state.matchedIds and pushing the loader-resolve
+// + cache-hit metrics. Shared verbatim by the prerender-store path
+// (yieldFromStore) and the runtime cache-hit path (withCacheLookup). The router
+// resolve fns are passed in (captured early by the callers) rather than re-read
+// from getRouterContext() here, because that is ALS-backed and the callers run
+// awaits before reaching this point (workerd can disrupt ALS mid-pipeline).
+async function* resolveFreshLoadersAndYield<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  pipelineStart: number,
+  ms: MatchContext<TEnv>["metricsStore"],
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
+): AsyncGenerator<ResolvedSegment> {
+  const loaderStart = performance.now();
+
+  if (ctx.isFullMatch) {
+    if (resolveLoadersOnly) {
+      const loaderSegments = await ctx.Store.run(() =>
+        resolveLoadersOnly(ctx.entries, ctx.handlerContext),
+      );
+      state.matchedIds = state.cachedMatchedIds!;
+      for (const segment of loaderSegments) {
+        yield segment;
+      }
+    } else {
+      state.matchedIds = state.cachedMatchedIds!;
+    }
+  } else {
+    if (resolveLoadersOnlyWithRevalidation) {
+      const loaderResult = await ctx.Store.run(() =>
+        resolveLoadersOnlyWithRevalidation(
+          ctx.entries,
+          ctx.handlerContext,
+          ctx.clientSegmentSet,
+          ctx.prevParams,
+          ctx.request,
+          ctx.prevUrl,
+          ctx.url,
+          ctx.routeKey,
+          ctx.actionContext,
+          // Loaders are never cached in the segment cache, so segment staleness
+          // must not propagate; browser-sent staleness (ctx.stale) still must.
+          ctx.stale || undefined,
+        ),
+      );
+      state.matchedIds = [
+        ...state.cachedMatchedIds!,
+        ...loaderResult.matchedIds,
+      ];
+      for (const segment of loaderResult.segments) {
+        yield segment;
+      }
+    } else {
+      state.matchedIds = state.cachedMatchedIds!;
+    }
+  }
+
+  if (ms) {
+    const loaderEnd = performance.now();
+    ms.metrics.push({
+      label: "pipeline:loader-resolve",
+      duration: loaderEnd - loaderStart,
+      startTime: loaderStart - ms.requestStart,
+      depth: 1,
+    });
+    ms.metrics.push({
+      label: "pipeline:cache-hit",
+      duration: loaderEnd - pipelineStart,
+      startTime: pipelineStart - ms.requestStart,
+    });
+  }
+}
+
 async function* yieldFromStore<TEnv>(
   entry: PrerenderEntry,
   ctx: MatchContext<TEnv>,
@@ -216,64 +291,15 @@ async function* yieldFromStore<TEnv>(
     yield segment;
   }
 
-  // Resolve loaders fresh (loaders are never pre-rendered/cached)
-  const ms = ctx.metricsStore;
-  const loaderStart = performance.now();
-
-  if (ctx.isFullMatch) {
-    if (resolveLoadersOnly) {
-      const loaderSegments = await ctx.Store.run(() =>
-        resolveLoadersOnly(ctx.entries, ctx.handlerContext),
-      );
-      state.matchedIds = state.cachedMatchedIds!;
-      for (const segment of loaderSegments) {
-        yield segment;
-      }
-    } else {
-      state.matchedIds = state.cachedMatchedIds!;
-    }
-  } else {
-    if (resolveLoadersOnlyWithRevalidation) {
-      const loaderResult = await ctx.Store.run(() =>
-        resolveLoadersOnlyWithRevalidation(
-          ctx.entries,
-          ctx.handlerContext,
-          ctx.clientSegmentSet,
-          ctx.prevParams,
-          ctx.request,
-          ctx.prevUrl,
-          ctx.url,
-          ctx.routeKey,
-          ctx.actionContext,
-          ctx.stale || undefined,
-        ),
-      );
-      state.matchedIds = [
-        ...state.cachedMatchedIds!,
-        ...loaderResult.matchedIds,
-      ];
-      for (const segment of loaderResult.segments) {
-        yield segment;
-      }
-    } else {
-      state.matchedIds = state.cachedMatchedIds!;
-    }
-  }
-
-  if (ms) {
-    const loaderEnd = performance.now();
-    ms.metrics.push({
-      label: "pipeline:loader-resolve",
-      duration: loaderEnd - loaderStart,
-      startTime: loaderStart - ms.requestStart,
-      depth: 1,
-    });
-    ms.metrics.push({
-      label: "pipeline:cache-hit",
-      duration: loaderEnd - pipelineStart,
-      startTime: pipelineStart - ms.requestStart,
-    });
-  }
+  // Resolve loaders fresh (loaders are never pre-rendered/cached).
+  yield* resolveFreshLoadersAndYield(
+    ctx,
+    state,
+    pipelineStart,
+    ctx.metricsStore,
+    resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation,
+  );
 }
 
 /**
@@ -550,71 +576,15 @@ export function withCacheLookup<TEnv>(
       barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
     }
 
-    const Store = ctx.Store;
-    const loaderStart = performance.now();
-
-    if (ctx.isFullMatch) {
-      if (resolveLoadersOnly) {
-        const loaderSegments = await Store.run(() =>
-          resolveLoadersOnly(ctx.entries, ctx.handlerContext),
-        );
-
-        state.matchedIds = state.cachedMatchedIds!;
-
-        for (const segment of loaderSegments) {
-          yield segment;
-        }
-      } else {
-        state.matchedIds = state.cachedMatchedIds!;
-      }
-    } else {
-      if (resolveLoadersOnlyWithRevalidation) {
-        const loaderResult = await Store.run(() =>
-          resolveLoadersOnlyWithRevalidation(
-            ctx.entries,
-            ctx.handlerContext,
-            ctx.clientSegmentSet,
-            ctx.prevParams,
-            ctx.request,
-            ctx.prevUrl,
-            ctx.url,
-            ctx.routeKey,
-            ctx.actionContext,
-            // Loaders are never cached in the segment cache, so segment
-            // staleness (cacheResult.shouldRevalidate) must not propagate.
-            // But browser-sent staleness (ctx.stale) — indicating an action
-            // happened in this or another tab — must still reach loaders.
-            ctx.stale || undefined,
-          ),
-        );
-
-        // Update state with fresh loader matchedIds
-        state.matchedIds = [
-          ...state.cachedMatchedIds!,
-          ...loaderResult.matchedIds,
-        ];
-
-        // Yield fresh loader segments
-        for (const segment of loaderResult.segments) {
-          yield segment;
-        }
-      } else {
-        state.matchedIds = state.cachedMatchedIds!;
-      }
-    }
-    if (ms) {
-      const loaderEnd = performance.now();
-      ms.metrics.push({
-        label: "pipeline:loader-resolve",
-        duration: loaderEnd - loaderStart,
-        startTime: loaderStart - ms.requestStart,
-        depth: 1,
-      });
-      ms.metrics.push({
-        label: "pipeline:cache-hit",
-        duration: loaderEnd - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
-      });
-    }
+    // Resolve loaders fresh (loaders are never cached). Shared with the
+    // prerender-store path via resolveFreshLoadersAndYield.
+    yield* resolveFreshLoadersAndYield(
+      ctx,
+      state,
+      pipelineStart,
+      ms,
+      resolveLoadersOnly,
+      resolveLoadersOnlyWithRevalidation,
+    );
   };
 }

package/src/router/match-middleware/segment-resolution.ts

@@ -193,7 +193,6 @@ export function withSegmentResolution<TEnv>(
           ctx.request,
           ctx.prevUrl,
           ctx.url,
-          ctx.loaderPromises,
           ctx.actionContext,
           ctx.interceptResult,
           ctx.localRouteName,

package/src/router/middleware-types.ts

@@ -76,7 +76,6 @@ export interface MiddlewareEntry<TEnv = any> {
   regex: RegExp | null;
   paramNames: string[];
   handler: MiddlewareFn<TEnv>;
-  mountPrefix: string | null;
 }
 
 export interface ResponseHolder {

package/src/router/middleware.ts

@@ -12,20 +12,23 @@ import type {
   ResponseHolder,
 } from "./middleware-types.js";
 import { _getRequestContext } from "../server/request-context.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
 import { stripInternalParams } from "./handler-context.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
-// Re-export types and cookie utilities consumed through this module's path.
+// Re-export types consumed through this module's path.
 export type {
   CookieOptions,
-  MiddlewareCollectableEntry,
   MiddlewareContext,
   MiddlewareEntry,
   MiddlewareFn,
 } from "./middleware-types.js";
-export { parseCookies, serializeCookie } from "./middleware-cookies.js";
 
 const MIDDLEWARE_METRIC_DEPTH = 1;
 const POST_METRIC_MIN_DURATION_MS = 0.01;
@@ -238,9 +241,13 @@ export function createMiddlewareContext<TEnv>(
 
     reverse:
       reverse ??
-      ((name: string) => {
+      ((
+        name: string,
+        _params?: Record<string, string>,
+        _search?: Record<string, unknown>,
+      ) => {
         throw new Error(
-          `ctx.reverse() is not available - route map was not provided to middleware context`,
+          `ctx.reverse(${JSON.stringify(name)}) is not available: no route map is bound to this middleware context.`,
         );
       }),
 
@@ -293,6 +300,10 @@ function mergeStubHeaders(
   stubOverridesNonCookie: boolean,
 ): void {
   stub.forEach((value, name) => {
+    // The reserved external-redirect marker is internal and never a trust
+    // signal; never copy a stub value (e.g. a stray ctx.header() call) onto a
+    // browser-facing response. The opt-in is the out-of-band brand.
+    if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
     if (name.toLowerCase() === "set-cookie") {
       target.append(name, value);
     } else if (stubOverridesNonCookie || !target.has(name)) {
@@ -318,12 +329,50 @@ function mergeReqCtxStub(
     }
   }
   reqCtx.res.headers.forEach((value, name) => {
+    // Never propagate the reserved external-redirect marker (see mergeStubHeaders).
+    if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
     if (name !== "set-cookie" && !target.has(name)) {
       target.set(name, value);
     }
   });
 }
 
+// Clone `base` with stub headers merged into a fresh Headers (the clone keeps
+// the body mutable for post-next() modifications). Set-Cookie is always
+// appended; other headers obey stubOverridesNonCookie (see mergeStubHeaders).
+// mergeReqCtx folds in RequestContext stub cookies/headers; the intercept
+// short-circuit path passes false (its reqCtx headers are not merged here),
+// which is the one deliberate divergence between the call sites.
+function mergeResponse(
+  base: Response,
+  stub: Headers,
+  opts: { stubOverridesNonCookie: boolean; mergeReqCtx: boolean },
+): Response {
+  const mergedHeaders = new Headers(base.headers);
+  // The reserved external-redirect marker is never a trust signal and must never
+  // reach the browser. The guard strips it on 3xx redirects; strip it here too so
+  // a forged value cannot ride a non-3xx middleware response (which the 3xx-only
+  // guard would not touch) to the client. The opt-in is the out-of-band brand.
+  mergedHeaders.delete(EXTERNAL_REDIRECT_MARKER);
+  mergeStubHeaders(mergedHeaders, stub, opts.stubOverridesNonCookie);
+  if (opts.mergeReqCtx) {
+    mergeReqCtxStub(mergedHeaders, _getRequestContext());
+  }
+  const merged = new Response(base.body, {
+    status: base.status,
+    statusText: base.statusText,
+    headers: mergedHeaders,
+  });
+  // Transfer the out-of-band external-redirect brand across this rebuild: a
+  // middleware short-circuit `return redirect(url, { external: true })` reaches
+  // the open-redirect guard only after this merge, and the brand lives on the
+  // Response object, not in its headers.
+  if (isExternalRedirect(base)) {
+    markExternalRedirect(merged);
+  }
+  return merged;
+}
+
 /**
  * Execute middleware chain
  *
@@ -362,20 +411,16 @@ export async function executeMiddleware<TEnv>(
       // End of chain - call actual RSC handler
       const response = await finalHandler();
 
-      const mergedHeaders = new Headers(response.headers);
-      mergeStubHeaders(mergedHeaders, stubResponse.headers, true);
-      mergeReqCtxStub(mergedHeaders, _getRequestContext());
-
       if (isWebSocketUpgradeResponse(response)) {
         responseHolder.response = response;
         return response;
       }
 
-      // Clone response with merged headers (mutable for post-next() modifications)
-      responseHolder.response = new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: mergedHeaders,
+      // Chain ran to completion: stub headers overwrite (stubOverridesNonCookie)
+      // and reqCtx stub headers are merged in.
+      responseHolder.response = mergeResponse(response, stubResponse.headers, {
+        stubOverridesNonCookie: true,
+        mergeReqCtx: true,
       });
 
       return responseHolder.response;
@@ -474,13 +519,11 @@ export async function executeMiddleware<TEnv>(
         responseHolder.response = result;
         return result;
       }
-      const mergedHeaders = new Headers(result.headers);
-      mergeStubHeaders(mergedHeaders, stubResponse.headers, false);
-      mergeReqCtxStub(mergedHeaders, _getRequestContext());
-      const merged = new Response(result.body, {
-        status: result.status,
-        statusText: result.statusText,
-        headers: mergedHeaders,
+      // Explicit short-circuit: the returned Response's own headers win
+      // (stubOverridesNonCookie=false); reqCtx stub headers still merge in.
+      const merged = mergeResponse(result, stubResponse.headers, {
+        stubOverridesNonCookie: false,
+        mergeReqCtx: true,
       });
       responseHolder.response = merged;
       return merged;
@@ -635,15 +678,13 @@ export async function executeInterceptMiddleware<TEnv>(
     });
 
     if (hasStubHeaders) {
-      // Clone and merge headers from stub into early response.
-      // Only fill in missing headers — the returned Response's explicit
-      // headers take precedence, matching executeMiddleware behavior.
-      const mergedHeaders = new Headers(response.headers);
-      mergeStubHeaders(mergedHeaders, stubResponse.headers, false);
-      return new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: mergedHeaders,
+      // Only fill in missing headers — the returned Response's explicit headers
+      // take precedence (stubOverridesNonCookie=false), matching executeMiddleware.
+      // mergeReqCtx=false: the intercept path deliberately does NOT merge reqCtx
+      // stub headers here (pinned by intercept-middleware-headers.test.ts).
+      return mergeResponse(response, stubResponse.headers, {
+        stubOverridesNonCookie: false,
+        mergeReqCtx: false,
       });
     }
     return response;
@@ -684,7 +725,6 @@ export async function executeLoaderMiddleware<TEnv>(
       regex: null,
       paramNames: [],
       handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params,
   }));