@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

package/src/router/content-negotiation.ts

@@ -0,0 +1,228 @@
+/**
+ * Content Negotiation Utilities
+ *
+ * Pure functions for HTTP Accept header parsing and response type matching.
+ * Used by previewMatch and classifyRequest for content negotiation between
+ * RSC routes and response routes (JSON, text, image, stream, etc.).
+ */
+
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import { loadManifest } from "./manifest.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { RouteSnapshot } from "./route-snapshot.js";
+
+// Response type -> MIME type used for Accept header matching
+export const RESPONSE_TYPE_MIME: Record<string, string> = {
+  json: "application/json",
+  text: "text/plain",
+  xml: "application/xml",
+  html: "text/html",
+  md: "text/markdown",
+};
+
+// Reverse lookup: MIME type -> response type tag (e.g. "text/html" -> "html")
+export const MIME_RESPONSE_TYPE: Record<string, string> = Object.fromEntries(
+  Object.entries(RESPONSE_TYPE_MIME).map(([tag, mime]) => [mime, tag]),
+);
+
+export type NamedRouteEntry =
+  | string
+  | { path: string; search?: Record<string, string> };
+
+export function flattenNamedRoutes(
+  routeNames?: Record<string, NamedRouteEntry>,
+): Record<string, string> {
+  if (!routeNames) return {};
+  const flattened: Record<string, string> = {};
+  for (const [name, entry] of Object.entries(routeNames)) {
+    flattened[name] = typeof entry === "string" ? entry : entry.path;
+  }
+  return flattened;
+}
+
+export interface AcceptEntry {
+  mime: string;
+  q: number;
+  order: number;
+}
+
+/**
+ * Parse an Accept header into a sorted array of MIME entries.
+ * Respects q-values (default 1.0) and uses client order as tiebreaker
+ * when q-values are equal (matching Express/Hono behavior).
+ */
+export function parseAcceptTypes(accept: string): AcceptEntry[] {
+  const entries: AcceptEntry[] = [];
+  const parts = accept.split(",");
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    const segments = part.split(";");
+    const mime = segments[0]!.trim().toLowerCase();
+    if (!mime) continue;
+    let q = 1.0;
+    for (let j = 1; j < segments.length; j++) {
+      const param = segments[j]!.trim();
+      if (param.startsWith("q=")) {
+        q = Math.max(0, Math.min(1, Number(param.slice(2)) || 0));
+      }
+    }
+    entries.push({ mime, q, order: i });
+  }
+  // Sort: highest q first, then lowest client order first (stable)
+  entries.sort((a, b) => b.q - a.q || a.order - b.order);
+  return entries;
+}
+
+// Sentinel response type for RSC routes in negotiation candidates
+export const RSC_RESPONSE_TYPE = "__rsc__";
+
+/**
+ * Pick the best negotiate variant by walking the client's sorted Accept list.
+ * For each accepted MIME type (in q-value/order priority), check if any
+ * candidate serves that type. Wildcards match the first candidate.
+ * Falls back to the first candidate if nothing matches.
+ */
+export function pickNegotiateVariant(
+  acceptEntries: AcceptEntry[],
+  candidates: Array<{ routeKey: string; responseType: string }>,
+): { routeKey: string; responseType: string } {
+  // Build a MIME -> candidate lookup for O(1) matching
+  const byCandidateMime = new Map<
+    string,
+    { routeKey: string; responseType: string }
+  >();
+  for (const c of candidates) {
+    const mime =
+      c.responseType === RSC_RESPONSE_TYPE
+        ? "text/html"
+        : RESPONSE_TYPE_MIME[c.responseType];
+    if (mime && !byCandidateMime.has(mime)) {
+      byCandidateMime.set(mime, c);
+    }
+  }
+
+  for (const entry of acceptEntries) {
+    if (entry.q === 0) continue;
+    // Wildcard matches first candidate
+    if (entry.mime === "*/*") return candidates[0]!;
+    // Type wildcard (e.g. "text/*") -- match first candidate with that type
+    if (entry.mime.endsWith("/*")) {
+      const typePrefix = entry.mime.slice(0, entry.mime.indexOf("/"));
+      for (const [mime, candidate] of byCandidateMime) {
+        if (mime.startsWith(typePrefix + "/")) return candidate;
+      }
+      continue;
+    }
+    const match = byCandidateMime.get(entry.mime);
+    if (match) return match;
+  }
+  // No match -- use first candidate as default
+  return candidates[0]!;
+}
+
+/**
+ * Result of content negotiation for a route with negotiate variants.
+ */
+export interface NegotiationResult {
+  /** The winning response type */
+  responseType: string;
+  /** Handler function for the winning variant */
+  handler: Function;
+  /** Manifest entry for the winning variant (may differ from primary) */
+  manifestEntry: EntryData;
+  /** Route middleware for the winning variant */
+  routeMiddleware: CollectedMiddleware[];
+  /** True when negotiation selected a variant; false for a plain response route. */
+  negotiated: boolean;
+}
+
+/**
+ * Perform content negotiation for a route with negotiate variants.
+ *
+ * Returns a NegotiationResult when a response route wins negotiation.
+ * Returns null when RSC wins or no negotiation is needed.
+ *
+ * Shared by previewMatch and classifyRequest to avoid duplicating
+ * the candidate-building and variant-loading logic.
+ */
+export async function negotiateRoute(
+  request: Request,
+  pathname: string,
+  snapshot: RouteSnapshot,
+): Promise<NegotiationResult | null> {
+  const { matched, manifestEntry, routeMiddleware, responseType } = snapshot;
+  if (!matched.negotiateVariants || matched.negotiateVariants.length === 0) {
+    // No variants: a plain response route still yields a result (negotiated:false)
+    // so callers don't re-derive it; RSC routes (no responseType/handler) -> null.
+    const handler =
+      manifestEntry.type === "route" ? manifestEntry.handler : undefined;
+    if (responseType && handler) {
+      return {
+        responseType,
+        handler: handler as Function,
+        manifestEntry,
+        routeMiddleware,
+        negotiated: false,
+      };
+    }
+    return null;
+  }
+
+  const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
+
+  // Build candidate list preserving definition order.
+  const variants = matched.negotiateVariants;
+  let candidates: Array<{ routeKey: string; responseType: string }>;
+  if (responseType) {
+    candidates = [...variants, { routeKey: matched.routeKey, responseType }];
+  } else {
+    const rscCandidate = {
+      routeKey: matched.routeKey,
+      responseType: RSC_RESPONSE_TYPE,
+    };
+    candidates = matched.rscFirst
+      ? [rscCandidate, ...variants]
+      : [...variants, rscCandidate];
+  }
+
+  const variant = pickNegotiateVariant(acceptEntries, candidates);
+
+  // RSC won negotiation
+  if (variant.responseType === RSC_RESPONSE_TYPE) {
+    return null;
+  }
+
+  // Primary response-type won — use existing manifest entry and middleware
+  if (responseType && variant.routeKey === matched.routeKey) {
+    return {
+      responseType,
+      handler: manifestEntry.handler as Function,
+      manifestEntry,
+      routeMiddleware,
+      negotiated: true,
+    };
+  }
+
+  // Different variant won — load its manifest entry
+  const negotiateEntry = await loadManifest(
+    matched.entry,
+    variant.routeKey,
+    pathname,
+    undefined,
+    false,
+  );
+  const variantMiddleware = collectRouteMiddleware(
+    traverseBack(negotiateEntry),
+    matched.params,
+  );
+  return {
+    responseType: variant.responseType,
+    handler: negotiateEntry.handler as Function,
+    manifestEntry: negotiateEntry,
+    routeMiddleware: variantMiddleware,
+    negotiated: true,
+  };
+}

