@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/router/middleware.ts

@@ -11,7 +11,6 @@
 
 import { contextGet, contextSet } from "../context-var.js";
 import type {
-  CookieOptions,
   CollectedMiddleware,
   MiddlewareCollectableEntry,
   MiddlewareContext,
@@ -19,7 +18,9 @@ import type {
   MiddlewareFn,
   ResponseHolder,
 } from "./middleware-types.js";
-import { parseCookies, serializeCookie } from "./middleware-cookies.js";
+import { _getRequestContext } from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+import { appendMetric, createMetricsStore } from "./metrics.js";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -33,6 +34,52 @@ 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>,
+  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)}`;
+}
+
+/** 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/*
@@ -107,7 +154,7 @@ export function extractParams(
  *
  * 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,
@@ -122,9 +169,20 @@ export function createMiddlewareContext<TEnv>(
   ) => string,
 ): MiddlewareContext<TEnv> {
   const url = new URL(request.url);
-  const cookieHeader = request.headers.get("Cookie");
-  let parsedCookies: Record<string, string> | null = null;
 
+  // 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>
   return {
     request,
@@ -133,9 +191,23 @@ export function createMiddlewareContext<TEnv>(
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
     params,
+    // 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 getter - returns the stub or real response (always available)
     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",
@@ -143,50 +215,9 @@ export function createMiddlewareContext<TEnv>(
       }
       return responseHolder.response;
     },
-
-    // res setter - allows middleware to replace the response
-    set res(response: Response) {
-      responseHolder.response = response;
-    },
-
-    cookie(name: string): string | undefined {
-      if (!parsedCookies) {
-        parsedCookies = parseCookies(cookieHeader);
-      }
-      return parsedCookies[name];
-    },
-
-    cookies(): Record<string, string> {
-      if (!parsedCookies) {
-        parsedCookies = parseCookies(cookieHeader);
-      }
-      return { ...parsedCookies };
-    },
-
-    setCookie(name: string, value: string, options?: CookieOptions): void {
-      if (!responseHolder.response) {
-        throw new Error(
-          "ctx.setCookie() is not available - responseHolder was not initialized",
-        );
-      }
-      responseHolder.response.headers.append(
-        "Set-Cookie",
-        serializeCookie(name, value, options),
-      );
-    },
-
-    deleteCookie(
-      name: string,
-      options?: Pick<CookieOptions, "domain" | "path">,
-    ): void {
-      if (!responseHolder.response) {
-        throw new Error(
-          "ctx.deleteCookie() is not available - responseHolder was not initialized",
-        );
-      }
-      responseHolder.response.headers.append(
-        "Set-Cookie",
-        serializeCookie(name, "", { ...options, maxAge: 0 }),
+    set res(_: Response) {
+      throw new Error(
+        "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
       );
     },
 
@@ -198,6 +229,15 @@ export function createMiddlewareContext<TEnv>(
     }) 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;
+        }
+      }
+      // After next() or standalone: write to current response
       if (!responseHolder.response) {
         throw new Error(
           "ctx.header() is not available - responseHolder was not initialized",
@@ -213,6 +253,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);
+      }
+    },
   };
 }
 
@@ -284,8 +332,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") {
@@ -294,6 +342,26 @@ export async function executeMiddleware<TEnv>(
           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);
+          }
+        });
+      }
 
       // Clone response with merged headers (mutable for post-next() modifications)
       responseHolder.response = new Response(response.body, {
@@ -305,6 +373,7 @@ export async function executeMiddleware<TEnv>(
       return responseHolder.response;
     }
 
+    const middlewareOrdinal = index;
     const { entry, params } = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -314,21 +383,132 @@ 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);
+    // 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;
+    }
+    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 ctx.setCookie) into the
+    // returned Response so they are not lost.
     if (result instanceof Response) {
-      responseHolder.response = result;
-      return result;
+      // 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);
+      }
+
+      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,
+      });
+      responseHolder.response = merged;
+      return merged;
     }
 
     // Warn about unexpected return values (non-Response, non-undefined)
@@ -344,6 +524,19 @@ 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!;
     }
 
@@ -366,70 +559,30 @@ 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,
-  reverse?: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string,
-): Promise<void> {
-  if (middlewares.length === 0) {
-    return;
-  }
-
-  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,
-      reverse,
-    );
-
-    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.`,
-      );
+  // 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 stubResponse;
-  };
-
-  await next();
-  // Headers/cookies set on stubResponse will be merged by the caller
+  return finalResponse;
 }
 
 /**
@@ -485,19 +638,24 @@ 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;
       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;
   };
 
@@ -515,12 +673,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);
         }
       });