@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/router/middleware.ts

@@ -19,6 +19,9 @@ import type {
   ResponseHolder,
 } from "./middleware-types.js";
 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";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -32,6 +35,31 @@ export type {
 } from "./middleware-types.js";
 export { parseCookies, serializeCookie } from "./middleware-cookies.js";
 
+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>,
+  ordinal: number,
+): string {
+  const handlerName = entry.handler.name?.trim();
+  const scope = entry.pattern ?? "*";
+
+  if (handlerName) {
+    return `${handlerName}@${scope}`;
+  }
+
+  return `${scope}#${ordinal + 1}`;
+}
+
+function getMiddlewareMetricLabel<TEnv>(
+  entry: MiddlewareEntry<TEnv>,
+  ordinal: number,
+): string {
+  return `middleware:${getMiddlewareMetricBase(entry, ordinal)}`;
+}
+
 /**
  * Parse a route pattern into regex and param names
  * Supports: *, /path, /path/*, /path/:param, /path/:param/*
@@ -120,7 +148,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).
@@ -136,41 +164,49 @@ 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;
+  };
+
   return {
     request,
     url,
+    originalUrl: new URL(request.url),
     pathname: url.pathname,
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
     params,
-
-    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;
+    // 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"];
     },
-    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()) {
@@ -189,6 +225,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) => {
@@ -196,6 +250,14 @@ export function createMiddlewareContext<TEnv>(
           `ctx.reverse() is not available - route map was not provided to middleware context`,
         );
       }),
+
+    debugPerformance(): void {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) {
+        reqCtx._debugPerformance = true;
+        reqCtx._metricsStore ??= createMetricsStore(true);
+      }
+    },
   };
 }
 
@@ -234,9 +296,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
  */
@@ -267,8 +329,8 @@ 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
+      // 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") {
@@ -277,13 +339,22 @@ export async function executeMiddleware<TEnv>(
           mergedHeaders.set(name, value);
         }
       });
-      // Also merge shared RequestContext stub (cookies written via cookies().set())
+      // 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.toLowerCase() === "set-cookie") {
-            mergedHeaders.append(name, value);
-          } else if (!mergedHeaders.has(name)) {
+          if (name !== "set-cookie" && !mergedHeaders.has(name)) {
             mergedHeaders.set(name, value);
           }
         });
@@ -299,6 +370,7 @@ export async function executeMiddleware<TEnv>(
       return responseHolder.response;
     }
 
+    const middlewareOrdinal = index;
     const { entry, params } = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -308,16 +380,71 @@ 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
-    // 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);
+    let result: Response | void;
+    try {
+      result = await entry.handler(ctx, wrappedNext);
+    } catch (error) {
+      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
@@ -332,13 +459,22 @@ export async function executeMiddleware<TEnv>(
           mergedHeaders.set(name, value);
         }
       });
-      // Also merge shared RequestContext stub (cookies written via setCookie)
+      // 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.toLowerCase() === "set-cookie") {
-            mergedHeaders.append(name, value);
-          } else if (!mergedHeaders.has(name)) {
+          if (name !== "set-cookie" && !mergedHeaders.has(name)) {
             mergedHeaders.set(name, value);
           }
         });
@@ -387,6 +523,29 @@ export async function executeMiddleware<TEnv>(
     throw new Error("No response generated by middleware chain");
   }
 
+  // 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.
+  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);
+      }
+    });
+  }
+
   return finalResponse;
 }
 
@@ -443,7 +602,18 @@ export async function executeInterceptMiddleware<TEnv>(
       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();
+    };
+
+    const result = await middleware(ctx, guardedNext);
 
     if (result instanceof Response) {
       earlyResponse = result;
@@ -467,12 +637,14 @@ export async function executeInterceptMiddleware<TEnv>(
     });
 
     if (hasStubHeaders) {
-      // Clone and merge headers from stub into early response
+      // 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 {
+        } else if (!mergedHeaders.has(name)) {
           mergedHeaders.set(name, value);
         }
       });

package/src/router/pattern-matching.ts

