@rangojs/router 0.0.0-experimental.23 → 0.0.0-experimental.24535dcb

package/src/router/middleware.ts

@@ -1,15 +1,10 @@
 /// <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 { contextGet, contextSet } from "../context-var.js";
+import { escapeRegExp } from "../regex-escape.js";
+import { parsePattern as parseRoutePattern } from "./pattern-matching.js";
+import { safeDecodeURIComponent } from "./url-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import type {
   CollectedMiddleware,
   MiddlewareCollectableEntry,
@@ -19,46 +14,79 @@ 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 { observePhase, PHASES } from "./instrument.js";
+import { stripInternalParams } from "./handler-context.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
-// Re-export types and cookie utilities for backward compatibility
+// Re-export types consumed through this module's path.
 export type {
   CookieOptions,
-  CollectedMiddleware,
-  MiddlewareCollectableEntry,
   MiddlewareContext,
   MiddlewareEntry,
   MiddlewareFn,
-  ResponseHolder,
 } from "./middleware-types.js";
-export { parseCookies, serializeCookie } from "./middleware-cookies.js";
-
-// W5: Deduplicate by function reference so each distinct middleware warns once,
-// regardless of whether it is named or anonymous.
-let warnedRedirectMiddleware = new WeakSet<Function>();
-
-function warnCtxSetBeforeRedirect(handler: Function): void {
-  if (warnedRedirectMiddleware.has(handler)) return;
-  warnedRedirectMiddleware.add(handler);
-  const label = handler.name || "(anonymous)";
-  console.warn(
-    `[rango] Route middleware "${label}" called ctx.set() then returned a ` +
-      `redirect. Context variables are per-request and won't be available ` +
-      `on the redirect target. Use cookies to persist state across ` +
-      `redirects, or move ctx.set() to the target route's middleware.`,
-  );
-}
 
-/** Reset W5 deduplication state (for tests only). */
-export function _resetW5Warnings(): void {
-  warnedRedirectMiddleware = new WeakSet();
+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 ?? "*";
+
+  if (handlerName) {
+    return `middleware:${handlerName}@${scope}`;
+  }
+
+  return `middleware:${scope}#${ordinal + 1}`;
 }
 
 /**
- * Parse a route pattern into regex and param names
- * Supports: *, /path, /path/*, /path/:param, /path/:param/*
+ * Compile a middleware scope pattern to a regex + param names.
+ *
+ * Middleware scopes reuse the route pattern parser (`parsePattern` from
+ * pattern-matching.ts), so they support the same param forms as routes —
+ * optional (`:x?`), constrained (`:x(en|gb)`), and suffix (`:x.html`) — in
+ * addition to the trailing-`*` wildcard middleware relies on. Before this
+ * unification the middleware-side parser handled only static, bare `:param`,
+ * and trailing `*`, so e.g. `router.use("/:locale(en|gb)/*", mw)` silently
+ * named the param "locale(en|gb)" and never enforced the constraint.
+ *
+ * Middleware matching semantics deliberately differ from route matching, so we
+ * emit the regex here rather than route through `compilePattern`:
+ * - `*` alone matches every path (`/^.*$/`).
+ * - A trailing `*` segment is an OPTIONAL subtree match (`(?:/.*)?`): `/admin/*`
+ *   matches `/admin`, `/admin/`, and `/admin/users`. It contributes no param
+ *   name (unlike route wildcards, which capture `*`).
+ * - A NON-trailing `*` is also OPTIONAL (`(?:/.*)?`), matching zero-or-more
+ *   intermediate segments: `/a/<star>/b` matches both `/a/b` and `/a/x/b`. This
+ *   mirrors the pre-unification parser, which compiled every `*` part as
+ *   optional regardless of position.
+ * - A pattern without a trailing `*` tolerates a trailing slash (`/?$`).
+ * - Constraints are baked into the regex as an alternation so `matchMiddleware`
+ *   (a bare `regex.test`) enforces them without extra validation. Constraint
+ *   values are matched against the raw (still URL-encoded) path segment, which
+ *   matches the pre-unification middleware behavior (it never decoded for
+ *   matching); the constraint string is regex-escaped so values like `en.gb`
+ *   are treated literally.
+ *
+ * The route segment parser only recognizes `/`-prefixed segments, but the
+ * pre-unification middleware parser split on `/` and dropped empty parts, so a
+ * leading slash was irrelevant: `use("admin/*")` and `use("/admin/*")` scoped
+ * identically. Normalize a non-`*` pattern to have a leading slash before
+ * parsing so that behavior is preserved (without it, `parseRoutePattern("admin/*")`
+ * drops the static `admin` and the scope explodes to every path).
  */