package/src/router/debug-manifest.ts

@@ -0,0 +1,72 @@
+import { type EntryData, getContext } from "../server/context";
+import { serializeManifest, type SerializedManifest } from "../debug.js";
+import { createRouteHelpers } from "../route-definition.js";
+import MapRootLayout from "../server/root-layout.js";
+import type { RouteEntry, TrailingSlashMode } from "../types";
+
+/**
+ * Build a serialized manifest from all route entries for debug inspection.
+ * Used by the `debugManifest()` method on the router instance.
+ */
+export async function buildDebugManifest<TEnv = any>(
+  routesEntries: RouteEntry<TEnv>[],
+): Promise<SerializedManifest> {
+  const manifest = new Map<string, EntryData>();
+
+  for (const entry of routesEntries) {
+    const Store = {
+      manifest,
+      namespace: `debug.M${entry.mountIndex}`,
+      parent: null as EntryData | null,
+      counters: {} as Record<string, number>,
+      mountIndex: entry.mountIndex,
+      patterns: new Map<string, string>(),
+      trailingSlash: new Map<string, TrailingSlashMode>(),
+    };
+
+    await getContext().runWithStore(
+      Store,
+      `debug.M${entry.mountIndex}`,
+      null,
+      async () => {
+        const helpers = createRouteHelpers();
+
+        // Wrap handler execution in root layout (same as loadManifest)
+        let promiseResult: Promise<any> | null = null;
+        helpers.layout(MapRootLayout, () => {
+          const result = entry.handler();
+          if (result instanceof Promise) {
+            promiseResult = result;
+            return [];
+          }
+          return result;
+        });
+
+        if (promiseResult !== null) {
+          const load = await (promiseResult as Promise<any>);
+          if (load && typeof load === "object" && "default" in load) {
+            // Promise<{ default: fn }> — e.g. dynamic import
+            if (typeof load.default !== "function") {
+              throw new Error(
+                `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
+                  `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
+              );
+            }
+            load.default(helpers);
+          } else if (typeof load === "function") {
+            // Promise<fn>
+            load(helpers);
+          } else {
+            // Reject unsupported async handler results (same policy as manifest.ts)
+            throw new Error(
+              `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+                `Lazy route handlers must resolve to a function or { default: fn }.`,
+            );
+          }
+        }
+      },
+    );
+  }
+
+  return serializeManifest(manifest);
+}

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.
  */
 
@@ -60,7 +60,7 @@ export function invokeOnError<TEnv = any>(
   error: unknown,
   phase: ErrorPhase,
   context: InvokeOnErrorContext<TEnv>,
-  logPrefix: string = "Router"
+  logPrefix: string = "Router",
 ): void {
   if (!onError) return;
 
@@ -74,8 +74,8 @@ export function invokeOnError<TEnv = any>(
     phase,
     request: context.request,
     url: context.url,
-    pathname: context.url.pathname,
-    method: context.request.method,
+    pathname: context.url?.pathname,
+    method: context.request?.method,
     routeKey: context.routeKey,
     params: context.params,
     segmentId: context.segmentId,
@@ -112,7 +112,7 @@ export function invokeOnError<TEnv = any>(
  */
 export function findNearestErrorBoundary(
   entry: EntryData | null,
-  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler,
 ): ReactNode | ErrorBoundaryHandler | null {
   let current: EntryData | null = entry;
 
@@ -148,7 +148,7 @@ export function findNearestErrorBoundary(
  */
 export function findNearestNotFoundBoundary(
   entry: EntryData | null,
-  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler,
 ): ReactNode | NotFoundBoundaryHandler | null {
   let current: EntryData | null = entry;
 
@@ -172,7 +172,7 @@ export function findNearestNotFoundBoundary(
 export function createErrorInfo(
   error: unknown,
   segmentId: string,
-  segmentType: ErrorInfo["segmentType"]
+  segmentType: ErrorInfo["segmentType"],
 ): ErrorInfo {
   const isDev = process.env.NODE_ENV !== "production";
 
@@ -205,7 +205,7 @@ export function createErrorSegment(
   errorInfo: ErrorInfo,
   fallback: ReactNode | ErrorBoundaryHandler,
   entry: EntryData,
-  params: Record<string, string>
+  params: Record<string, string>,
 ): ResolvedSegment {
   // Determine the component to render
   let component: ReactNode;
@@ -241,7 +241,7 @@ export function createNotFoundInfo(
   error: { message: string },
   segmentId: string,
   segmentType: NotFoundInfo["segmentType"],
-  pathname?: string
+  pathname?: string,
 ): NotFoundInfo {
   return {
     message: error.message,
@@ -259,7 +259,7 @@ export function createNotFoundSegment(
   notFoundInfo: NotFoundInfo,
   fallback: ReactNode | NotFoundBoundaryHandler,
   entry: EntryData,
-  params: Record<string, string>
+  params: Record<string, string>,
 ): ResolvedSegment {
   // Determine the component to render
   let component: ReactNode;

package/src/router/find-match.ts

@@ -0,0 +1,208 @@
+import { tryTrieMatch } from "./trie-matching.js";
+import { getRouterTrie } from "../route-map-builder.js";
+import {
+  findMatch as findRouteMatch,
+  isLazyEvaluationNeeded,
+  type RouteMatchResult,
+} from "./pattern-matching.js";
+import type { MetricsStore } from "../server/context";
+import type { RouteEntry } from "../types";
+
+// Return a shallow copy with an independent `params` object. The single-entry
+// cache below is module-lifetime and keyed only on pathname, so the same result
+// object is handed to every same-pathname request in the isolate. ctx.params
+// aliases this `params` (see request-context), so without an own copy a handler
+// that mutates ctx.params would corrupt the cached entry for later requests.
+// `entry` and the flags are intentionally shared by reference: they are
+// read-only, and entry identity is compared in match-api (prevMatch.entry).
+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;
+  routerId: string;
+}
+
+/**
+ * Create a findMatch function bound to router state.
+ * Includes single-entry cache to avoid redundant matching within the same request.
+ */
+export function createFindMatch<TEnv = any>(
+  deps: FindMatchDeps<TEnv>,
+): (pathname: string, ms?: MetricsStore) => 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(
+    pathname: string,
+    ms?: MetricsStore,
+  ): RouteMatchResult<TEnv> | null {
+    // Return cached result if same pathname (avoids double-match per request).
+    // Clone so a caller mutating ctx.params cannot corrupt the shared cache.
+    if (lastFindMatchPathname === pathname) {
+      return cloneMatchResult(lastFindMatchResult);
+    }
+
+    // Helper to push sub-metrics
+    const pushMetric = ms
+      ? (label: string, start: number) => {
+          ms.metrics.push({
+            label,
+            duration: performance.now() - start,
+            startTime: start - ms.requestStart,
+          });
+        }
+      : undefined;
+
+    // Phase 1: Try trie match (O(path_length))
+    // Only use the per-router trie. The global trie merges routes from ALL
+    // routers and must not be used — in multi-router setups (host routing)
+    // overlapping paths like "/" would match the wrong app's route.
+    const routeTrie = getRouterTrie(deps.routerId);
+    // Whether the trie produced a match for this pathname (independent of
+    // whether the owning RouteEntry was resolvable yet). Used to suppress the
+    // R3 dev warning below: if the trie DID match but we fell through to the
+    // regex fallback only because a lazy entry was not spliced in yet, that is
+    // not a trie gap.
+    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
+        // each candidate and pick the one whose routes include the matched key.
+        const entryStart = performance.now();
+        let entry: RouteEntry<TEnv> | undefined;
+        let fallbackEntry: RouteEntry<TEnv> | undefined;
+
+        for (const e of deps.routesEntries) {
+          if (e.staticPrefix !== trieResult.sp) continue;
+          if (!fallbackEntry) fallbackEntry = e;
+          deps.evaluateLazyEntry(e);
+          if (
+            e.routes &&
+            trieResult.routeKey in (e.routes as Record<string, unknown>)
+          ) {
+            entry = e;
+            break;
+          }
+        }
+
+        // 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) =>
+              trieResult.sp.startsWith(e.staticPrefix) &&
+              e.staticPrefix !== trieResult.sp,
+          );
+          if (parent) {
+            const lazyStart = performance.now();
+            deps.evaluateLazyEntry(parent);
+            pushMetric?.("match:lazy-eval", lazyStart);
+          }
+          entry = deps.routesEntries.find(
+            (e) => e.staticPrefix === trieResult.sp,
+          );
+        }
+        pushMetric?.("match:entry-resolve", entryStart);
+
+        if (entry) {
+          lastFindMatchPathname = pathname;
+          lastFindMatchResult = {
+            entry,
+            routeKey: trieResult.routeKey,
+            params: trieResult.params,
+            optionalParams: new Set(trieResult.optionalParams || []),
+            redirectTo: trieResult.redirectTo,
+            ...(trieResult.pr ? { pr: true } : {}),
+            ...(trieResult.pt ? { pt: true } : {}),
+            ...(trieResult.responseType
+              ? { responseType: trieResult.responseType }
+              : {}),
+            ...(trieResult.negotiateVariants
+              ? { negotiateVariants: trieResult.negotiateVariants }
+              : {}),
+            ...(trieResult.rscFirst ? { rscFirst: true } : {}),
+          };
+          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)) {
+      if (++iterations > MAX_LAZY_ITERATIONS) {
+        console.error(
+          `[@rangojs/router] Exceeded ${MAX_LAZY_ITERATIONS} lazy evaluation iterations ` +
+            `for pathname "${pathname}". This likely indicates circular lazy includes.`,
+        );
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
+      }
+      deps.evaluateLazyEntry(result.lazyEntry);
+      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 cloneMatchResult(result);
+  };
+}