@@ -16,6 +16,7 @@ export interface ParsedSegment {
   value: string; // static text, param name, or "*"
   optional: boolean;
   constraint?: string[]; // enum values like ["en", "gb"]
+  suffix?: string; // literal text after param in same segment (e.g., ".html")
 }
 
 /**
@@ -39,11 +40,21 @@ export function parsePattern(pattern: string): ParsedSegment[] {
   // - :param(a|b)?
   // - *
   const segmentRegex =
-    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?|(\*)|([^/]+))/g;
+    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
 
   let match;
   while ((match = segmentRegex.exec(pattern)) !== null) {
-    const [, , paramName, , constraint, optional, wildcard, staticText] = match;
+    const [
+      ,
+      ,
+      paramName,
+      ,
+      constraint,
+      optional,
+      suffix,
+      wildcard,
+      staticText,
+    ] = match;
 
     if (wildcard) {
       segments.push({ type: "wildcard", value: "*", optional: false });
@@ -53,6 +64,7 @@ export function parsePattern(pattern: string): ParsedSegment[] {
         value: paramName,
         optional: optional === "?",
         constraint: constraint ? constraint.split("|") : undefined,
+        suffix: suffix || undefined,
       });
     } else if (staticText) {
       segments.push({ type: "static", value: staticText, optional: false });
@@ -139,16 +151,19 @@ export function compilePattern(pattern: string): CompiledPattern {
       regexPattern += "/(.*)";
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
+      const suffixPattern = segment.suffix ? escapeRegex(segment.suffix) : "";
       const valuePattern = segment.constraint
-        ? `(${segment.constraint.join("|")})`
-        : "([^/]+)";
+        ? `(${segment.constraint.map(escapeRegex).join("|")})`
+        : segment.suffix
+          ? "([^/]+?)"
+          : "([^/]+)";
 
       if (segment.optional) {
         optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
-        regexPattern += `(?:/${valuePattern})?`;
+        regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
-        regexPattern += `/${valuePattern}`;
+        regexPattern += `/${valuePattern}${suffixPattern}`;
       }
     } else {
       // Static segment
@@ -388,6 +403,9 @@ export function findMatch<TEnv>(
       const prFlag = entry.prerenderRouteKeys?.has(routeKey)
         ? { pr: true as const }
         : {};
+      const ptFlag = entry.passthroughRouteKeys?.has(routeKey)
+        ? { pt: true as const }
+        : {};
 
       // Try exact match first
       const match = regex.exec(pathname);
@@ -419,6 +437,7 @@ export function findMatch<TEnv>(
             optionalParams,
             redirectTo: pathname + "/",
             ...prFlag,
+            ...ptFlag,
           };
         } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
           // Mode says never have trailing slash, but pathname has it
@@ -429,10 +448,18 @@ export function findMatch<TEnv>(
             optionalParams,
             redirectTo: pathname.slice(0, -1),
             ...prFlag,
+            ...ptFlag,
           };
         }
 
-        return { entry, routeKey, params, optionalParams, ...prFlag };
+        return {
+          entry,
+          routeKey,
+          params,
+          optionalParams,
+          ...prFlag,
+          ...ptFlag,
+        };
       }
 
       // Try alternate pathname (opposite trailing slash)
@@ -446,7 +473,14 @@ export function findMatch<TEnv>(
         // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
           // Match without redirect
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never") {
           // Redirect to no trailing slash
           if (pathnameHasTrailingSlash) {
@@ -457,9 +491,17 @@ export function findMatch<TEnv>(
               optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
+              ...ptFlag,
             };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "always") {
           // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
@@ -470,9 +512,17 @@ export function findMatch<TEnv>(
               optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
+              ...ptFlag,
             };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else {
           // No explicit mode - use pattern-based detection
           // Redirect to canonical form (what the pattern defines)
@@ -486,6 +536,7 @@ export function findMatch<TEnv>(
             optionalParams,
             redirectTo: canonicalPath,
             ...prFlag,
+            ...ptFlag,
           };
         }
       }