@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/router/logging.ts

@@ -1,10 +1,45 @@
 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";
+  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 {
@@ -94,9 +129,16 @@ export function withRouterLogScope<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;
@@ -149,3 +191,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

@@ -127,6 +127,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,
@@ -178,15 +194,28 @@ 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

package/src/router/match-api.ts

@@ -31,7 +31,11 @@ import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
 import type { ReactNode } from "react";
 import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.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";
 
 /**
@@ -87,6 +91,13 @@ export async function createMatchContextForFull<TEnv>(
     });
   }
 
+  if (
+    manifestEntry.type === "route" &&
+    manifestEntry.prerenderDef?.options?.passthrough === true
+  ) {
+    matched.pt = true;
+  }
+
   const routeMiddleware = collectRouteMiddleware(
     traverseBack(manifestEntry),
     matched.params,
@@ -105,6 +116,7 @@ export async function createMatchContextForFull<TEnv>(
     deps.getRouteMap(),
     matched.routeKey,
     matched.responseType,
+    matched.pt === true,
   );
 
   const loaderPromises = new Map<string, Promise<any>>();
@@ -161,6 +173,10 @@ export async function createMatchContextForFull<TEnv>(
       request,
       env,
       segments: { path: [], ids: [] },
+      toRouteName:
+        matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
+          ? matched.routeKey
+          : undefined,
     },
     isSameRouteNavigation: false,
     interceptResult: null,
@@ -207,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);
@@ -262,6 +289,13 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
+  if (
+    manifestEntry.type === "route" &&
+    manifestEntry.prerenderDef?.options?.passthrough === true
+  ) {
+    matched.pt = true;
+  }
+
   const routeMiddleware = collectRouteMiddleware(
     traverseBack(manifestEntry),
     matched.params,
@@ -280,6 +314,7 @@ export async function createMatchContextForPartial<TEnv>(
     deps.getRouteMap(),
     matched.routeKey,
     matched.responseType,
+    matched.pt === true,
   );
 
   const clientSegmentSet = new Set(clientSegmentIds);
@@ -325,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,
+    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;
 
@@ -537,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;
@@ -567,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

@@ -210,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[];

package/src/router/match-handlers.ts

@@ -22,9 +22,21 @@ import {
   matchError as _matchError,
 } from "./match-api.js";
 import { previewMatch as _previewMatch } from "./preview-match.js";
-import { runWithRouterLogContext, withRouterLogScope } from "./logging.js";
+import {
+  runWithRouterLogContext,
+  withRouterLogScope,
+  isRouterDebugEnabled,
+  startRevalidationTrace,
+  flushRevalidationTrace,
+} from "./logging.js";
 import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
+import {
+  type TelemetrySink,
+  safeEmit,
+  resolveSink,
+  getRequestId,
+} from "./telemetry.js";
 
 export interface MatchHandlerDeps<TEnv = any> {
   buildRouterContext: () => RouterContext<TEnv>;
@@ -38,6 +50,7 @@ export interface MatchHandlerDeps<TEnv = any> {
     selectorContext: InterceptSelectorContext | null,
     isAction: boolean,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
+  telemetry?: TelemetrySink;
 }
 
 export interface MatchHandlers<TEnv = any> {
@@ -98,6 +111,8 @@ export function createMatchHandlers<TEnv = any>(
     defaultErrorBoundary,
     findInterceptForRoute,
   } = deps;
+  const hasTelemetry = !!deps.telemetry;
+  const telemetry = resolveSink(deps.telemetry);
 
   async function createMatchContextForFull(
     request: Request,
@@ -140,13 +155,43 @@ export function createMatchHandlers<TEnv = any>(
    * - background-revalidation: SWR revalidation
    */
   async function match(request: Request, env: TEnv): Promise<MatchResult> {
-    return runWithRouterLogContext({ request, transaction: "match" }, () =>
-      runWithRouterContext(buildRouterContext(), async () =>
+    const requestId = hasTelemetry ? getRequestId(request) : undefined;
+    return runWithRouterLogContext({ request, transaction: "match" }, () => {
+      const routerCtx = buildRouterContext();
+      routerCtx.requestId = requestId;
+      return runWithRouterContext(routerCtx, async () =>
         withRouterLogScope("match", async () => {
+          const matchStart = performance.now();
+          const pathname = new URL(request.url).pathname;
+          if (hasTelemetry) {
+            safeEmit(telemetry, {
+              type: "request.start",
+              timestamp: matchStart,
+              requestId,
+              method: request.method,
+              pathname,
+              transaction: "match",
+              isPartial: false,
+            });
+          }
+
           const result = await createMatchContextForFull(request, env);
 
           // Handle redirect case
           if ("type" in result && result.type === "redirect") {
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "request.end",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                durationMs: performance.now() - matchStart,
+                segmentCount: 0,
+                cacheHit: false,
+              });
+            }
             return {
               segments: [],
               matched: [],
@@ -161,8 +206,47 @@ export function createMatchHandlers<TEnv = any>(
           try {
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
-            return await collectMatchResult(pipeline, ctx, state);
+            const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "cache.decision",
+                timestamp: performance.now(),
+                requestId,
+                pathname,
+                routeKey: ctx.routeKey,
+                hit: state.cacheHit,
+                shouldRevalidate: !!state.shouldRevalidate,
+                source: state.cacheSource,
+              });
+              safeEmit(telemetry, {
+                type: "request.end",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                durationMs: performance.now() - matchStart,
+                segmentCount: matchResult.segments.length,
+                cacheHit: state.cacheHit,
+              });
+            }
+            return matchResult;
           } catch (error) {
+            if (hasTelemetry) {
+              const errorObj =
+                error instanceof Error ? error : new Error(String(error));
+              safeEmit(telemetry, {
+                type: "request.error",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                error: errorObj,
+                phase: error instanceof Response ? "redirect" : "routing",
+                durationMs: performance.now() - matchStart,
+              });
+            }
             if (error instanceof Response) throw error;
             // Report unhandled errors during full match pipeline
             callOnError(error, "routing", {
@@ -175,8 +259,8 @@ export function createMatchHandlers<TEnv = any>(
             throw sanitizeError(error);
           }
         }),
-      ),
-    );
+      );
+    });
   }
 
   async function matchError(
@@ -214,23 +298,112 @@ export function createMatchHandlers<TEnv = any>(
     context: TEnv,
     actionContext?: ActionContext,
   ): Promise<MatchResult | null> {
+    const partialRequestId = hasTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext(
       { request, transaction: "matchPartial" },
-      () =>
-        runWithRouterContext(buildRouterContext(), async () =>
+      () => {
+        const routerCtx = buildRouterContext();
+        routerCtx.requestId = partialRequestId;
+        return runWithRouterContext(routerCtx, async () =>
           withRouterLogScope("matchPartial", async () => {
+            const matchStart = performance.now();
+            const pathname = new URL(request.url).pathname;
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "request.start",
+                timestamp: matchStart,
+                requestId: partialRequestId,
+                method: request.method,
+                pathname,
+                transaction: "matchPartial",
+                isPartial: true,
+              });
+            }
+
             const ctx = await createMatchContextForPartial(
               request,
               context,
               actionContext,
             );
-            if (!ctx) return null;
+            if (!ctx) {
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "request.end",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  durationMs: performance.now() - matchStart,
+                  segmentCount: 0,
+                  cacheHit: false,
+                });
+              }
+              return null;
+            }
+
+            if (isRouterDebugEnabled()) {
+              startRevalidationTrace({
+                method: request.method,
+                prevUrl: ctx.prevUrl.href,
+                nextUrl: ctx.url.href,
+                routeKey: ctx.routeKey,
+                isAction: !!actionContext,
+                stale: ctx.stale || undefined,
+              });
+            }
 
             try {
               const state = createPipelineState();
               const pipeline = createMatchPartialPipeline(ctx, state);
-              return await collectMatchResult(pipeline, ctx, state);
+              const matchResult = await collectMatchResult(
+                pipeline,
+                ctx,
+                state,
+              );
+              flushRevalidationTrace();
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "cache.decision",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  pathname,
+                  routeKey: ctx.routeKey,
+                  hit: state.cacheHit,
+                  shouldRevalidate: !!state.shouldRevalidate,
+                  source: state.cacheSource,
+                });
+                safeEmit(telemetry, {
+                  type: "request.end",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  durationMs: performance.now() - matchStart,
+                  segmentCount: matchResult.segments.length,
+                  cacheHit: state.cacheHit,
+                });
+              }
+              return matchResult;
             } catch (error) {
+              flushRevalidationTrace();
+              if (hasTelemetry) {
+                const errorObj =
+                  error instanceof Error ? error : new Error(String(error));
+                const phase = actionContext ? "action" : "revalidation";
+                safeEmit(telemetry, {
+                  type: "request.error",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  error: errorObj,
+                  phase: error instanceof Response ? "redirect" : phase,
+                  durationMs: performance.now() - matchStart,
+                });
+              }
               if (error instanceof Response) throw error;
               // Report unhandled errors during partial match pipeline
               callOnError(error, actionContext ? "action" : "revalidation", {
@@ -244,7 +417,8 @@ export function createMatchHandlers<TEnv = any>(
               throw sanitizeError(error);
             }
           }),
-        ),
+        );
+      },
     );
   }