@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.135c6902

package/src/router/logging.ts

@@ -1,10 +1,48 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
+// -- Revalidation trace types --
+
+export interface RevalidationTraceEntry {
+  segmentId: string;
+  segmentType: string;
+  belongsToRoute: boolean;
+  source:
+    | "segment-resolution"
+    | "cache-hit"
+    | "loader"
+    | "parallel"
+    | "orphan-layout"
+    | "route-handler"
+    | "layout-handler"
+    | "intercept-loader";
+  defaultShouldRevalidate: boolean;
+  finalShouldRevalidate: boolean;
+  reason: string;
+  customRevalidators?: number;
+}
+
+export interface RevalidationTraceMeta {
+  method: string;
+  prevUrl: string;
+  nextUrl: string;
+  routeKey: string;
+  isAction: boolean;
+  stale?: boolean;
+}
+
+export interface RevalidationTrace {
+  meta: RevalidationTraceMeta;
+  entries: RevalidationTraceEntry[];
+}
+
+// -- Log context --
+
 interface RouterLogContext {
   requestId: string;
   transactionId: string;
   depth: number;
+  revalidationTrace?: RevalidationTrace;
 }
 
 interface RouterLogOptions {
@@ -36,7 +74,7 @@ function getHeaderRequestId(request: Request): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
-function getOrCreateRequestId(request: Request): string {
+export function getOrCreateRequestId(request: Request): string {
   const existing = requestIds.get(request);
   if (existing) return existing;
 
@@ -74,9 +112,15 @@ export function runWithRouterLogContext<T>(
   );
 }
 
-export function withRouterLogScope<T>(label: string, fn: () => Promise<T>): Promise<T>;
+export function withRouterLogScope<T>(
+  label: string,
+  fn: () => Promise<T>,
+): Promise<T>;
 export function withRouterLogScope<T>(label: string, fn: () => T): T;
-export function withRouterLogScope<T>(label: string, fn: () => Promise<T> | T): Promise<T> | T {
+export function withRouterLogScope<T>(
+  label: string,
+  fn: () => Promise<T> | T,
+): Promise<T> | T {
   const ctx = routerLogContext.getStore();
   if (!INTERNAL_RANGO_DEBUG || !ctx) {
     return fn();
@@ -88,9 +132,16 @@ export function withRouterLogScope<T>(label: string, fn: () => Promise<T> | T):
     try {
       const result = fn();
       if (result && typeof (result as Promise<T>).then === "function") {
-        return (result as Promise<T>).finally(() => {
-          debugLog(label, "end");
-        });
+        return (result as Promise<T>).then(
+          (value) => {
+            debugLog(label, "end");
+            return value;
+          },
+          (error) => {
+            debugLog(label, "error", { error: String(error) });
+            throw error;
+          },
+        );
       }
       debugLog(label, "end");
       return result;
@@ -143,3 +194,58 @@ export function debugWarn(
 
   console.warn(`${prefix} ${message}`);
 }
+
+// -- Revalidation trace helpers --
+
+export function isTraceActive(): boolean {
+  if (!INTERNAL_RANGO_DEBUG) return false;
+  const ctx = routerLogContext.getStore();
+  return !!ctx?.revalidationTrace;
+}
+
+export function startRevalidationTrace(meta: RevalidationTraceMeta): void {
+  const ctx = routerLogContext.getStore();
+  if (!ctx || !INTERNAL_RANGO_DEBUG) return;
+  ctx.revalidationTrace = { meta, entries: [] };
+}
+
+export function pushRevalidationTraceEntry(
+  entry: RevalidationTraceEntry,
+): void {
+  const ctx = routerLogContext.getStore();
+  if (!ctx?.revalidationTrace) return;
+  ctx.revalidationTrace.entries.push(entry);
+}
+
+export function flushRevalidationTrace(): RevalidationTrace | null {
+  const ctx = routerLogContext.getStore();
+  if (!ctx?.revalidationTrace) return null;
+  const trace = ctx.revalidationTrace;
+  ctx.revalidationTrace = undefined;
+
+  if (trace.entries.length === 0) return trace;
+
+  const revalidated = trace.entries.filter((e) => e.finalShouldRevalidate);
+  const skipped = trace.entries.filter((e) => !e.finalShouldRevalidate);
+
+  debugLog("revalidation-trace", "flush", {
+    method: trace.meta.method,
+    routeKey: trace.meta.routeKey,
+    isAction: trace.meta.isAction,
+    stale: trace.meta.stale,
+    prevUrl: trace.meta.prevUrl,
+    nextUrl: trace.meta.nextUrl,
+    total: trace.entries.length,
+    revalidated: revalidated.length,
+    skipped: skipped.length,
+    entries: trace.entries.map((e) => ({
+      segmentId: e.segmentId,
+      type: e.segmentType,
+      source: e.source,
+      revalidate: e.finalShouldRevalidate,
+      reason: e.reason,
+    })),
+  });
+
+  return trace;
+}

package/src/router/manifest.ts

@@ -6,7 +6,13 @@
 
 import { invariant, RouteNotFoundError } from "../errors";
 import { createRouteHelpers } from "../route-definition";
-import { getContext, runWithPrefixes, type EntryData, type MetricsStore } from "../server/context";
+import {
+  getContext,
+  runWithPrefixes,
+  getIsolatedLazyParent,
+  type EntryData,
+  type MetricsStore,
+} from "../server/context";
 import MapRootLayout from "../server/root-layout";
 import type { RouteEntry } from "../types";
 import type { UrlPatterns } from "../urls";
@@ -60,7 +66,9 @@ export async function loadManifest(
   const mountIndex = entry.mountIndex;
 
   // Check module-level cache (persists across requests within same isolate)
-  const cacheKey = `${VERSION}:${mountIndex ?? ''}:${routeKey}:${isSSR ? 1 : 0}`;
+  // Include routerId so multi-router setups (host routing) don't share cached
+  // EntryData across routers with overlapping mountIndex + routeKey combinations.
+  const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
   const cached = manifestModuleCache.get(cacheKey);
   if (cached) {
     const cacheStart = performance.now();
@@ -100,14 +108,18 @@ export async function loadManifest(
 
   try {
     // Include mountIndex in namespace to ensure unique cache keys per mount
-    const namespaceWithMount = mountIndex !== undefined
-      ? `#router.M${mountIndex}`
-      : "#router";
+    const namespaceWithMount =
+      mountIndex !== undefined ? `#router.M${mountIndex}` : "#router";
 
     // For lazy entries, use the captured parent from include() context
     // This ensures routes are registered under the correct layout hierarchy
-    const lazyContext = entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
-    const parentForContext = lazyContext?.parent as EntryData | null ?? Store.parent;
+    const lazyContext =
+      entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
+    const parentForContext = lazyContext
+      ? getIsolatedLazyParent(
+          (lazyContext.parent as EntryData | null) ?? Store.parent,
+        )
+      : Store.parent;
 
     // For lazy entries, merge captured counters from include() so the
     // handler's entries get shortCode indices after sibling entries that
@@ -121,6 +133,22 @@ export async function loadManifest(
       }
     }
 
+    // Propagate cache profiles for DSL-time cache("profileName") resolution.
+    // Non-lazy entries carry profiles directly; lazy entries carry them
+    // in the captured lazyContext from include() time.
+    const entryProfiles =
+      entry.cacheProfiles ?? (lazyContext as any)?.cacheProfiles;
+    if (entryProfiles) {
+      Store.cacheProfiles = entryProfiles;
+    }
+
+    // Propagate rootScoped from lazyContext so that routes inside
+    // nested { name: "sub" } under { name: "" } keep inherited root scope
+    // when the manifest is rebuilt on each request.
+    if (lazyContext && (lazyContext as any).rootScoped !== undefined) {
+      Store.rootScoped = (lazyContext as any).rootScoped;
+    }
+
     const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(
       Store,
@@ -142,10 +170,8 @@ export async function loadManifest(
           const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
 
           if (fullPrefix || lazyContext?.namePrefix) {
-            return runWithPrefixes(
-              fullPrefix,
-              lazyContext?.namePrefix,
-              () => lazyPatterns.handler()
+            return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () =>
+              lazyPatterns.handler(),
             );
           }
           return lazyPatterns.handler();
@@ -174,27 +200,40 @@ export async function loadManifest(
             "default" in load
           ) {
             // Promise<{ default: () => Array }> - e.g., dynamic import
-            // Lazy-loaded handlers may need helpers (passed as optional arg)
+            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.`,
+              );
+            }
             return (load.default as (h?: any) => any)(helpers);
           }
           if (typeof load === "function") {
             // Promise<() => Array>
             return (load as (h?: any) => any)(helpers);
           }
-          // Promise<Array> - direct array from async handler
-          return load;
+          // Reject unsupported async handler results. Supported shapes are:
+          //   Promise<{ default: fn }> — dynamic import
+          //   Promise<fn> — lazy function
+          // Direct Promise<Array> is not supported; use a function wrapper.
+          throw new Error(
+            `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+              `Lazy route handlers must resolve to a function or { default: fn }, ` +
+              `not a direct array. Wrap your handler: () => import('./urls') or ` +
+              `() => Promise.resolve((h) => [...])`,
+          );
         }
 
         // Inline handler - routes were registered with correct parent inside layout
         return [wrappedItems].flat(3);
-      }
+      },
     );
     pushMetric?.("manifest:handler-exec", handlerExecStart);
 
     const validationStart = performance.now();
     invariant(
       useItems && useItems.length > 0,
-      "Did not receive any handler from router.map()"
+      "Did not receive any handler from router.map()",
     );
     // For non-lazy entries the root handler is wrapped in MapRootLayout,
     // so the result always contains a layout item.  Lazy entries run the
@@ -203,13 +242,13 @@ export async function loadManifest(
     if (!lazyContext) {
       invariant(
         useItems.some((item: { type: string }) => item.type === "layout"),
-        "Top-level handler must be a layout"
+        "Top-level handler must be a layout",
       );
     }
 
     invariant(
       Store.manifest.has(routeKey),
-      `Route must be registered for ${routeKey}`
+      `Route must be registered for ${routeKey}`,
     );
     pushMetric?.("manifest:validation", validationStart);
 
@@ -228,7 +267,7 @@ export async function loadManifest(
             routeKey,
           },
         },
-      }
+      },
     );
   }
 }

package/src/router/match-api.ts

@@ -6,15 +6,16 @@
  */
 
 import { CacheScope, createCacheScope } from "../cache/cache-scope.js";
-import {
-  RouteNotFoundError,
-} from "../errors";
+import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
   createErrorSegment,
   findNearestErrorBoundary as findErrorBoundary,
 } from "./error-handling.js";
-import { createHandlerContext } from "./handler-context.js";
+import {
+  createHandlerContext,
+  stripInternalParams,
+} from "./handler-context.js";
 import { setupLoaderAccess } from "./loader-resolution.js";
 import { loadManifest, clearManifestCache } from "./manifest.js";
 import { collectRouteMiddleware } from "./middleware.js";
@@ -25,21 +26,16 @@ import {
   LoaderEntry,
   getContext,
   InterceptSelectorContext,
-  type MetricsStore,
 } from "../server/context";
-import type {
-  ErrorBoundaryHandler,
-  ErrorInfo,
-  HandlerContext,
-  MatchResult,
-  ResolvedSegment,
-} from "../types";
+import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
 import type { ReactNode } from "react";
-import type { MatchContext, ActionContext as MatchActionContext } from "./match-context.js";
+import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.js";
-import type { InterceptEntry } from "../server/context";
-import type { RouteMatchResult } from "./pattern-matching.js";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  getRequestContext,
+  setRequestContextPrevRouteKey,
+} from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 import { debugLog, debugWarn } from "./logging.js";
 
 /**
@@ -95,22 +91,32 @@ export async function createMatchContextForFull<TEnv>(
     });
   }
 
+  if (
+    manifestEntry.type === "route" &&
+    manifestEntry.prerenderDef?.options?.passthrough === true
+  ) {
+    matched.pt = true;
+  }
+
   const routeMiddleware = collectRouteMiddleware(
     traverseBack(manifestEntry),
     matched.params,
   );
 
-  const bindings = (env as any)?.Bindings ?? env;
+  // Clean URL without internal _rsc* params for userland access
+  const cleanUrl = stripInternalParams(url);
 
   const handlerContext = createHandlerContext(
     matched.params,
     request,
-    url.searchParams,
+    cleanUrl.searchParams,
     pathname,
-    url,
-    bindings,
+    cleanUrl,
+    env,
     deps.getRouteMap(),
     matched.routeKey,
+    matched.responseType,
+    matched.pt === true,
   );
 
   const loaderPromises = new Map<string, Promise<any>>();
@@ -138,14 +144,13 @@ export async function createMatchContextForFull<TEnv>(
 
   return {
     request,
-    url,
+    url: cleanUrl,
     pathname,
     env,
-    bindings,
     clientSegmentIds: [],
     clientSegmentSet: new Set(),
     stale: false,
-    prevUrl: url,
+    prevUrl: cleanUrl,
     prevParams: {},
     prevMatch: null,
     matched,
@@ -162,12 +167,16 @@ export async function createMatchContextForFull<TEnv>(
     Store,
     interceptContextMatch: null,
     interceptSelectorContext: {
-      from: url,
-      to: url,
+      from: cleanUrl,
+      to: cleanUrl,
       params: matched.params,
       request,
       env,
       segments: { path: [], ids: [] },
+      toRouteName:
+        matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
+          ? matched.routeKey
+          : undefined,
     },
     isSameRouteNavigation: false,
     interceptResult: null,
@@ -193,7 +202,6 @@ export async function createMatchContextForPartial<TEnv>(
   const url = new URL(request.url);
   const pathname = url.pathname;
 
-  const requestStartTime = performance.now();
   const metricsStore = deps.getMetricsStore();
 
   const clientSegmentIds =
@@ -215,10 +223,21 @@ export async function createMatchContextForPartial<TEnv>(
     return null;
   }
 
-  const prevUrl = new URL(previousUrl, url.origin);
-  const interceptContextUrl = interceptSourceUrl
-    ? new URL(interceptSourceUrl, url.origin)
-    : prevUrl;
+  let prevUrl: URL;
+  try {
+    prevUrl = new URL(previousUrl, url.origin);
+  } catch {
+    return null;
+  }
+
+  let interceptContextUrl: URL;
+  try {
+    interceptContextUrl = interceptSourceUrl
+      ? new URL(interceptSourceUrl, url.origin)
+      : prevUrl;
+  } catch {
+    interceptContextUrl = prevUrl;
+  }
 
   const routeMatchStart = metricsStore ? performance.now() : 0;
   const prevMatch = deps.findMatch(prevUrl.pathname);
@@ -270,21 +289,32 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
+  if (
+    manifestEntry.type === "route" &&
+    manifestEntry.prerenderDef?.options?.passthrough === true
+  ) {
+    matched.pt = true;
+  }
+
   const routeMiddleware = collectRouteMiddleware(
     traverseBack(manifestEntry),
     matched.params,
   );
 
-  const bindings = (env as any)?.Bindings ?? env;
+  // Clean URL without internal _rsc* params for userland access
+  const cleanUrl = stripInternalParams(url);
+
   const handlerContext = createHandlerContext(
     matched.params,
     request,
-    url.searchParams,
+    cleanUrl.searchParams,
     pathname,
-    url,
-    bindings,
+    cleanUrl,
+    env,
     deps.getRouteMap(),
     matched.routeKey,
+    matched.responseType,
+    matched.pt === true,
   );
 
   const clientSegmentSet = new Set(clientSegmentIds);
@@ -308,8 +338,7 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   const isSameRouteNavigation = !!(
-    interceptContextMatch &&
-    interceptContextMatch.routeKey === matched.routeKey
+    interceptContextMatch && interceptContextMatch.routeKey === matched.routeKey
   );
 
   if (interceptSourceUrl) {
@@ -331,16 +360,35 @@ export async function createMatchContextForPartial<TEnv>(
     if (/D\d+\./.test(id)) return false;
     return true;
   });
+  const effectiveFromUrl = interceptSourceUrl ? interceptContextUrl : prevUrl;
+  const effectiveFromMatch = interceptSourceUrl
+    ? interceptContextMatch
+    : prevMatch;
+
+  // Store previous route key on the request context for revalidation
+  // fromRouteName. Uses effectiveFromMatch so intercept-source navigations
+  // see the intercept origin route, not the plain previous URL route.
+  setRequestContextPrevRouteKey(effectiveFromMatch?.routeKey);
+
   const interceptSelectorContext: InterceptSelectorContext = {
-    from: prevUrl,
-    to: url,
+    from: effectiveFromUrl,
+    to: cleanUrl,
     params: matched.params,
     request,
     env,
     segments: {
-      path: prevUrl.pathname.split("/").filter(Boolean),
+      path: effectiveFromUrl.pathname.split("/").filter(Boolean),
       ids: filteredSegmentIds,
     },
+    fromRouteName:
+      effectiveFromMatch?.routeKey &&
+      !isAutoGeneratedRouteName(effectiveFromMatch.routeKey)
+        ? effectiveFromMatch.routeKey
+        : undefined,
+    toRouteName:
+      matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
+        ? matched.routeKey
+        : undefined,
   };
   const isAction = !!actionContext;
 
@@ -389,10 +437,9 @@ export async function createMatchContextForPartial<TEnv>(
 
   return {
     request,
-    url,
+    url: cleanUrl,
     pathname,
     env,
-    bindings,
     clientSegmentIds,
     clientSegmentSet,
     stale,
@@ -544,10 +591,7 @@ export async function matchError<TEnv>(
 
   const reqCtx = getRequestContext();
   if (reqCtx) {
-    reqCtx.res = new Response(null, {
-      status: 500,
-      headers: reqCtx.res.headers,
-    });
+    reqCtx._setStatus(500);
   }
 
   const effectiveFallback = fallback || DefaultErrorFallback;
@@ -574,46 +618,3 @@ export async function matchError<TEnv>(
     params: matched.params,
   };
 }
-
-/**
- * Preview match - returns route middleware without segment resolution.
- */
-export async function previewMatch<TEnv>(
-  request: Request,
-  context: TEnv,
-  deps: MatchApiDeps<TEnv>,
-): Promise<{
-  routeMiddleware?: Array<{
-    handler: import("./middleware.js").MiddlewareFn;
-    params: Record<string, string>;
-  }>;
-} | null> {
-  const url = new URL(request.url);
-  const pathname = url.pathname;
-
-  const matched = deps.findMatch(pathname);
-  if (!matched) {
-    return null;
-  }
-
-  if (matched.redirectTo) {
-    return { routeMiddleware: undefined };
-  }
-
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    undefined,
-    false,
-  );
-
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
-  return {
-    routeMiddleware: routeMiddleware.length > 0 ? routeMiddleware : undefined,
-  };
-}

package/src/router/match-context.ts

@@ -45,7 +45,7 @@
  *   - request, url, pathname: The incoming HTTP request
  *
  * Environment:
- *   - env, bindings: Server environment (Cloudflare bindings, etc.)
+ *   - env: Server environment (Cloudflare bindings, etc.)
  *
  * Client State (from RSC request headers):
  *   - clientSegmentIds: Segments the client currently has
@@ -140,7 +140,6 @@ export interface MatchContext<TEnv = any> {
 
   // Environment
   env: TEnv;
-  bindings: TEnv;
 
   // Client state
   clientSegmentIds: string[];
@@ -211,6 +210,9 @@ export interface MatchPipelineState {
   // Whether cache should be revalidated (SWR)
   shouldRevalidate?: boolean;
 
+  // Source of cache hit ("runtime" or "prerender")
+  cacheSource?: "runtime" | "prerender";
+
   // Resolved segments from pipeline
   segments: ResolvedSegment[];
   matchedIds: string[];