@rangojs/router 0.0.0-experimental.25 → 0.0.0-experimental.25dbaac3

package/src/router/middleware.ts

@@ -10,6 +10,8 @@
  */
 
 import { contextGet, contextSet } from "../context-var.js";
+import { safeDecodeURIComponent } from "./url-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import type {
   CollectedMiddleware,
   MiddlewareCollectableEntry,
@@ -21,6 +23,8 @@ import type {
 import { _getRequestContext } from "../server/request-context.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 for backward compatibility
 export type {
@@ -34,23 +38,9 @@ export type {
 } 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.`,
-  );
-}
-
 const MIDDLEWARE_METRIC_DEPTH = 1;
+/** Ignore post-next() durations below this threshold (measurement noise). */
+const POST_METRIC_MIN_DURATION_MS = 0.01;
 
 function getMiddlewareMetricBase<TEnv>(
   entry: MiddlewareEntry<TEnv>,
@@ -73,11 +63,6 @@ function getMiddlewareMetricLabel<TEnv>(
   return `middleware:${getMiddlewareMetricBase(entry, ordinal)}`;
 }
 
-/** Reset W5 deduplication state (for tests only). */
-export function _resetW5Warnings(): void {
-  warnedRedirectMiddleware = new WeakSet();
-}
-
 /**
  * Parse a route pattern into regex and param names
  * Supports: *, /path, /path/*, /path/:param, /path/:param/*
@@ -130,7 +115,12 @@ 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,
@@ -142,7 +132,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;
 }
@@ -166,7 +156,7 @@ export function createMiddlewareContext<TEnv>(
     search?: Record<string, unknown>,
   ) => string,
 ): MiddlewareContext<TEnv> {
-  const url = new URL(request.url);
+  const url = stripInternalParams(new URL(request.url));
 
   // Track the initial response to detect pre/post-next() phase.
   // Before next(): responseHolder.response === initialResponse (the stub).
@@ -182,13 +172,37 @@ 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;
+  };
+
+  // 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,
+    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"] {
@@ -199,33 +213,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()) {
@@ -244,6 +241,24 @@ 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) => {
@@ -297,9 +312,9 @@ export function matchMiddleware<TEnv>(
  *
  * 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`
+ * - `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 Response to stop chain
  * - Error catching: try/catch around `next()` works
  */
@@ -361,6 +376,11 @@ export async function executeMiddleware<TEnv>(
         });
       }
 
+      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,
@@ -382,13 +402,14 @@ export async function executeMiddleware<TEnv>(
       reverse,
     );
     const metricStart = performance.now();
+    const metricLabel = getMiddlewareMetricLabel(entry, middlewareOrdinal);
     let middlewareFinished = false;
     const finishMiddleware = () => {
       if (!middlewareFinished) {
         middlewareFinished = true;
         appendMetric(
           _getRequestContext()?._metricsStore,
-          getMiddlewareMetricLabel(entry, middlewareOrdinal),
+          `${metricLabel}:pre`,
           metricStart,
           performance.now() - metricStart,
           MIDDLEWARE_METRIC_DEPTH,
@@ -400,6 +421,7 @@ export async function executeMiddleware<TEnv>(
     // 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(
@@ -407,44 +429,61 @@ export async function executeMiddleware<TEnv>(
         );
       }
       finishMiddleware();
-      nextPromise = next();
+      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;
-    }
-
     let result: Response | void;
     try {
       result = await entry.handler(ctx, wrappedNext);
     } catch (error) {
-      finishMiddleware();
-      throw 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 (middleware short-circuit).
     // Merge stub headers (from ctx.header before this point) and
     // RequestContext stub headers (from ctx.setCookie) 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") {
@@ -495,19 +534,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!;
     }
 
@@ -534,8 +560,11 @@ 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) {
+  if (reqCtx && !isWebSocketUpgradeResponse(finalResponse)) {
     const stubCookies = reqCtx.res.headers.getSetCookie();
     if (stubCookies.length > 0) {
       const existingCookies = new Set(finalResponse.headers.getSetCookie());
@@ -620,7 +649,18 @@ export async function executeInterceptMiddleware<TEnv>(
       return next();
     };
 
-    const result = await middleware(ctx, guardedNext);
+    let result: Response | void;
+    try {
+      result = await 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;

package/src/router/navigation-snapshot.ts

@@ -0,0 +1,182 @@
+/**
+ * Navigation Snapshot
+ *
+ * Pure data type representing the navigation-specific state for partial requests.
+ * Consolidates the header parsing, previous-route matching, intercept-context
+ * detection, and segment ID filtering that previously lived inline in
+ * createMatchContextForPartial (match-api.ts).
+ *
+ * resolveNavigation() is the factory: given a request + URL + current route key,
+ * it returns a NavigationSnapshot (or null if no previous URL).
+ */
+
+import type { RouteMatchResult } from "./pattern-matching.js";
+
+/**
+ * Snapshot of navigation state for a partial (navigation/action) request.
+ *
+ * Contains the "where are we coming from?" data: previous route, intercept
+ * source, client segment state, and derived flags.
+ */
+export interface NavigationSnapshot {
+  /** Previous page URL (from X-RSC-Router-Client-Path or Referer) */
+  prevUrl: URL;
+  /** Params from the previous route match */
+  prevParams: Record<string, string>;
+  /** Previous route match result (null if prev URL doesn't match any route) */
+  prevMatch: RouteMatchResult | null;
+
+  /** URL used as intercept context source */
+  interceptContextUrl: URL;
+  /** Route match for the intercept context URL */
+  interceptContextMatch: RouteMatchResult | null;
+
+  /** Raw segment IDs the client currently has */
+  clientSegmentIds: string[];
+  /** Set version for O(1) lookup */
+  clientSegmentSet: Set<string>;
+  /** Segment IDs filtered to remove parallel (.@) and loader (D\d+.) entries */
+  filteredSegmentIds: string[];
+
+  /** Whether client considers its cache stale */
+  stale: boolean;
+
+  /** Whether the intercept context route is the same as the current route */
+  isSameRouteNavigation: boolean;
+
+  /** Effective "from" URL (intercept source URL when present, else prevUrl) */
+  effectiveFromUrl: URL;
+  /** Effective "from" match (intercept source match when present, else prevMatch) */
+  effectiveFromMatch: RouteMatchResult | null;
+
+  /** Whether an intercept source header was present */
+  hasInterceptSource: boolean;
+
+  /** Whether an HMR request header was present */
+  isHmr: boolean;
+}
+
+export interface ResolveNavigationDeps {
+  findMatch: (pathname: string) => RouteMatchResult | null;
+}
+
+/**
+ * Resolve navigation state from a partial request.
+ *
+ * Returns null if no previous URL is available (required for partial navigation).
+ *
+ * @param request - The incoming HTTP request
+ * @param url - Parsed URL of the request
+ * @param currentRouteKey - Route key of the current (target) route match
+ * @param deps - Dependencies (findMatch)
+ */
+export function resolveNavigation(
+  request: Request,
+  url: URL,
+  currentRouteKey: string,
+  deps: ResolveNavigationDeps,
+): NavigationSnapshot | null {
+  // Parse client state from RSC request params/headers
+  const clientSegmentIds =
+    url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
+  const stale = url.searchParams.get("_rsc_stale") === "true";
+  const previousUrl =
+    request.headers.get("X-RSC-Router-Client-Path") ||
+    request.headers.get("Referer");
+  const interceptSourceUrl = request.headers.get(
+    "X-RSC-Router-Intercept-Source",
+  );
+  const isHmr = !!request.headers.get("X-RSC-HMR");
+
+  if (!previousUrl) {
+    return null;
+  }
+
+  // Parse previous URL
+  let prevUrl: URL;
+  try {
+    prevUrl = new URL(previousUrl, url.origin);
+  } catch {
+    return null;
+  }
+
+  // Parse intercept context URL
+  let interceptContextUrl: URL;
+  try {
+    interceptContextUrl = interceptSourceUrl
+      ? new URL(interceptSourceUrl, url.origin)
+      : prevUrl;
+  } catch {
+    interceptContextUrl = prevUrl;
+  }
+
+  // Match previous and intercept context routes
+  const prevMatch = deps.findMatch(prevUrl.pathname);
+  const prevParams = prevMatch?.params || {};
+  const interceptContextMatch = interceptSourceUrl
+    ? deps.findMatch(interceptContextUrl.pathname)
+    : prevMatch;
+
+  // Derived state
+  const isSameRouteNavigation = !!(
+    interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
+  );
+
+  const hasInterceptSource = !!interceptSourceUrl;
+  const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : prevUrl;
+  const effectiveFromMatch = hasInterceptSource
+    ? interceptContextMatch
+    : prevMatch;
+
+  // Filter segment IDs: remove parallel (.@) and loader (D\d+.) entries
+  const filteredSegmentIds = clientSegmentIds.filter((id) => {
+    if (id.includes(".@")) return false;
+    if (/D\d+\./.test(id)) return false;
+    return true;
+  });
+
+  const clientSegmentSet = new Set(clientSegmentIds);
+
+  return {
+    prevUrl,
+    prevParams,
+    prevMatch,
+    interceptContextUrl,
+    interceptContextMatch,
+    clientSegmentIds,
+    clientSegmentSet,
+    filteredSegmentIds,
+    stale,
+    isSameRouteNavigation,
+    effectiveFromUrl,
+    effectiveFromMatch,
+    hasInterceptSource,
+    isHmr,
+  };
+}
+
+/**
+ * Test helper: create a NavigationSnapshot with sensible defaults and overrides.
+ */
+export function createNavigationSnapshot(
+  overrides?: Partial<NavigationSnapshot>,
+): NavigationSnapshot {
+  const defaultUrl = new URL("http://localhost/");
+  return {
+    prevUrl: defaultUrl,
+    prevParams: {},
+    prevMatch: null,
+    interceptContextUrl: defaultUrl,
+    interceptContextMatch: null,
+    clientSegmentIds: [],
+    clientSegmentSet: new Set(),
+    filteredSegmentIds: [],
+    stale: false,
+    isSameRouteNavigation: false,
+    effectiveFromUrl: defaultUrl,
+    effectiveFromMatch: null,
+    hasInterceptSource: false,
+    isHmr: false,
+    ...overrides,
+  };
+}