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

package/src/router/error-handling.ts

@@ -1,7 +1,7 @@
 /**
  * Router Error Handling Utilities
  *
- * Error boundary and not-found boundary handling for RSC Router.
+ * Error boundary and not-found boundary handling for Rango.
  * Also includes the shared invokeOnError utility for error callback invocation.
  */
 
@@ -117,16 +117,10 @@ export function findNearestErrorBoundary(
   let current: EntryData | null = entry;
 
   while (current) {
-    // Check if this entry has error boundaries defined
     if (current.errorBoundary && current.errorBoundary.length > 0) {
-      // Return the last error boundary (most recently defined takes precedence)
       return current.errorBoundary[current.errorBoundary.length - 1];
     }
 
-    // Check orphan layouts for error boundaries
-    // Orphan layouts are siblings that render alongside the main route chain
-    // They can define error boundaries that catch errors from routes in the same route group
-    // Check from first to last (first sibling takes precedence as the "outer" wrapper)
     if (current.layout && current.layout.length > 0) {
       for (const orphan of current.layout) {
         if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
@@ -153,11 +147,21 @@ export function findNearestNotFoundBoundary(
   let current: EntryData | null = entry;
 
   while (current) {
-    // Check if this entry has notFound boundaries defined
     if (current.notFoundBoundary && current.notFoundBoundary.length > 0) {
-      // Return the last notFound boundary (most recently defined takes precedence)
       return current.notFoundBoundary[current.notFoundBoundary.length - 1];
     }
+
+    // Check orphan layouts mirroring findNearestErrorBoundary: notFoundBoundary
+    // attaches identically (onto parent.notFoundBoundary), and an orphan layout
+    // (parent=null) is reachable only via this scan. First sibling is "outer".
+    if (current.layout && current.layout.length > 0) {
+      for (const orphan of current.layout) {
+        if (orphan.notFoundBoundary && orphan.notFoundBoundary.length > 0) {
+          return orphan.notFoundBoundary[orphan.notFoundBoundary.length - 1];
+        }
+      }
+    }
+
     current = current.parent;
   }
 
@@ -165,6 +169,37 @@ export function findNearestNotFoundBoundary(
   return defaultNotFoundBoundary || null;
 }
 
+/**
+ * Normalize an error's cause into a Flight-serializable shape.
+ * ErrorInfo.cause crosses the RSC serialization boundary (via
+ * LoaderDataResult.error + error-segment fallback props); a non-serializable
+ * cause (function, class instance, circular object) would make Flight
+ * serialization throw and mask the original loader error.
+ */
+function normalizeCause(cause: unknown): unknown {
+  if (cause == null) return undefined;
+  const t = typeof cause;
+  if (t === "string" || t === "number" || t === "boolean") return cause;
+  // The whole body is guarded: even `instanceof`/clone can run user code (a
+  // Proxy trap, a throwing getter), and this helper must never throw —
+  // throwing here would mask the original loader error it exists to protect.
+  try {
+    if (cause instanceof Error) {
+      return { name: cause.name, message: cause.message, stack: cause.stack };
+    }
+    // Prefer preserving a serializable object/array intact (Flight uses
+    // structured-clone-like semantics); fall back to a string when the value
+    // is circular, host-bound, or otherwise non-serializable.
+    return structuredClone(cause);
+  } catch {
+    try {
+      return String(cause);
+    } catch {
+      return "[unstringifiable cause]";
+    }
+  }
+}
+
 /**
  * Create ErrorInfo from an error object
  * Sanitizes error details in production
@@ -182,7 +217,7 @@ export function createErrorInfo(
       name: error.name,
       code: (error as any).code,
       stack: isDev ? error.stack : undefined,
-      cause: isDev ? error.cause : undefined,
+      cause: isDev ? normalizeCause(error.cause) : undefined,
       segmentId,
       segmentType,
     };
@@ -207,22 +242,17 @@ export function createErrorSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  // Determine the component to render
   let component: ReactNode;
 
   if (typeof fallback === "function") {
-    // ErrorBoundaryHandler - call with error info
     const props: ErrorBoundaryFallbackProps = {
       error: errorInfo,
     };
     component = fallback(props);
   } else {
-    // Static ReactNode fallback
     component = fallback;
   }
 
-  // Error segment uses the same ID as the layout that has the error boundary
-  // The error boundary content replaces the layout's outlet content
   return {
     id: entry.shortCode,
     namespace: entry.id,
@@ -261,17 +291,14 @@ export function createNotFoundSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  // Determine the component to render
   let component: ReactNode;
 
   if (typeof fallback === "function") {
-    // NotFoundBoundaryHandler - call with props
     const props: NotFoundBoundaryFallbackProps = {
       notFound: notFoundInfo,
     };
     component = fallback(props);
   } else {
-    // Static ReactNode fallback
     component = fallback;
   }
 

package/src/router/find-match.ts

@@ -1,5 +1,5 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouteTrie, getRouterTrie } from "../route-map-builder.js";
+import { getRouterTrie } from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -8,6 +8,16 @@ import {
 import type { MetricsStore } from "../server/context";
 import type { RouteEntry } from "../types";
 
+// The single-entry cache is module-lifetime, keyed only on pathname, so the same
+// result object is handed to every same-pathname request. ctx.params aliases
+// this object, so handlers mutating it would corrupt the cache for later requests.
+// Clone params; entry/flags are read-only and shared safely.
+function cloneMatchResult<TEnv>(
+  r: RouteMatchResult<TEnv> | null,
+): RouteMatchResult<TEnv> | null {
+  return r ? { ...r, params: { ...r.params } } : null;
+}
+
 export interface FindMatchDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
   evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void;
@@ -27,20 +37,14 @@ export function createFindMatch<TEnv = any>(
   let lastFindMatchPathname: string | null = null;
   let lastFindMatchResult: RouteMatchResult<TEnv> | null = null;
 
-  // Wrapper for findMatch that uses routesEntries
-  // Handles lazy evaluation by evaluating lazy entries on first match.
-  // Phase 1: try O(path_length) trie match.
-  // Phase 2: fall back to regex iteration.
   return function findMatch(
     pathname: string,
     ms?: MetricsStore,
   ): RouteMatchResult<TEnv> | null {
-    // Return cached result if same pathname (avoids double-match per request)
     if (lastFindMatchPathname === pathname) {
-      return lastFindMatchResult;
+      return cloneMatchResult(lastFindMatchResult);
     }
 
-    // Helper to push sub-metrics
     const pushMetric = ms
       ? (label: string, start: number) => {
           ms.metrics.push({
@@ -51,15 +55,15 @@ export function createFindMatch<TEnv = any>(
         }
       : undefined;
 
-    // Phase 1: Try trie match (O(path_length))
-    // Prefer per-router trie (isolated) over global trie (merged).
-    const routeTrie = getRouterTrie(deps.routerId) ?? getRouteTrie();
+    const routeTrie = getRouterTrie(deps.routerId);
+    let trieMatched = false;
     if (routeTrie) {
       const trieStart = performance.now();
       const trieResult = tryTrieMatch(routeTrie, pathname);
       pushMetric?.("match:trie", trieStart);
 
       if (trieResult) {
+        trieMatched = true;
         // Find the RouteEntry that contains this route.
         // Multiple entries can share the same staticPrefix (e.g., several
         // include("/", patterns) calls all produce staticPrefix=""). Evaluate
@@ -81,12 +85,8 @@ export function createFindMatch<TEnv = any>(
           }
         }
 
-        // If no entry had the route in its routes map, use the first matching
-        // entry as fallback (handles main entry with inline routes not yet
-        // reflected in its routes object).
         if (!entry) entry = fallbackEntry;
 
-        // If entry not found (nested include not yet discovered), evaluate parent
         if (!entry) {
           const parent = deps.routesEntries.find(
             (e) =>
@@ -110,9 +110,7 @@ export function createFindMatch<TEnv = any>(
             entry,
             routeKey: trieResult.routeKey,
             params: trieResult.params,
-            optionalParams: new Set(trieResult.optionalParams || []),
             redirectTo: trieResult.redirectTo,
-            ancestry: trieResult.ancestry,
             ...(trieResult.pr ? { pr: true } : {}),
             ...(trieResult.pt ? { pt: true } : {}),
             ...(trieResult.responseType
@@ -123,17 +121,14 @@ export function createFindMatch<TEnv = any>(
               : {}),
             ...(trieResult.rscFirst ? { rscFirst: true } : {}),
           };
-          return lastFindMatchResult;
+          return cloneMatchResult(lastFindMatchResult);
         }
       }
     }
 
-    // Phase 2: Fall back to existing matching (regex iteration)
     const regexStart = performance.now();
     let result = findRouteMatch(pathname, deps.routesEntries);
 
-    // If we hit a lazy entry that needs evaluation, evaluate and retry.
-    // Cap iterations to prevent infinite loops from pathological nesting.
     const MAX_LAZY_ITERATIONS = 100;
     let iterations = 0;
     while (isLazyEvaluationNeeded(result)) {
@@ -151,8 +146,36 @@ export function createFindMatch<TEnv = any>(
     }
     pushMetric?.("match:regex-fallback", regexStart);
 
+    // The trie is the single source of truth and is built before findMatch in
+    // both dev (handler rebuild) and production (ensureRouterManifest). If the
+    // trie was present yet the regex fallback resolved a real match, the trie
+    // has a gap (e.g. a route shape it cannot represent) and dev/prod could
+    // diverge if the trie were ever absent. Surface it in dev; folded out in
+    // production builds.
+    //
+    // Suppress when the trie DID match (`trieMatched`): that path falls through
+    // to the regex fallback only on the first request to a not-yet-spliced lazy
+    // entry (e.g. a 2+-level nested include whose deeper parent has not been
+    // evaluated). The trie knew the route; runtime lazy discovery simply lagged.
+    // That is the supported lazy-include flow, not a trie gap, so warning on it
+    // is a false positive (it manufactures bug reports and erodes the signal).
+    if (
+      process.env.NODE_ENV !== "production" &&
+      routeTrie &&
+      !trieMatched &&
+      result &&
+      !isLazyEvaluationNeeded(result)
+    ) {
+      console.warn(
+        `[@rangojs/router] Route "${pathname}" resolved via the regex fallback ` +
+          `even though the route trie was present. The trie should be the single ` +
+          `matching source of truth; this indicates a trie gap. Please report this ` +
+          `with your route configuration.`,
+      );
+    }
+
     lastFindMatchPathname = pathname;
     lastFindMatchResult = result;
-    return result;
+    return cloneMatchResult(result);
   };
 }

package/src/router/handler-context.ts

@@ -8,10 +8,23 @@ import type { HandlerContext, InternalHandlerContext } from "../types";
 import { _getRequestContext } from "../server/request-context.js";
 import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
-import { contextGet, contextSet } from "../context-var.js";
+import {
+  contextGet,
+  contextSet,
+  isNonCacheable,
+  type ContextSetOptions,
+} from "../context-var.js";
+import { isInsideCacheScope } from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
+import { substitutePatternParams } from "./substitute-pattern-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
+
+// Mutating Headers methods guarded so they throw inside "use cache" / cache()
+// scope. Module-level constant (read-only, .has() lookups) so it is allocated
+// once at module load instead of per createHandlerContext (per-request) call.
+const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
 
 /**
  * Strip internal _rsc* query params from a URL.
@@ -108,9 +121,9 @@ function createPrerenderPassthroughFn(
     }
     if (!isPassthroughRoute) {
       throw new Error(
-        "ctx.passthrough() is only available on routes declared with " +
-          "{ passthrough: true }. Remove the passthrough() call or add " +
-          "{ passthrough: true } to the Prerender options.",
+        "ctx.passthrough() is only available on routes wrapped with " +
+          "Passthrough(). Remove the passthrough() call or wrap the " +
+          "Prerender definition with Passthrough(prerenderDef, liveHandler).",
       );
     }
     return PRERENDER_PASSTHROUGH;
@@ -152,26 +165,14 @@ export function createReverseFunction(
       );
     }
 
-    let result = pattern;
-
     // Merge current request params as defaults, explicit params override
     const effectiveParams = currentParams
       ? { ...currentParams, ...hrefParams }
       : hrefParams;
 
-    // Substitute params (strip constraint and optional syntax: :param(a|b)? -> value)
-    if (effectiveParams) {
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
-        (_, key) => {
-          const value = effectiveParams[key];
-          if (value === undefined) {
-            throw new Error(`Missing param "${key}" for route "${name}"`);
-          }
-          return encodeURIComponent(value);
-        },
-      );
-    }
+    let result = effectiveParams
+      ? substitutePatternParams(pattern, effectiveParams, name)
+      : pattern;
 
     // Append search params as query string
     if (search) {
@@ -201,7 +202,7 @@ export function createHandlerContext<TEnv>(
   // Get variables from request context - this is the unified context
   // shared between middleware and route handlers
   const requestContext = _getRequestContext();
-  const variables: any = requestContext?.var ?? {};
+  const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
   const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
@@ -213,10 +214,10 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
-  // Guard mutating Headers methods so they throw inside "use cache" functions.
+  // Guard mutating Headers methods so they throw inside "use cache" or cache() scope.
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
-  const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+  // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
   let ctx: InternalHandlerContext<any, TEnv>;
   const guardedHeaders = new Proxy(stubResponse.headers, {
     get(target, prop, receiver) {
@@ -225,6 +226,13 @@ export function createHandlerContext<TEnv>(
         if (MUTATING_HEADERS_METHODS.has(prop as string)) {
           return (...args: any[]) => {
             assertNotInsideCacheExec(ctx, "headers");
+            if (isInsideCacheScope()) {
+              throw new Error(
+                `ctx.headers.${String(prop)}() cannot be called inside a cache() boundary. ` +
+                  `On cache hit the handler is skipped, so this side effect would be lost. ` +
+                  `Move header mutations to a middleware or layout outside the cache() scope.`,
+              );
+            }
             return value.apply(target, args);
           };
         }
@@ -237,21 +245,36 @@ export function createHandlerContext<TEnv>(
   ctx = {
     params,
     build: false,
+    dev: false,
     request,
     searchParams,
     search: searchSchema ? resolvedSearchParams : {},
     pathname,
     url,
-    originalUrl: new URL(request.url),
+    originalUrl: requestContext?.originalUrl ?? new URL(request.url),
     env: bindings,
-    var: variables,
-    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as HandlerContext<
-      any,
-      TEnv
-    >["get"],
-    set: ((keyOrVar: any, value: any) => {
+    waitUntil: requestContext
+      ? requestContext.waitUntil.bind(requestContext)
+      : fireAndForgetWaitUntil,
+    executionContext: requestContext?.executionContext,
+    _variables: variables,
+    get: ((keyOrVar: any) => {
+      // Read-time guard: non-cacheable var inside cache() → throw.
+      // Works for both ContextVar tokens and string keys.
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as HandlerContext<any, TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: ContextSetOptions) => {
       assertNotInsideCacheExec(ctx, "set");
-      contextSet(variables, keyOrVar, value);
+      // Write is dumb: store value + non-cacheable metadata.
+      // Enforcement happens at read time via ctx.get().
+      contextSet(variables, keyOrVar, value, options);
     }) as HandlerContext<any, TEnv>["set"],
     res: stubResponse, // Stub response for setting headers
     headers: guardedHeaders, // Guarded shorthand for res.headers
@@ -297,7 +320,7 @@ export function createHandlerContext<TEnv>(
  *
  * Returns an InternalHandlerContext where params, pathname, url, searchParams,
  * search, reverse, and use(handle) work. Request-time properties
- * (request, env, headers, cookies, var, get, set, res) throw with a clear error.
+ * (request, env, headers, cookies, get, set, res) throw with a clear error.
  */
 export function createPrerenderContext<TEnv>(
   params: Record<string, string>,
@@ -306,6 +329,8 @@ export function createPrerenderContext<TEnv>(
   routeName?: string,
   buildVars?: Record<string, any>,
   isPassthroughRoute?: boolean,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const syntheticUrl = new URL(`http://prerender${pathname}`);
   const variables = buildVars ?? {};
@@ -320,6 +345,7 @@ export function createPrerenderContext<TEnv>(
   return {
     params,
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -329,11 +355,19 @@ export function createPrerenderContext<TEnv>(
     url: syntheticUrl,
     originalUrl: syntheticUrl,
     get env(): TEnv {
-      return throwUnavailable("env");
-    },
-    get var(): any {
-      return throwUnavailable("var");
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available during pre-rendering. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    // Build-time prerender has no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect — these are meant to outlive the live response).
+    // executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
@@ -379,6 +413,8 @@ export function createPrerenderContext<TEnv>(
 export function createStaticContext<TEnv>(
   routeMap: Record<string, string>,
   routeName?: string,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const variables: Record<string, any> = {};
 
@@ -394,6 +430,7 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("params");
     },
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -413,11 +450,18 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("originalUrl");
     },
     get env(): TEnv {
-      return throwUnavailable("env");
-    },
-    get var(): any {
-      return throwUnavailable("var");
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available in Static() handlers. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    // Static() handlers have no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect). executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);