-export function parsePattern(pattern: string): {
+export function compileMiddlewarePattern(pattern: string): {
   regex: RegExp;
   paramNames: string[];
 } {
@@ -66,47 +94,63 @@ export function parsePattern(pattern: string): {
     return { regex: /^.*$/, paramNames: [] };
   }
 
+  const normalizedPattern = pattern.startsWith("/") ? pattern : `/${pattern}`;
+  const segments = parseRoutePattern(normalizedPattern);
   const paramNames: string[] = [];
   let regexStr = "^";
-
-  const parts = pattern.split("/").filter(Boolean);
-
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i];
-
-    if (part === "*") {
-      // Wildcard - match rest of path
-      regexStr += "(?:/.*)?";
-    } else if (part.startsWith(":")) {
-      // Param
-      const paramName = part.slice(1);
-      paramNames.push(paramName);
-      regexStr += "/([^/]+)";
+  let hasTrailingWildcard = false;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+
+    if (segment.type === "wildcard") {
+      if (segment.value === "*") {
+        // Bare `*`: optional subtree match, no capture (parity with the original
+        // middleware parser). A trailing `*` matches the subtree; a non-trailing
+        // `*` matches zero-or-more intermediate segments, so `/a/<star>/b` still
+        // matches `/a/b`.
+        regexStr += "(?:/.*)?";
+      } else {
+        // Named catch-all `:name+` / `:name*`: capture the remainder under the
+        // name so a scoping middleware sees `ctx.params.<name>`, and respect the
+        // one-or-more arity (`+` must not match the bare prefix), mirroring the
+        // route matcher instead of collapsing to the bare-`*` subtree.
+        paramNames.push(segment.value);
+        regexStr += segment.oneOrMore ? "/(.+)" : "(?:/(.*))?";
+      }
+      if (i === segments.length - 1) {
+        hasTrailingWildcard = true;
+      }
+    } else if (segment.type === "param") {
+      paramNames.push(segment.value);
+      const suffixPattern = segment.suffix ? escapeRegExp(segment.suffix) : "";
+      const valuePattern = segment.constraint
+        ? `(${segment.constraint.map(escapeRegExp).join("|")})`
+        : "([^/]+)";
+      if (segment.optional) {
+        regexStr += `(?:/${valuePattern}${suffixPattern})?`;
+      } else {
+        regexStr += `/${valuePattern}${suffixPattern}`;
+      }
     } else {
-      // Literal
-      regexStr += "/" + escapeRegex(part);
+      // Static literal
+      regexStr += "/" + escapeRegExp(segment.value);
     }
   }
 
-  // If pattern doesn't end with *, match exact or with trailing segments
-  if (!pattern.endsWith("*")) {
-    regexStr += "/?$";
-  } else {
-    regexStr += "$";
-  }
+  // Without a trailing `*`, match exactly with an optional trailing slash.
+  regexStr += hasTrailingWildcard ? "$" : "/?$";
 
   return { regex: new RegExp(regexStr), paramNames };
 }
 
 /**
- * Escape special regex characters
- */
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * 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,
@@ -118,7 +162,7 @@ export function extractParams(
 
   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;
 }
