@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1b930379

package/src/router/middleware.ts

@@ -20,6 +20,7 @@ import type {
 } from "./middleware-types.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,25 +34,29 @@ 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}`;
 }
 
-/** Reset W5 deduplication state (for tests only). */
-export function _resetW5Warnings(): void {
-  warnedRedirectMiddleware = new WeakSet();
+function getMiddlewareMetricLabel<TEnv>(
+  entry: MiddlewareEntry<TEnv>,
+  ordinal: number,
+): string {
+  return `middleware:${getMiddlewareMetricBase(entry, ordinal)}`;
 }
 
 /**
@@ -158,9 +163,25 @@ 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"],
@@ -175,24 +196,8 @@ 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) =>
@@ -202,6 +207,8 @@ export function createMiddlewareContext<TEnv>(
       contextSet(variables, keyOrVar, value);
     }) as MiddlewareContext<TEnv>["set"],
 
+    var: variables as MiddlewareContext<TEnv>["var"],
+
     header(name: string, value: string): void {
       // Before next(): delegate to shared RequestContext stub
       if (isPreNext()) {
@@ -220,6 +227,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) => {
@@ -227,6 +252,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);
+      }
+    },
   };
 }
 
@@ -265,9 +298,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
  */
@@ -309,14 +342,21 @@ export async function executeMiddleware<TEnv>(
         }
       });
       // Also merge shared RequestContext stub (cookies written via cookies().set()).
-      // Set-Cookie duplication is prevented by createResponseWithMergedHeaders
-      // draining Set-Cookie from ctx.res after merging (helpers.ts).
+      // 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);
           }
         });
@@ -332,6 +372,7 @@ export async function executeMiddleware<TEnv>(
       return responseHolder.response;
     }
 
+    const middlewareOrdinal = index;
     const { entry, params } = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -341,48 +382,77 @@ 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;
+    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,
+        );
+      }
     }
-
-    const result = await entry.handler(ctx, wrappedNext);
 
     // 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);
-      }
-
       const mergedHeaders = new Headers(result.headers);
       stubResponse.headers.forEach((value, name) => {
         if (name.toLowerCase() === "set-cookie") {
@@ -391,13 +461,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);
           }
         });
@@ -424,19 +503,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!;
     }
 
@@ -459,6 +525,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;
 }
 

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.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

package/src/router/prerender-match.ts

