@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

package/src/router/middleware.ts

@@ -1,183 +1,53 @@
 /// <reference types="vite/types/importMeta.d.ts" />
-/**
- * Middleware Execution
- *
- * True middleware that wraps the entire RSC handler.
- * - `await next()` returns actual Response
- * - Can modify response headers
- * - Can catch errors from RSC rendering
- * - Forgiving API: if middleware doesn't return, original response is used
- */
 
-import type { RouterEnv } from "../types.js";
-
-/**
- * Helper type to extract Variables from RouterEnv
- * Uses 0 extends 1 & TEnv to detect `any` type and fall back to Record<string, unknown>
- */
-type ExtractVariables<TEnv> = 0 extends 1 & TEnv
-  ? Record<string, unknown>  // TEnv is any
-  : TEnv extends RouterEnv<unknown, infer V>
-    ? V
-    : Record<string, unknown>;
-
-/**
- * Get variable function type
- */
-type GetVariableFn<TEnv> = <K extends keyof ExtractVariables<TEnv>>(
-  key: K
-) => ExtractVariables<TEnv>[K];
-
-/**
- * Set variable function type
- */
-type SetVariableFn<TEnv> = <K extends keyof ExtractVariables<TEnv>>(
-  key: K,
-  value: ExtractVariables<TEnv>[K]
-) => void;
-
-/**
- * Cookie options for setting cookies
- */
-export interface CookieOptions {
-  domain?: string;
-  path?: string;
-  maxAge?: number;
-  expires?: Date;
-  httpOnly?: boolean;
-  secure?: boolean;
-  sameSite?: "strict" | "lax" | "none";
-}
-
-/**
- * Context passed to middleware
- *
- * @template TEnv - Environment type (bindings, variables) - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware, Record<string, string> for global middleware)
- */
-export interface MiddlewareContext<
-  TEnv = any,
-  TParams = Record<string, string>,
-> {
-  /** Original request */
-  request: Request;
-
-  /** Parsed URL */
-  url: URL;
-
-  /** URL pathname */
-  pathname: string;
-
-  /** URL search params */
-  searchParams: URLSearchParams;
-
-  /** Platform bindings (Cloudflare, etc.) */
-  env: TEnv extends RouterEnv<infer B, unknown> ? B : {};
-
-  /** URL params extracted from route/middleware pattern */
-  params: TParams;
-
-  /**
-   * Response object - available immediately via stub, real response after `await next()`
-   *
-   * Headers set before `next()` are merged into the final response.
-   * Can be used to modify headers directly like Hono's `c.res`.
-   *
-   * @example
-   * ```typescript
-   * middleware(async (ctx, next) => {
-   *   // Set headers BEFORE next() - will be merged into final response
-   *   ctx.res.headers.set('X-Request-Id', generateId());
-   *
-   *   await next();
-   *
-   *   // Set headers AFTER next() - applied directly
-   *   ctx.res.headers.set('X-Custom', 'value');
-   *   // No return needed!
-   * });
-   * ```
-   */
-  res: Response;
-
-  /** Get a cookie value */
-  cookie(name: string): string | undefined;
-
-  /** Get all cookies as object */
-  cookies(): Record<string, string>;
-
-  /** Set a cookie on the response */
-  setCookie(name: string, value: string, options?: CookieOptions): void;
-
-  /** Delete a cookie */
-  deleteCookie(
-    name: string,
-    options?: Pick<CookieOptions, "domain" | "path">
-  ): void;
-
-  /** Get a context variable (shared with route handlers) */
-  get: GetVariableFn<TEnv>;
-
-  /** Set a context variable (shared with route handlers) */
-  set: SetVariableFn<TEnv>;
-
-  /**
-   * Set a response header - can be called before or after `next()`
-   *
-   * When called before `next()`, headers are queued and merged into the final response.
-   * When called after `next()`, headers are set directly on the response.
-   * Shorthand for `ctx.res.headers.set()`.
-   */
-  header(name: string, value: string): void;
-}
-
-/**
- * Middleware function signature
- *
- * @template TEnv - Environment type - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware)
- *
- * When using middleware with global augmentation (RSCRouter.Env), explicitly
- * annotate your middleware functions, or the types will be inferred from context:
- *
- * @example
- * ```typescript
- * // With explicit annotation (recommended for reusable middleware)
- * const authMiddleware: MiddlewareFn<AppEnv> = async (ctx, next) => {...}
- *
- * // Types inferred from router.use() call
- * router.use((ctx, next) => {...}) // ctx is typed from router's TEnv
- * ```
- */
-export type MiddlewareFn<TEnv = any, TParams = Record<string, string>> = (
-  ctx: MiddlewareContext<TEnv, TParams>,
-  next: () => Promise<Response>
-) => Response | void | Promise<Response | void>;
-
-/**
- * Stored middleware entry with pattern matching info
- * @internal - uses any for internal flexibility
- */
-export interface MiddlewareEntry<TEnv = any> {
-  /** Original pattern string */
-  pattern: string | null;
-
-  /** Compiled regex for matching */
-  regex: RegExp | null;
-
-  /** Param names extracted from pattern */
-  paramNames: string[];
+import { contextGet, contextSet } from "../context-var.js";
+import { safeDecodeURIComponent } from "./url-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
+import type {
+  CollectedMiddleware,
+  MiddlewareCollectableEntry,
+  MiddlewareContext,
+  MiddlewareEntry,
+  MiddlewareFn,
+  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 { observePhase, PHASES } from "./instrument.js";
+import { stripInternalParams } from "./handler-context.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
+
+// Re-export types consumed through this module's path.
+export type {
+  CookieOptions,
+  MiddlewareContext,
+  MiddlewareEntry,
+  MiddlewareFn,
+} from "./middleware-types.js";
+
+const MIDDLEWARE_METRIC_DEPTH = 1;
+const POST_METRIC_MIN_DURATION_MS = 0.01;
+
+function getMiddlewareMetricLabel<TEnv>(
+  entry: MiddlewareEntry<TEnv>,
+  ordinal: number,
+): string {
+  const handlerName = entry.handler.name?.trim();
+  const scope = entry.pattern ?? "*";
 
-  /** The middleware function */
-  handler: MiddlewareFn<TEnv>;
+  if (handlerName) {
+    return `middleware:${handlerName}@${scope}`;
+  }
 
-  /** Mount prefix this middleware is scoped to (null = global) */
-  mountPrefix: string | null;
+  return `middleware:${scope}#${ordinal + 1}`;
 }
 
-/**
- * Parse a route pattern into regex and param names
- * Supports: *, /path, /path/*, /path/:param, /path/:param/*
- */
 export function parsePattern(pattern: string): {
   regex: RegExp;
   paramNames: string[];
@@ -226,168 +96,168 @@ function escapeRegex(str: string): string {
 }
 
 /**
- * Extract params from a pathname using a pattern's regex and param names
+ * Extract params from a pathname using a pattern's regex and param names.
+ *
+ * Values are URL-decoded so apps see the raw string (e.g. "ivo@example.com")
+ * instead of the percent-encoded form ("ivo%40example.com"). This matches the
+ * contract assumed by ctx.reverse (which re-encodes) and aligns with
+ * Express/React Router/Fastify/Koa.
  */
 export function extractParams(
   pathname: string,
   regex: RegExp,
-  paramNames: string[]
+  paramNames: string[],
 ): Record<string, string> {
   const match = pathname.match(regex);
   if (!match) return {};
 
   const params: Record<string, string> = {};
   for (let i = 0; i < paramNames.length; i++) {
-    params[paramNames[i]] = match[i + 1] || "";
+    params[paramNames[i]] = safeDecodeURIComponent(match[i + 1] || "");
   }
   return params;
 }
 
-/**
- * Parse cookies from Cookie header
- */
-export function parseCookies(
-  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) {
-      cookies[name] = decodeURIComponent(rest.join("="));
-    }
-  }
-
-  return cookies;
-}
-
-/**
- * Serialize a cookie for Set-Cookie header
- */
-export function serializeCookie(
-  name: string,
-  value: string,
-  options: CookieOptions = {}
-): string {
-  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
-
-  if (options.domain) cookie += `; Domain=${options.domain}`;
-  if (options.path) cookie += `; Path=${options.path}`;
-  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
-  if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
-  if (options.httpOnly) cookie += "; HttpOnly";
-  if (options.secure) cookie += "; Secure";
-  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
-
-  return cookie;
-}
-
-/**
- * Mutable response holder - allows ctx.res to be updated after next() is called
- */
-export interface ResponseHolder {
-  response: Response | null;
-}
-
 /**
  * Create middleware context
  *
  * Note: The implementation uses runtime values while the interface provides
  * compile-time type safety. The env/get/set types are resolved at call sites
- * via conditional types based on TEnv extending RouterEnv.
+ * via conditional types based on TEnv from createRouter<TBindings>().
  */
 export function createMiddlewareContext<TEnv>(
   request: Request,
   env: TEnv,
   params: Record<string, string>,
   variables: Record<string, unknown>,
-  responseHolder: ResponseHolder
+  responseHolder: ResponseHolder,
+  reverse?: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string,
 ): MiddlewareContext<TEnv> {
-  const url = new URL(request.url);
-  const cookieHeader = request.headers.get("Cookie");
-  let parsedCookies: Record<string, string> | null = null;
-
+  const url = stripInternalParams(new URL(request.url));
+
+  // Track the initial response to detect pre/post-next() phase.
+  // Before next(): responseHolder.response === initialResponse (the stub).
+  // After next(): responseHolder.response is the real downstream response.
+  const initialResponse = responseHolder.response;
+  const isPreNext = () => responseHolder.response === initialResponse;
+
+  // Delegation strategy for RequestContext (reqCtx):
+  // - res getter: before next() returns shared reqCtx stub; after next() returns
+  //   the real downstream response.
+  // - header(): before next() delegates to reqCtx; after next() writes to the
+  //   real downstream response.
+  // Cookie operations are handled by the standalone cookies() function which
+  // delegates to the shared RequestContext internally.
   // The runtime implementation - types are enforced at call sites via MiddlewareContext<TEnv>
+  // Internal helper: resolve the current response (stub before next(), real after).
+  // Not exposed on the public MiddlewareContext type — use ctx.headers instead.
+  const getResponse = (): Response => {
+    if (isPreNext()) {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) return reqCtx.res;
+    }
+    if (!responseHolder.response) {
+      throw new Error(
+        "Response is not available - responseHolder was not initialized",
+      );
+    }
+    return responseHolder.response;
+  };
+
+  // Capture reqCtx once: the request-scoped platform fields
+  // (originalUrl, executionContext, waitUntil) are immutable per request,
+  // so snapshotting beats re-reading ALS on every access. The lazy getters
+  // below (routeName, theme, setTheme) stay lazy because those can change
+  // during `await next()`.
+  const reqCtx = _getRequestContext();
   return {
     request,
     url,
+    originalUrl: reqCtx?.originalUrl ?? new URL(request.url),
     pathname: url.pathname,
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
     params,
-
-    // res getter - returns the stub or real response (always available)
-    get res(): Response {
-      if (!responseHolder.response) {
-        throw new Error(
-          "ctx.res is not available - responseHolder was not initialized"
-        );
-      }
-      return responseHolder.response;
+    executionContext: reqCtx?.executionContext,
+    waitUntil: reqCtx ? reqCtx.waitUntil.bind(reqCtx) : fireAndForgetWaitUntil,
+    // Getter: re-derives from request context on each access so that global
+    // middleware sees the matched route name after await next().
+    get routeName(): MiddlewareContext<TEnv>["routeName"] {
+      const reqCtx = _getRequestContext();
+      const raw = reqCtx?._routeName;
+      return (
+        raw && !isAutoGeneratedRouteName(raw) ? raw : undefined
+      ) as MiddlewareContext<TEnv>["routeName"];
     },
 
-    // res setter - allows middleware to replace the response
-    set res(response: Response) {
-      responseHolder.response = response;
+    get headers(): Headers {
+      return getResponse().headers;
     },
 
-    cookie(name: string): string | undefined {
-      if (!parsedCookies) {
-        parsedCookies = parseCookies(cookieHeader);
-      }
-      return parsedCookies[name];
-    },
+    get: ((keyOrVar: any) =>
+      contextGet(variables, keyOrVar)) as MiddlewareContext<TEnv>["get"],
 
-    cookies(): Record<string, string> {
-      if (!parsedCookies) {
-        parsedCookies = parseCookies(cookieHeader);
+    set: ((keyOrVar: any, value: unknown, options?: any) => {
+      contextSet(variables, keyOrVar, value, options);
+    }) as MiddlewareContext<TEnv>["set"],
+    header(name: string, value: string): void {
+      // Before next(): delegate to shared RequestContext stub
+      if (isPreNext()) {
+        const reqCtx = _getRequestContext();
+        if (reqCtx) {
+          reqCtx.header(name, value);
+          return;
+        }
       }
-      return { ...parsedCookies };
-    },
-
-    setCookie(name: string, value: string, options?: CookieOptions): void {
+      // After next() or standalone: write to current response
       if (!responseHolder.response) {
         throw new Error(
-          "ctx.setCookie() is not available - responseHolder was not initialized"
+          "ctx.header() is not available - responseHolder was not initialized",
         );
       }
-      responseHolder.response.headers.append(
-        "Set-Cookie",
-        serializeCookie(name, value, options)
-      );
+      responseHolder.response.headers.set(name, value);
     },
 
-    deleteCookie(
-      name: string,
-      options?: Pick<CookieOptions, "domain" | "path">
-    ): void {
-      if (!responseHolder.response) {
+    get theme(): MiddlewareContext<TEnv>["theme"] {
+      return _getRequestContext()?.theme;
+    },
+
+    get setTheme(): MiddlewareContext<TEnv>["setTheme"] {
+      return _getRequestContext()?.setTheme;
+    },
+
+    setLocationState(entries) {
+      const reqCtx = _getRequestContext();
+      if (!reqCtx) {
         throw new Error(
-          "ctx.deleteCookie() is not available - responseHolder was not initialized"
+          "setLocationState() is not available outside a request context",
         );
       }
-      responseHolder.response.headers.append(
-        "Set-Cookie",
-        serializeCookie(name, "", { ...options, maxAge: 0 })
-      );
+      reqCtx.setLocationState(entries);
     },
 
-    get: ((key: string) => variables[key]) as MiddlewareContext<TEnv>["get"],
-
-    set: ((key: string, value: unknown) => {
-      variables[key] = value;
-    }) as MiddlewareContext<TEnv>["set"],
-
-    header(name: string, value: string): void {
-      if (!responseHolder.response) {
+    reverse:
+      reverse ??
+      ((
+        name: string,
+        _params?: Record<string, string>,
+        _search?: Record<string, unknown>,
+      ) => {
         throw new Error(
-          "ctx.header() is not available - responseHolder was not initialized"
+          `ctx.reverse(${JSON.stringify(name)}) is not available: no route map is bound to this middleware context.`,
         );
+      }),
+
+    debugPerformance(): void {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) {
+        reqCtx._debugPerformance = true;
+        reqCtx._metricsStore ??= createMetricsStore(true);
       }
-      responseHolder.response.headers.set(name, value);
     },
   };
 }
@@ -398,7 +268,7 @@ export function createMiddlewareContext<TEnv>(
  */
 export function matchMiddleware<TEnv>(
   pathname: string,
-  entries: MiddlewareEntry<TEnv>[]
+  entries: MiddlewareEntry<TEnv>[],
 ): Array<{ entry: MiddlewareEntry<TEnv>; params: Record<string, string> }> {
   const matches: Array<{
     entry: MiddlewareEntry<TEnv>;
@@ -422,15 +292,97 @@ export function matchMiddleware<TEnv>(
   return matches;
 }
 
+// Set-Cookie is appended; for other headers stubOverridesNonCookie=true
+// overwrites (chain ran to completion), false fills only missing slots (an
+// explicit short-circuit Response's own headers win).
+function mergeStubHeaders(
+  target: Headers,
+  stub: Headers,
+  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)) {
+      target.set(name, value);
+    }
+  });
+}
+
+// Set-Cookie is deduped so a nested inner executeMiddleware that already merged
+// the same reqCtx cookies does not duplicate them; other headers fill if missing.
+function mergeReqCtxStub(
+  target: Headers,
+  reqCtx: ReturnType<typeof _getRequestContext>,
+): void {
+  if (!reqCtx) return;
+  const stubCookies = reqCtx.res.headers.getSetCookie();
+  if (stubCookies.length > 0) {
+    const existing = new Set(target.getSetCookie());
+    for (const cookie of stubCookies) {
+      if (!existing.has(cookie)) {
+        target.append("set-cookie", cookie);
+      }
+    }
+  }
+  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
  *
  * Features:
  * - `await next()` returns actual Response
- * - `ctx.res` available after `await next()` (like Hono's `c.res`)
- * - `ctx.header()` shorthand for setting headers
- * - Forgiving: if middleware doesn't return, uses `ctx.res`
- * - Short-circuit: return Response to stop chain
+ * - `ctx.headers` available before and after `await next()`
+ * - `ctx.header()` shorthand for setting a single header
+ * - Forgiving: if middleware doesn't return, uses the downstream response
+ * - Short-circuit: return OR throw a Response to stop chain
  * - Error catching: try/catch around `next()` works
  */
 export async function executeMiddleware<TEnv>(
@@ -441,7 +393,12 @@ export async function executeMiddleware<TEnv>(
   request: Request,
   env: TEnv,
   variables: Record<string, any>,
-  finalHandler: () => Promise<Response>
+  finalHandler: () => Promise<Response>,
+  reverse?: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string,
 ): Promise<Response> {
   let index = 0;
 
@@ -455,50 +412,130 @@ export async function executeMiddleware<TEnv>(
       // End of chain - call actual RSC handler
       const response = await finalHandler();
 
-      // Merge headers set on stub into the real response
-      // Use append for Set-Cookie to preserve multiple cookies
-      const mergedHeaders = new Headers(response.headers);
-      stubResponse.headers.forEach((value, name) => {
-        if (name.toLowerCase() === "set-cookie") {
-          mergedHeaders.append(name, value);
-        } else {
-          mergedHeaders.set(name, value);
-        }
-      });
+      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;
     }
 
+    const middlewareOrdinal = index;
     const { entry, params } = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
       env,
       params,
       variables,
-      responseHolder
+      responseHolder,
+      reverse,
     );
+    const metricStart = performance.now();
+    const metricLabel = getMiddlewareMetricLabel(entry, middlewareOrdinal);
+    let middlewareFinished = false;
+    const finishMiddleware = () => {
+      if (!middlewareFinished) {
+        middlewareFinished = true;
+        appendMetric(
+          _getRequestContext()?._metricsStore,
+          `${metricLabel}:pre`,
+          metricStart,
+          performance.now() - metricStart,
+          MIDDLEWARE_METRIC_DEPTH,
+        );
+      }
+    };
 
-    // Track if next() was called and capture its Promise
-    // This handles the case where middleware calls next() synchronously without await
+    // Track if next() was called and capture its Promise.
+    // Guard against double-calling: a second call would re-enter the
+    // downstream chain and overwrite responseHolder.response.
     let nextPromise: Promise<Response> | null = null;
+    let nextResolvedAt: number | undefined;
     const wrappedNext = (): Promise<Response> => {
-      nextPromise = next();
+      if (nextPromise) {
+        throw new Error(
+          `[@rangojs/router] Middleware called next() more than once.`,
+        );
+      }
+      finishMiddleware();
+      const downstream = next();
+      nextPromise = downstream.then(
+        (res) => {
+          nextResolvedAt = performance.now();
+          return res;
+        },
+        (err) => {
+          nextResolvedAt = performance.now();
+          throw err;
+        },
+      );
       return nextPromise;
     };
 
-    const result = await entry.handler(ctx, wrappedNext);
+    // Wrap the middleware (including its downstream next() chain) in its span
+    // via the unified phase API. metric:false — the middleware's perf metric is
+    // its exclusive pre/post own-time, recorded directly above and below, finer
+    // than a single wrap. Spans nest by async context, so this onions
+    // middleware-over-middleware and the core handler underneath. Pass-through
+    // when neither surface is active.
+    let result: Response | void;
+    try {
+      result = await observePhase(PHASES.middleware(metricLabel), () =>
+        entry.handler(ctx, wrappedNext),
+      );
+    } catch (error) {
+      // Thrown Response is short-circuit control flow, not an error.
+      // Fall through to the `if (result instanceof Response)` branch below
+      // so stub headers and request-context cookies merge as they do for
+      // an explicit `return new Response(...)`. Real errors propagate.
+      if (error instanceof Response) {
+        result = error;
+      } else {
+        finishMiddleware();
+        throw error;
+      }
+    }
+    finishMiddleware();
+
+    // Record post-next() processing time when middleware did work after
+    // the downstream chain resolved (e.g. adding headers, logging).
+    if (nextResolvedAt !== undefined) {
+      const postDur = performance.now() - nextResolvedAt;
+      if (postDur > POST_METRIC_MIN_DURATION_MS) {
+        appendMetric(
+          _getRequestContext()?._metricsStore,
+          `${metricLabel}:post`,
+          nextResolvedAt,
+          postDur,
+          MIDDLEWARE_METRIC_DEPTH,
+        );
+      }
+    }
 
-    // Explicit return takes precedence
+    // Explicit return takes precedence (middleware short-circuit).
+    // Merge stub headers (from ctx.header before this point) and
+    // RequestContext stub headers (from cookies().set()) into the
+    // returned Response so they are not lost.
     if (result instanceof Response) {
-      responseHolder.response = result;
-      return result;
+      if (isWebSocketUpgradeResponse(result)) {
+        responseHolder.response = result;
+        return result;
+      }
+      // 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;
     }
 
     // Warn about unexpected return values (non-Response, non-undefined)
@@ -507,7 +544,7 @@ export async function executeMiddleware<TEnv>(
       const fnName = entry.handler.name || "(anonymous)";
       console.warn(
         `[Middleware] "${fnName}" returned ${typeof result} instead of Response or undefined. ` +
-          `This return value will be ignored. Did you mean to return a Response?`
+          `This return value will be ignored. Did you mean to return a Response?`,
       );
     }
 
@@ -524,7 +561,7 @@ export async function executeMiddleware<TEnv>(
       `Middleware must call next() or return a Response. ` +
         `Function: ${fnName}, Pattern: ${entry.pattern ?? "(all)"}
         Source: ${import.meta.env.DEV ? entry.handler.toString().slice(0, 200) : "(source hidden in production)"}`,
-      { cause: { url: request.url, fn: entry.handler } }
+      { cause: { url: request.url, fn: entry.handler } },
     );
   };
 
@@ -536,64 +573,19 @@ export async function executeMiddleware<TEnv>(
     throw new Error("No response generated by middleware chain");
   }
 
-  return finalResponse;
-}
-
-/**
- * Execute middleware for server actions
- *
- * Server actions can't return Response directly, but headers/cookies set
- * on ctx.res (from getRequestContext().res) will be merged into the final response.
- *
- * - Runs middleware for auth checks, variable setting, headers, cookies
- * - Throws if middleware returns Response (can't short-circuit server action)
- */
-export async function executeServerActionMiddleware<TEnv>(
-  middlewares: MiddlewareFn<TEnv>[],
-  request: Request,
-  env: TEnv,
-  params: Record<string, string>,
-  variables: Record<string, any>,
-  stubResponse: Response
-): Promise<void> {
-  if (middlewares.length === 0) {
-    return;
+  // Final re-merge: capture any RequestContext stub headers added after the
+  // last merge point (e.g. cookies().set() called after await next()).
+  // The reqCtx stub may have already been partially merged during finalHandler
+  // or early-return paths; only append *new* Set-Cookie entries to avoid dupes.
+  //
+  // Skip for upgrade responses: upgrade headers are semantically immutable and
+  // set-cookie on an upgrade is not meaningful.
+  const reqCtx = _getRequestContext();
+  if (reqCtx && !isWebSocketUpgradeResponse(finalResponse)) {
+    mergeReqCtxStub(finalResponse.headers, reqCtx);
   }
 
-  let index = 0;
-  const responseHolder: ResponseHolder = { response: stubResponse };
-
-  const next = async (): Promise<Response> => {
-    if (index >= middlewares.length) {
-      return stubResponse;
-    }
-
-    const middleware = middlewares[index++];
-    const ctx = createMiddlewareContext(
-      request,
-      env,
-      params,
-      variables,
-      responseHolder
-    );
-
-    const result = await middleware(ctx, next);
-
-    // If middleware returned a Response, throw an error
-    // Server actions can't short-circuit with a Response
-    if (result instanceof Response) {
-      throw new Error(
-        `Loader middleware returned a Response (status: ${result.status}). ` +
-          `Server actions cannot return Response. ` +
-          `Use GET-based loader fetching for redirects, or throw an error instead.`
-      );
-    }
-
-    return stubResponse;
-  };
-
-  await next();
-  // Headers/cookies set on stubResponse will be merged by the caller
+  return finalResponse;
 }
 
 /**
@@ -601,7 +593,7 @@ export async function executeServerActionMiddleware<TEnv>(
  *
  * Intercepts use a shared stubResponse from the request context. This function:
  * - Runs middleware in sequence with a simple next() chain
- * - Returns Response if any middleware short-circuits (returns Response or redirects BEFORE next())
+ * - Returns Response if any middleware short-circuits (returns OR throws a Response, or redirects, BEFORE next())
  * - Returns null if all middleware calls next() - headers set after next() remain on stubResponse
  *
  * @param middlewares - Array of middleware functions
@@ -617,7 +609,12 @@ export async function executeInterceptMiddleware<TEnv>(
   env: TEnv,
   params: Record<string, string>,
   variables: Record<string, any>,
-  stubResponse: Response
+  stubResponse: Response,
+  reverse?: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string,
 ): Promise<Response | null> {
   if (middlewares.length === 0) {
     return null;
@@ -634,28 +631,57 @@ export async function executeInterceptMiddleware<TEnv>(
       return stubResponse;
     }
 
+    const ordinal = index;
     const middleware = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
       env,
       params,
       variables,
-      responseHolder
+      responseHolder,
+      reverse,
     );
 
-    const result = await middleware(ctx, next);
+    let nextCalled = false;
+    const guardedNext = (): Promise<Response> => {
+      if (nextCalled) {
+        throw new Error(
+          `[@rangojs/router] Intercept middleware called next() more than once.`,
+        );
+      }
+      nextCalled = true;
+      return next();
+    };
+
+    // Span-wrap each intercept middleware as rango.middleware (metric:false —
+    // intercept runs inside the render phase already metered by render:total, so
+    // it contributes a span but no separate perf metric). Bare MiddlewareFns
+    // have no pattern, so the label is scoped to "*" like a pattern-less entry.
+    const label = getMiddlewareMetricLabel(
+      { handler: middleware, pattern: null } as MiddlewareEntry<TEnv>,
+      ordinal,
+    );
+
+    let result: Response | void;
+    try {
+      result = await observePhase(PHASES.middleware(label), () =>
+        middleware(ctx, guardedNext),
+      );
+    } catch (error) {
+      // Thrown Response is short-circuit control flow, parity with the
+      // explicit-return path below. Real errors propagate.
+      if (error instanceof Response) {
+        result = error;
+      } else {
+        throw error;
+      }
+    }
 
     if (result instanceof Response) {
       earlyResponse = result;
       return result;
     }
 
-    // Check if middleware replaced ctx.res with a different response
-    if (responseHolder.response && responseHolder.response !== stubResponse) {
-      earlyResponse = responseHolder.response;
-      return earlyResponse;
-    }
-
     return stubResponse;
   };
 
@@ -673,19 +699,13 @@ export async function executeInterceptMiddleware<TEnv>(
     });
 
     if (hasStubHeaders) {
-      // Clone and merge headers from stub into early response
-      const mergedHeaders = new Headers(response.headers);
-      stubResponse.headers.forEach((value, name) => {
-        if (name.toLowerCase() === "set-cookie") {
-          mergedHeaders.append(name, value);
-        } else {
-          mergedHeaders.set(name, value);
-        }
-      });
-      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;
@@ -708,7 +728,12 @@ export async function executeLoaderMiddleware<TEnv>(
   env: TEnv,
   params: Record<string, string>,
   variables: Record<string, any>,
-  finalHandler: () => Promise<Response>
+  finalHandler: () => Promise<Response>,
+  reverse?: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string,
 ): Promise<Response> {
   if (middlewares.length === 0) {
     return finalHandler();
@@ -721,7 +746,6 @@ export async function executeLoaderMiddleware<TEnv>(
       regex: null,
       paramNames: [],
       handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params,
   }));
@@ -731,27 +755,11 @@ export async function executeLoaderMiddleware<TEnv>(
     request,
     env,
     variables,
-    finalHandler
+    finalHandler,
+    reverse,
   );
 }
 
-/**
- * Entry type for middleware collection
- * Matches the shape of EntryData used in router.ts
- */
-export interface MiddlewareCollectableEntry {
-  middleware?: MiddlewareFn<any, any>[];
-  layout?: MiddlewareCollectableEntry[];
-}
-
-/**
- * Collected route middleware with params
- */
-export interface CollectedMiddleware {
-  handler: MiddlewareFn<any, any>;
-  params: Record<string, string>;
-}
-
 /**
  * Collect route-level middleware from an entry tree
  *
@@ -764,7 +772,7 @@ export interface CollectedMiddleware {
  */
 export function collectRouteMiddleware(
   entries: Iterable<MiddlewareCollectableEntry>,
-  params: Record<string, string>
+  params: Record<string, string>,
 ): CollectedMiddleware[] {
   const result: CollectedMiddleware[] = [];