@@ -142,7 +186,15 @@ export function createMiddlewareContext<TEnv>(
     search?: Record<string, unknown>,
   ) => string,
 ): MiddlewareContext<TEnv> {
-  const url = new URL(request.url);
+  // Reuse the request context's clean URL when available. Each middleware still
+  // gets its OWN URL clone (a middleware may mutate ctx.url / ctx.searchParams),
+  // but cloning the already-clean URL is cheaper than re-parsing + re-stripping
+  // request.url per middleware. Fall back to parsing when no ALS context.
+  const reqCtx = _getRequestContext();
+  const ctxUrl = reqCtx?.url;
+  const url = ctxUrl
+    ? new URL(ctxUrl)
+    : stripInternalParams(new URL(request.url));
 
   // Track the initial response to detect pre/post-next() phase.
   // Before next(): responseHolder.response === initialResponse (the stub).
@@ -158,13 +210,36 @@ export function createMiddlewareContext<TEnv>(
   // 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;
+  };
+
+  // reqCtx captured once above: 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()`.
   return {
     request,
     url,
+    originalUrl: reqCtx?.originalUrl ?? new URL(request.url),
     pathname: url.pathname,
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
     params,
+    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"] {
@@ -175,33 +250,16 @@ export function createMiddlewareContext<TEnv>(
       ) as MiddlewareContext<TEnv>["routeName"];
     },
 
-    get res(): Response {
-      // Before next(): return shared RequestContext stub so headers
-      // set via ctx.header() are visible on ctx.res.
-      if (isPreNext()) {
-        const reqCtx = _getRequestContext();
-        if (reqCtx) return reqCtx.res;
-      }
-      if (!responseHolder.response) {
-        throw new Error(
-          "ctx.res is not available - responseHolder was not initialized",
-        );
-      }
-      return responseHolder.response;
-    },
-    set res(_: Response) {
-      throw new Error(
-        "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
-      );
+    get headers(): Headers {
+      return getResponse().headers;
     },
 
     get: ((keyOrVar: any) =>
       contextGet(variables, keyOrVar)) as MiddlewareContext<TEnv>["get"],
 
-    set: ((keyOrVar: any, value: unknown) => {
-      contextSet(variables, keyOrVar, value);
+    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()) {
@@ -220,11 +278,33 @@ export function createMiddlewareContext<TEnv>(
       responseHolder.response.headers.set(name, value);
     },
 
+    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(
+          "setLocationState() is not available outside a request context",
+        );
+      }
+      reqCtx.setLocationState(entries);
+    },
+
     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.`,
         );
       }),
 
@@ -232,6 +312,10 @@ export function createMiddlewareContext<TEnv>(
       const reqCtx = _getRequestContext();
       if (reqCtx) {
         reqCtx._debugPerformance = true;
+        // Anchor to the true request entry (reqCtx._handlerStart) so phases that
+        // began before this opt-in report non-negative offsets; undefined falls
+        // back to performance.now() in createMetricsStore.
+        reqCtx._metricsStore ??= createMetricsStore(true, reqCtx._handlerStart);
       }
     },
   };
@@ -257,9 +341,16 @@ export function matchMiddleware<TEnv>(
       continue;
     }
 
-    // Check if pathname matches
-    if (entry.regex.test(pathname)) {
-      const params = extractParams(pathname, entry.regex, entry.paramNames);
+    // Run the scope regex ONCE per entry. The old code ran test() then, on a
+    // hit, extractParams' match() — a second full pass over the same string for
+    // every matching entry on the per-request hot path. The regexes carry no
+    // `g` flag, so there is no lastIndex statefulness across this single match.
+    const m = pathname.match(entry.regex);
+    if (m) {
+      const params: Record<string, string> = {};
+      for (let i = 0; i < entry.paramNames.length; i++) {
+        params[entry.paramNames[i]] = safeDecodeURIComponent(m[i + 1] || "");
+      }
       matches.push({ entry, params });
     }
   }
@@ -267,15 +358,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>(
@@ -305,47 +478,22 @@ 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);
-        }
-      });
-      // Also merge shared RequestContext stub (cookies written via cookies().set()).
-      // Dedup Set-Cookie: an inner executeMiddleware (route-level middleware)
-      // may have already merged the same reqCtx cookies into the response.
-      const reqCtx = _getRequestContext();
-      if (reqCtx) {
-        const stubCookies = reqCtx.res.headers.getSetCookie();
-        if (stubCookies.length > 0) {
-          const existing = new Set(mergedHeaders.getSetCookie());
-          for (const cookie of stubCookies) {
-            if (!existing.has(cookie)) {
-              mergedHeaders.append("set-cookie", cookie);
-            }
-          }
-        }
-        reqCtx.res.headers.forEach((value, name) => {
-          if (name !== "set-cookie" && !mergedHeaders.has(name)) {
-            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,
@@ -355,80 +503,108 @@ export async function executeMiddleware<TEnv>(
       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.
     // 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> => {
       if (nextPromise) {
         throw new Error(
           `[@rangojs/router] Middleware called next() more than once.`,
         );
       }
-      nextPromise = next();
+      finishMiddleware();
+      const downstream = next();
+      nextPromise = downstream.then(
+        (res) => {
+          nextResolvedAt = performance.now();
+          return res;
+        },
+        (err) => {
+          nextResolvedAt = performance.now();
+          throw err;
+        },
+      );
       return nextPromise;
     };
 
-    // W5: track whether ctx.set() is called during this middleware
-    let ctxSetCalled = false;
-    if (process.env.NODE_ENV !== "production") {
-      const originalSet = ctx.set;
-      ctx.set = ((...args: any[]) => {
-        ctxSetCalled = true;
-        return (originalSet as Function).apply(ctx, args);
-      }) as typeof ctx.set;
+    // 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), async () => {
+        try {
+          return await entry.handler(ctx, wrappedNext);
+        } catch (error) {
+          // Thrown Response is short-circuit control flow, not an error —
+          // absorb it INSIDE the span so the tracing runner settles the
+          // rango.middleware span as success, not STATUS_ERROR (every auth
+          // redirect would otherwise inflate trace error rates). Returning it
+          // routes through the `if (result instanceof Response)` branch below,
+          // so stub headers and request-context cookies merge identically to an
+          // explicit `return new Response(...)`. Segment handlers already follow
+          // this convention (segment-resolution/helpers.ts keeps result handling
+          // outside the span). Real errors propagate past the span.
+          if (error instanceof Response) return error;
+          throw error;
+        }
+      });
+    } finally {
+      // Settle the middleware own-time metric once on both the success and
+      // error paths (idempotent guard in finishMiddleware).
+      finishMiddleware();
     }
 
-    const result = await entry.handler(ctx, wrappedNext);
+    // 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 (middleware short-circuit).
     // Merge stub headers (from ctx.header before this point) and
-    // RequestContext stub headers (from ctx.setCookie) into the
+    // RequestContext stub headers (from cookies().set()) into the
     // returned Response so they are not lost.
     if (result instanceof Response) {
-      // W5: warn if ctx.set() was called but middleware returned a redirect
-      if (
-        process.env.NODE_ENV !== "production" &&
-        ctxSetCalled &&
-        result.status >= 300 &&
-        result.status < 400
-      ) {
-        warnCtxSetBeforeRedirect(entry.handler);
+      if (isWebSocketUpgradeResponse(result)) {
+        responseHolder.response = result;
+        return result;
       }
-
-      const mergedHeaders = new Headers(result.headers);
-      stubResponse.headers.forEach((value, name) => {
-        if (name.toLowerCase() === "set-cookie") {
-          mergedHeaders.append(name, value);
-        } else if (!mergedHeaders.has(name)) {
-          mergedHeaders.set(name, value);
-        }
-      });
-      // Also merge shared RequestContext stub (cookies written via setCookie).
-      // Dedup Set-Cookie: an inner executeMiddleware (route-level middleware)
-      // may have already merged the same reqCtx cookies into the response.
-      const reqCtx = _getRequestContext();
-      if (reqCtx) {
-        const stubCookies = reqCtx.res.headers.getSetCookie();
-        if (stubCookies.length > 0) {
-          const existing = new Set(mergedHeaders.getSetCookie());
-          for (const cookie of stubCookies) {
-            if (!existing.has(cookie)) {
-              mergedHeaders.append("set-cookie", cookie);
-            }
-          }
-        }
-        reqCtx.res.headers.forEach((value, name) => {
-          if (name !== "set-cookie" && !mergedHeaders.has(name)) {
-            mergedHeaders.set(name, value);
-          }
-        });
-      }
-      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;
@@ -447,19 +623,6 @@ export async function executeMiddleware<TEnv>(
     // If middleware called next(), await it and return the response
     if (nextPromise) {
       await nextPromise;
-
-      // W5: warn if ctx.set() was called but the downstream response is a redirect.
-      // The ctx.set() values will be lost because the redirect navigates away.
-      if (
-        process.env.NODE_ENV !== "production" &&
-        ctxSetCalled &&
-        responseHolder.response &&
-        responseHolder.response.status >= 300 &&
-        responseHolder.response.status < 400
-      ) {
-        warnCtxSetBeforeRedirect(entry.handler);
-      }
-
       return responseHolder.response!;
     }
 
@@ -486,23 +649,12 @@ export async function executeMiddleware<TEnv>(
   // 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) {
-    const stubCookies = reqCtx.res.headers.getSetCookie();
-    if (stubCookies.length > 0) {
-      const existingCookies = new Set(finalResponse.headers.getSetCookie());
-      for (const cookie of stubCookies) {
-        if (!existingCookies.has(cookie)) {
-          finalResponse.headers.append("set-cookie", cookie);
-        }
-      }
-    }
-    // Fill in non-cookie headers that aren't already on the response
-    reqCtx.res.headers.forEach((value, name) => {
-      if (name !== "set-cookie" && !finalResponse.headers.has(name)) {
-        finalResponse.headers.set(name, value);
-      }
-    });
+  if (reqCtx && !isWebSocketUpgradeResponse(finalResponse)) {
+    mergeReqCtxStub(finalResponse.headers, reqCtx);
   }
 
   return finalResponse;
@@ -513,7 +665,7 @@ export async function executeMiddleware<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
@@ -551,6 +703,7 @@ export async function executeInterceptMiddleware<TEnv>(
       return stubResponse;
     }
 
+    const ordinal = index;
     const middleware = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -572,7 +725,30 @@ export async function executeInterceptMiddleware<TEnv>(
       return next();
     };
 
-    const result = await middleware(ctx, guardedNext);
+    // 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,
+    );
+
+    const result: Response | void = await observePhase(
+      PHASES.middleware(label),
+      async () => {
+        try {
+          return await middleware(ctx, guardedNext);
+        } catch (error) {
+          // Thrown Response is short-circuit control flow, parity with the
+          // explicit-return path below. Absorb it INSIDE the span so the tracing
+          // runner settles rango.middleware as success, not STATUS_ERROR (same
+          // reasoning as executeMiddleware's main chain). Real errors propagate.
+          if (error instanceof Response) return error;
+          throw error;
+        }
+      },
+    );
 
     if (result instanceof Response) {
       earlyResponse = result;
@@ -596,21 +772,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);
-      stubResponse.headers.forEach((value, name) => {
-        if (name.toLowerCase() === "set-cookie") {
-          mergedHeaders.append(name, value);
-        } else if (!mergedHeaders.has(name)) {
-          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;
@@ -651,7 +819,6 @@ export async function executeLoaderMiddleware<TEnv>(
       regex: null,
       paramNames: [],
       handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params,
   }));