@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80

package/src/router/logging.ts

@@ -0,0 +1,251 @@
+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 {
+  request: Request;
+  transaction: string;
+}
+
+interface LogDetails {
+  [key: string]: unknown;
+}
+
+const routerLogContext = new AsyncLocalStorage<RouterLogContext>();
+const requestIds = new WeakMap<Request, string>();
+
+let requestCounter = 0;
+let transactionCounter = 0;
+
+function nextId(prefix: string, counter: number): string {
+  return `${prefix}${counter.toString(36)}`;
+}
+
+function getHeaderRequestId(request: Request): string | null {
+  const candidate =
+    request.headers.get("x-rsc-router-request-id") ??
+    request.headers.get("x-request-id") ??
+    request.headers.get("cf-ray");
+  if (!candidate) return null;
+  const trimmed = candidate.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function getOrCreateRequestId(request: Request): string {
+  const existing = requestIds.get(request);
+  if (existing) return existing;
+
+  const fromHeaders = getHeaderRequestId(request);
+  if (fromHeaders) {
+    requestIds.set(request, fromHeaders);
+    return fromHeaders;
+  }
+
+  requestCounter += 1;
+  const generated = nextId("req-", requestCounter);
+  requestIds.set(request, generated);
+  return generated;
+}
+
+export function runWithRouterLogContext<T>(
+  options: RouterLogOptions,
+  fn: () => T,
+): T {
+  if (!INTERNAL_RANGO_DEBUG) {
+    return fn();
+  }
+
+  const requestId = getOrCreateRequestId(options.request);
+  transactionCounter += 1;
+  const transactionId = `${options.transaction}-${nextId("tx-", transactionCounter)}`;
+
+  return routerLogContext.run(
+    {
+      requestId,
+      transactionId,
+      depth: 0,
+    },
+    fn,
+  );
+}
+
+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 {
+  const ctx = routerLogContext.getStore();
+  if (!INTERNAL_RANGO_DEBUG || !ctx) {
+    return fn();
+  }
+
+  debugLog(label, "start");
+
+  return routerLogContext.run({ ...ctx, depth: ctx.depth + 1 }, () => {
+    try {
+      const result = fn();
+      if (result && typeof (result as Promise<T>).then === "function") {
+        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;
+    } catch (error) {
+      debugLog(label, "error", { error: String(error) });
+      throw error;
+    }
+  });
+}
+
+export function isRouterDebugEnabled(): boolean {
+  return INTERNAL_RANGO_DEBUG && !!routerLogContext.getStore();
+}
+
+function formatPrefix(scope: string): string {
+  const ctx = routerLogContext.getStore();
+  if (!ctx) return `[Router][${scope}]`;
+  const indent = "  ".repeat(ctx.depth);
+  return `[Router][req:${ctx.requestId}][tx:${ctx.transactionId}] ${indent}[${scope}]`;
+}
+
+export function debugLog(
+  scope: string,
+  message: string,
+  details?: LogDetails,
+): void {
+  if (!isRouterDebugEnabled()) return;
+
+  const prefix = formatPrefix(scope);
+  if (details) {
+    console.log(`${prefix} ${message}`, details);
+    return;
+  }
+
+  console.log(`${prefix} ${message}`);
+}
+
+export function debugWarn(
+  scope: string,
+  message: string,
+  details?: LogDetails,
+): void {
+  if (!isRouterDebugEnabled()) return;
+
+  const prefix = formatPrefix(scope);
+  if (details) {
+    console.warn(`${prefix} ${message}`, details);
+    return;
+  }
+
+  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,27 +6,86 @@
 
 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";
+import { VERSION } from "@rangojs/router:version";
+
+// Module-level manifest cache: avoids re-executing DSL handler on every request.
+// Handler execution is deterministic (components, loaders, middleware are module-level
+// stable references), so the resulting EntryData tree can be safely cached and reused
+// across requests within the same isolate.
+//
+// Cache is keyed by (VERSION, mountIndex, routeKey, isSSR). VERSION comes from the
+// @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
+// When VERSION changes, this module re-evaluates and the cache is recreated empty.
+// Including VERSION in the key is additional defense against stale entries.
+const manifestModuleCache = new Map<string, Map<string, EntryData>>();
 
 /**
  * Load manifest from route entry with AsyncLocalStorage context
  * Handles lazy imports, unwrapping, and validation
  *
- * Note: We don't cache manifests at the module level because includes are
- * lazily evaluated. Caching an incomplete manifest would cause cache misses
- * for routes in not-yet-evaluated includes.
+ * Results are cached at module level after first execution. Subsequent calls
+ * for the same (routeKey, isSSR) within the same isolate return cached data
+ * without re-executing the DSL handler.
+ */
+/**
+ * Clear the module-level manifest cache.
+ * Called on HMR to ensure stale handler references are discarded.
  */
+export function clearManifestCache(): void {
+  manifestModuleCache.clear();
+}
+
 export async function loadManifest(
   entry: RouteEntry<any>,
   routeKey: string,
   path: string,
   metricsStore?: MetricsStore,
-  isSSR?: boolean
+  isSSR?: boolean,
 ): Promise<EntryData> {
+  // Helper to push a metric entry
+  const pushMetric = metricsStore
+    ? (label: string, start: number) => {
+        metricsStore.metrics.push({
+          label,
+          duration: performance.now() - start,
+          startTime: start - metricsStore.requestStart,
+        });
+      }
+    : undefined;
+
   const mountIndex = entry.mountIndex;
+
+  // Check module-level cache (persists across requests within same isolate)
+  // 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();
+    // Set up Store for downstream consumers (segment resolution reads Store.manifest)
+    const Store = getContext().getOrCreateStore(routeKey);
+    Store.mountIndex = mountIndex;
+    Store.isSSR = isSSR;
+    if (metricsStore) Store.metrics = metricsStore;
+    // Restore cached manifest into Store
+    for (const [k, v] of cached) {
+      Store.manifest.set(k, v);
+    }
+    pushMetric?.("manifest:cache-hit", cacheStart);
+    return cached.get(routeKey)!;
+  }
+
+  const storeSetupStart = performance.now();
   const Store = getContext().getOrCreateStore(routeKey);
 
   // Set mount index in store for unique shortCode prefixes
@@ -40,20 +99,66 @@ export async function loadManifest(
     Store.metrics = metricsStore;
   }
 
+  pushMetric?.("manifest:store-setup", storeSetupStart);
+
   // Clear manifest before rebuilding to prevent stale entry mutations
+  const clearStart = performance.now();
   Store.manifest.clear();
+  pushMetric?.("manifest:clear", clearStart);
 
   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
+    // were created during pattern extraction.  This prevents shortCode
+    // collisions between lazy and non-lazy entries under the same parent
+    // (e.g., ArticlesLayout and BlogLayout both under NavLayout).
+    if (lazyContext?.counters) {
+      for (const [key, value] of Object.entries(lazyContext.counters)) {
+        Store.counters[key] = Math.max(Store.counters[key] ?? 0, value);
+      }
+    }
 
+    // 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. Always write
+    // (including clearing to undefined) so a prior lazy build's profile
+    // map cannot leak into a later non-lazy build on the same ALS-backed
+    // Store — which would otherwise let cache("name") resolve a profile
+    // from an unrelated entry.
+    Store.cacheProfiles = entry.cacheProfiles ?? lazyContext?.cacheProfiles;
+
+    // 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. Always write
+    // (including clearing to undefined, which makes getRootScoped()
+    // return its true default) so a prior lazy build's scope cannot leak
+    // into a later non-lazy build on the same ALS-backed Store — which
+    // would otherwise mis-register plain routes as non-root-scoped and
+    // break dot-local reverse resolution.
+    Store.rootScoped = lazyContext?.rootScoped;
+
+    // Propagate includeScope from lazyContext so that direct-descendant
+    // shortCodes of this include use the correct scoped counter namespace
+    // on every manifest rebuild. Always write (including clearing to
+    // undefined) so a prior lazy build's scope cannot leak into a later
+    // non-lazy build on the same ALS-backed Store.
+    Store.includeScope = lazyContext?.includeScope;
+
+    const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(
       Store,
       Store.namespace || namespaceWithMount,
@@ -62,25 +167,23 @@ export async function loadManifest(
         // Create helpers for lazy-loaded handlers that need them
         const helpers = createRouteHelpers();
 
-        // For lazy entries, use lazyPatterns.handler() with proper prefixes
+        // For lazy entries, use lazyPatterns.handler() with proper prefixes.
+        // Do NOT wrap in MapRootLayout here: the captured parent chain from
+        // pattern extraction already includes the synthetic MapRootLayout
+        // parent, so adding another would create an extra level that does
+        // not exist in the non-lazy (root handler) path and would produce
+        // mismatched shortCodes.
         if (entry.lazy && entry.lazyPatterns) {
           const lazyPatterns = entry.lazyPatterns as UrlPatterns<any>;
           const includePrefix = (entry as any)._lazyPrefix || "";
           const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
 
-          // Wrap in root layout and run with prefixes
-          const wrappedItems = helpers.layout(MapRootLayout, () => {
-            if (fullPrefix || lazyContext?.namePrefix) {
-              return runWithPrefixes(
-                fullPrefix,
-                lazyContext?.namePrefix,
-                () => lazyPatterns.handler()
-              );
-            }
-            return lazyPatterns.handler();
-          });
-
-          return [wrappedItems].flat(3);
+          if (fullPrefix || lazyContext?.namePrefix) {
+            return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () =>
+              lazyPatterns.handler(),
+            );
+          }
+          return lazyPatterns.handler();
         }
 
         // Wrap handler execution in root layout so routes get correct parent
@@ -106,35 +209,60 @@ 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()"
-    );
-    invariant(
-      useItems.some((item: { type: string }) => item.type === "layout"),
-      "Top-level handler must be a layout"
+      "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
+    // included patterns handler directly (no MapRootLayout wrapper) so
+    // we skip this check -- the layout is in the captured parent chain.
+    if (!lazyContext) {
+      invariant(
+        useItems.some((item: { type: string }) => item.type === "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);
+
+    // Cache manifest for future requests in this isolate
+    manifestModuleCache.set(cacheKey, new Map(Store.manifest));
 
     return Store.manifest.get(routeKey)!;
   } catch (e) {
@@ -148,7 +276,7 @@ export async function loadManifest(
             routeKey,
           },
         },
-      }
+      },
     );
   }
 }