@@ -101,6 +101,7 @@ export async function matchForPrerender<TEnv = any>(
       env: {} as TEnv,
       request: new Request("http://prerender" + pathname),
       url: new URL("http://prerender" + pathname),
+      originalUrl: new URL("http://prerender" + pathname),
       pathname,
       searchParams: new URLSearchParams(),
       var: variables,
@@ -116,6 +117,7 @@ export async function matchForPrerender<TEnv = any>(
       deleteCookie: () => {},
       header: () => {},
       setStatus: () => {},
+      _setStatus: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
@@ -331,6 +333,7 @@ export async function renderStaticSegment<TEnv = any>(
     env: {} as TEnv,
     request: syntheticRequest,
     url: syntheticUrl,
+    originalUrl: syntheticUrl,
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
     var: {},
@@ -344,6 +347,7 @@ export async function renderStaticSegment<TEnv = any>(
     deleteCookie: () => {},
     header: () => {},
     setStatus: () => {},
+    _setStatus: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,

package/src/router/revalidation.ts

@@ -84,6 +84,7 @@ export async function evaluateRevalidation<TEnv>(
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
+  const searchChanged = prevUrl.search !== nextUrl.search;
 
   // Trace helper: push a structured entry to the request-scoped trace buffer.
   // Guarded by isTraceActive() so object construction is skipped in production.
@@ -134,19 +135,38 @@ export async function evaluateRevalidation<TEnv>(
     // Only the route segment revalidates by default - all others require explicit opt-in
 
     if (segment.type === "route") {
-      // Route segments revalidate when params change
-      // Routes are the primary param-dependent content and always need updates
-      defaultShouldRevalidate = paramsChanged;
+      // Route segments revalidate when path params OR search params change.
+      // Search params (e.g., ?page=2&sort=price) are server-parsed via ctx.search,
+      // so the handler must re-execute to produce updated content.
+      const routeChanged = paramsChanged || searchChanged;
+      defaultShouldRevalidate = routeChanged;
       defaultReason = paramsChanged
         ? "nav:params-changed"
-        : "nav:params-unchanged";
-      if (paramsChanged) {
-        debugLog("revalidation", "route params changed, revalidating", {
+        : searchChanged
+          ? "nav:search-changed"
+          : "nav:params-unchanged";
+      if (routeChanged) {
+        debugLog("revalidation", "route revalidating", {
           segmentId: segment.id,
+          paramsChanged,
+          searchChanged,
         });
       }
+    } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
+      // Children of the route path (loaders, orphan layouts/parallels)
+      // revalidate when path params or search params change
+      defaultShouldRevalidate = true;
+      defaultReason = paramsChanged
+        ? "nav:route-child-params-changed"
+        : "nav:route-child-search-changed";
+      debugLog("revalidation", "route child revalidating", {
+        segmentId: segment.id,
+        segmentType: segment.type,
+        paramsChanged,
+        searchChanged,
+      });
     } else {
-      // Layouts and parallels default to no revalidation
+      // Parent layouts and parallels default to no revalidation
       // Cannot assume these segments depend on params without explicit declaration
       // Use custom revalidation functions to opt-in when needed
       defaultShouldRevalidate = false;

package/src/router/router-interfaces.ts

@@ -258,10 +258,17 @@ export interface RSCRouterInternal<
 
   /**
    * Cache-Control header value for prefetch responses.
-   * False means no browser caching of prefetch responses.
+   * False means no caching of prefetch responses.
+   * Derived from prefetchCacheTTL.
    */
   readonly prefetchCacheControl: string | false;
 
+  /**
+   * TTL in milliseconds for the client-side in-memory prefetch cache.
+   * 0 means caching is disabled.
+   */
+  readonly prefetchCacheTTL: number;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods
@@ -269,6 +276,12 @@ export interface RSCRouterInternal<
    */
   readonly warmupEnabled: boolean;
 
+  /**
+   * Whether router-wide performance debugging is enabled.
+   * Used by the request handler to create metrics before middleware runs.
+   */
+  readonly debugPerformance?: boolean;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.

package/src/router/router-options.ts

@@ -239,7 +239,7 @@ export interface RSCRouterOptions<TEnv = any> {
    *
    * @example Static config
    * ```typescript
-   * import { MemorySegmentCacheStore } from "rsc-router/rsc";
+   * import { MemorySegmentCacheStore } from "@rangojs/router/cache";
    *
    * const router = createRouter({
    *   cache: {
@@ -415,16 +415,21 @@ export interface RSCRouterOptions<TEnv = any> {
   version?: string;
 
   /**
-   * Cache-Control header value for prefetch responses.
-   * Only applied to non-intercept partial responses that include the
-   * `X-Rango-Prefetch` header (sent by the Link component's prefetch fetch).
-   * Navigation responses are never cached by the browser.
+   * TTL (in seconds) for the in-memory prefetch cache and the
+   * Cache-Control header on prefetch responses.
    *
-   * Set to `false` to disable browser caching of prefetch responses entirely.
+   * Controls how long prefetch responses are kept in the client-side
+   * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
+   * on server responses for CDN/edge caching.
    *
-   * @default "private, max-age=300"
+   * The cache is automatically invalidated on server actions regardless
+   * of TTL, so this is primarily a staleness safety net.
+   *
+   * Set to `false` to disable prefetch caching entirely.
+   *
+   * @default 300 (5 minutes)
    */
-  prefetchCacheControl?: string | false;
+  prefetchCacheTTL?: number | false;
 
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.