@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/router/error-handling.ts

@@ -1,11 +1,11 @@
 /**
  * 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.
  */
 
-import type { ReactNode } from "react";
+import { createElement, type ReactNode } from "react";
 import type { EntryData } from "../server/context";
 import type {
   ResolvedSegment,
@@ -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,
@@ -251,6 +281,69 @@ export function createNotFoundInfo(
   };
 }
 
+/** Router-level `createRouter({ notFound })` option shape. */
+export type NotFoundComponentOption =
+  | ReactNode
+  | ((props: { pathname: string }) => ReactNode);
+
+/**
+ * Pick the effective notFound fallback: nearest `notFoundBoundary`, else the
+ * router-level `notFound` option, else a plain default.
+ *
+ * The router option is resolved ONLY when no nearer boundary won — it may be a
+ * user render function doing arbitrary work, so computing it eagerly (as three
+ * earlier copies of this policy did) burned a full render on every 404 that a
+ * boundary was going to handle anyway.
+ *
+ * Every 404 origin routes through here — segment resolution
+ * (`segment-resolution/helpers.ts`), loader-thrown `notFound()`
+ * (`loader-resolution.ts`), and the unmatched-route path (`rsc/handler.ts`) —
+ * so the default text and the boundary-wins precedence cannot drift apart.
+ */
+export function resolveNotFoundFallback(
+  boundary: ReactNode | NotFoundBoundaryHandler | null | undefined,
+  notFoundComponent: NotFoundComponentOption | undefined,
+  pathname: string | undefined,
+): ReactNode | NotFoundBoundaryHandler {
+  if (boundary !== null && boundary !== undefined) return boundary;
+  return resolveDefaultNotFound(notFoundComponent, pathname);
+}
+
+/**
+ * The router-level default alone: `createRouter({ notFound })` rendered, or the
+ * plain fallback node. Separate from {@link resolveNotFoundFallback} for the
+ * unmatched-route path, which has no entry chain and therefore no boundary to
+ * consult — it gets a `ReactNode` back rather than a possible handler.
+ */
+export function resolveDefaultNotFound(
+  notFoundComponent: NotFoundComponentOption | undefined,
+  pathname: string | undefined,
+): ReactNode {
+  if (typeof notFoundComponent === "function") {
+    return notFoundComponent({ pathname: pathname ?? "" });
+  }
+  return notFoundComponent ?? createElement("h1", null, "Not Found");
+}
+
+/**
+ * Invoke a notFound fallback that may be a boundary handler or a plain node.
+ *
+ * Callers that cannot propagate a throw (the loader envelope) wrap this in
+ * their own try/catch; it deliberately does not swallow, so a throwing boundary
+ * still surfaces where that is the correct behavior.
+ */
+export function renderNotFoundFallback(
+  fallback: ReactNode | NotFoundBoundaryHandler,
+  notFoundInfo: NotFoundInfo,
+): ReactNode {
+  if (typeof fallback === "function") {
+    return fallback({
+      notFound: notFoundInfo,
+    } satisfies NotFoundBoundaryFallbackProps);
+  }
+  return fallback;
+}
+
 /**
  * Create a notFound segment with the fallback component
  * Renders the fallback with not found info
@@ -261,19 +354,7 @@ 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;
-  }
+  const component: ReactNode = renderNotFoundFallback(fallback, notFoundInfo);
 
   return {
     id: `${entry.shortCode}.notFound`,

package/src/router/find-match.ts

@@ -1,5 +1,8 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouteTrie, getRouterTrie } from "../route-map-builder.js";
+import {
+  getRouterTrie,
+  isRouterTrieAuthoritative,
+} from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -8,39 +11,55 @@ 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;
+  // Returns a Promise only when it had to resolve an async include provider
+  // (`() => import()`); void for eager/precomputed includes, so the per-entry
+  // match loop pays no microtask in the common case.
+  evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void | Promise<void>;
   routerId: string;
 }
 
 /**
  * Create a findMatch function bound to router state.
  * Includes single-entry cache to avoid redundant matching within the same request.
+ *
+ * Async because a lazy include may be backed by an async provider
+ * (`() => import("./routes")`) that must be resolved before its routes can be
+ * matched. The hot path is unaffected: `await` only suspends on the first
+ * request to a not-yet-loaded dynamic include; eager routes resolve in the same
+ * microtask. Every caller already runs inside an async match pipeline.
  */
 export function createFindMatch<TEnv = any>(
   deps: FindMatchDeps<TEnv>,
-): (pathname: string, ms?: MetricsStore) => RouteMatchResult<TEnv> | null {
+): (
+  pathname: string,
+  ms?: MetricsStore,
+) => Promise<RouteMatchResult<TEnv> | null> {
   // Single-entry cache for findMatch to avoid redundant matching within the same request.
   // previewMatch and match both call findMatch with the same pathname — this ensures
   // the route matching work (which may check thousands of routes) only happens once.
   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(
+  return async function findMatch(
     pathname: string,
     ms?: MetricsStore,
-  ): RouteMatchResult<TEnv> | null {
-    // Return cached result if same pathname (avoids double-match per request)
+  ): Promise<RouteMatchResult<TEnv> | null> {
     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 +70,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
@@ -67,11 +86,33 @@ export function createFindMatch<TEnv = any>(
         const entryStart = performance.now();
         let entry: RouteEntry<TEnv> | undefined;
         let fallbackEntry: RouteEntry<TEnv> | undefined;
+        let candidateError: unknown;
+        let candidateFailed = false;
 
         for (const e of deps.routesEntries) {
           if (e.staticPrefix !== trieResult.sp) continue;
           if (!fallbackEntry) fallbackEntry = e;
-          deps.evaluateLazyEntry(e);
+          try {
+            const ev = deps.evaluateLazyEntry(e);
+            if (ev) await ev;
+          } catch (err) {
+            // Multiple async includes can share one collapsed static prefix, so
+            // this loop may evaluate a candidate that is NOT the route's owner.
+            // Remember the failure and keep scanning: if another candidate owns
+            // the route, this sibling's failure is correctly isolated (its
+            // _lazyInflight was cleared, so a later request retries). But if NO
+            // candidate ends up owning it, the failing one WAS the owner — a
+            // real, trie-matched route whose module failed to import — and we
+            // rethrow below as a 5xx rather than silently 404ing (see finding 3:
+            // owner failure must stay loud).
+            candidateError = err;
+            candidateFailed = true;
+            console.error(
+              `[@rangojs/router] include at "${e.staticPrefix}" failed to load: ` +
+                `${(err as Error)?.message ?? String(err)}`,
+            );
+            continue;
+          }
           if (
             e.routes &&
             trieResult.routeKey in (e.routes as Record<string, unknown>)
@@ -81,12 +122,16 @@ 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).
+        // The trie matched this route, so it EXISTS. If no same-prefix candidate
+        // could own it AND one failed to load, the owning module is the one that
+        // threw — surface the module failure as a 5xx, not the misleading 404 a
+        // fallthrough would give.
+        if (!entry && candidateFailed) {
+          throw candidateError;
+        }
+
         if (!entry) entry = fallbackEntry;
 
-        // If entry not found (nested include not yet discovered), evaluate parent
         if (!entry) {
           const parent = deps.routesEntries.find(
             (e) =>
@@ -95,7 +140,8 @@ export function createFindMatch<TEnv = any>(
           );
           if (parent) {
             const lazyStart = performance.now();
-            deps.evaluateLazyEntry(parent);
+            const ev = deps.evaluateLazyEntry(parent);
+            if (ev) await ev;
             pushMetric?.("match:lazy-eval", lazyStart);
           }
           entry = deps.routesEntries.find(
@@ -110,9 +156,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 +167,25 @@ export function createFindMatch<TEnv = any>(
               : {}),
             ...(trieResult.rscFirst ? { rscFirst: true } : {}),
           };
-          return lastFindMatchResult;
+          return cloneMatchResult(lastFindMatchResult);
         }
+      } else if (isRouterTrieAuthoritative(deps.routerId)) {
+        // Authoritative miss (#664): this trie was deserialized from the
+        // COMPLETE build manifest, so trailing-slash redirects are already
+        // trie-native hits and a miss means no route exists. Skip the regex
+        // fallback — the only route-count-proportional match path — and do
+        // not evaluate lazy includes for unmatched (bot-probe) traffic.
+        // Trie hits that need lazy splicing keep the fallback loop below
+        // (trieMatched === true never reaches this branch).
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
       }
     }
 
-    // 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)) {
@@ -146,13 +198,62 @@ export function createFindMatch<TEnv = any>(
         lastFindMatchResult = null;
         return null;
       }
-      deps.evaluateLazyEntry(result.lazyEntry);
+      try {
+        const ev = deps.evaluateLazyEntry(result.lazyEntry);
+        if (ev) await ev;
+      } catch (err) {
+        // If the trie matched this pathname, the route is REAL and this lazy
+        // entry owns (part of) it — a module-load failure is a genuine error, so
+        // propagate it as a 5xx. If the trie did NOT match, this is a
+        // genuinely-unmatched pathname (a typo, a bot probe): its 404 must not be
+        // upgraded to a 500 just because some lazy include — e.g. a failing root
+        // `include("/")` — happened to need evaluating while we probed. Isolate
+        // and fall through to the 404 (finding 4: the two match phases agree —
+        // owner failure is loud, unmatched stays 404).
+        if (trieMatched) throw err;
+        console.error(
+          `[@rangojs/router] include at "${result.lazyEntry.staticPrefix}" ` +
+            `failed to load while resolving unmatched path "${pathname}": ` +
+            `${(err as Error)?.message ?? String(err)}`,
+        );
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
+      }
       result = findRouteMatch(pathname, deps.routesEntries);
     }
     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);
   };
 }