@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/router/loader-resolution.ts

@@ -7,6 +7,7 @@
 import type { ReactNode } from "react";
 import { track } from "../server/context";
 import type { EntryData } from "../server/context";
+import { contextGet } from "../context-var.js";
 import type {
   ResolvedSegment,
   HandlerContext,
@@ -19,10 +20,11 @@ import type {
   ErrorInfo,
 } from "../types";
 import type { LoaderRevalidationResult, ActionContext } from "./types";
-import { isHandle, type Handle } from "../handle.js";
-import type { HandleStore } from "../server/handle-store.js";
+import { isHandle, collectHandleData, type Handle } from "../handle.js";
+import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
-import { getRequestContext } from "../server/request-context.js";
+import { _getRequestContext } from "../server/request-context.js";
+import { isInsideLoaderScope } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -182,7 +184,7 @@ function createLoaderExecutor<TEnv>(
   callerLoaderId: string | null,
 ) => Promise<any> {
   // Capture RequestContext eagerly for cookie access (ALS protection on Cloudflare)
-  const reqCtxRef = getRequestContext();
+  const reqCtxRef = _getRequestContext();
 
   // Dependency graph: loaderId -> set of loader IDs it directly depends on.
   const dependsOn = new Map<string, Set<string>>();
@@ -241,33 +243,116 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
+    const variables = (ctx as InternalHandlerContext<any, TEnv>)._variables;
+
+    // Capture whether this loader is being started from a DSL loader scope
+    // (runInsideLoaderScope in fresh.ts). Handler-invoked loaders are NOT
+    // inside loader scope. This determines whether rendered() is allowed.
+    const isDslLoader = isInsideLoaderScope();
+
+    let renderedResolved = false;
+    let renderedPromise: Promise<void> | null = null;
+
+    // Loader functions are always fresh (never cached), so they get an
+    // unguarded get that bypasses non-cacheable read guards. This applies
+    // to ALL loaders — DSL and handler-called — because the loader
+    // function itself always re-executes. Also handles nested deps
+    // (loaderA → use(loaderB)) since all share this unguarded get.
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
+      routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
       searchParams: ctx.searchParams,
       search: (ctx as any).search,
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env,
-      var: ctx.var,
-      get: ctx.get,
-      cookie(name: string) {
-        return reqCtxRef?.cookie(name);
-      },
-      cookies() {
-        return reqCtxRef?.cookies() ?? {};
-      },
-      use: <TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>,
-      ): Promise<TDep> => {
-        return useLoader(dep, currentLoaderId);
-      },
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
+      get: ((keyOrVar: any) =>
+        contextGet(variables, keyOrVar)) as typeof ctx.get,
+      use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+        if (isHandle(item)) {
+          if (!renderedResolved) {
+            throw new Error(
+              `ctx.use(handle) in a loader requires "await ctx.rendered()" first. ` +
+                `Handle "${item.$$id}" cannot be read until the render tree has settled.`,
+            );
+          }
+          const reqCtx = reqCtxRef ?? _getRequestContext();
+          if (!reqCtx) {
+            throw new Error(
+              `ctx.use(handle) failed: request context not available.`,
+            );
+          }
+          const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
+          const snapshot =
+            reqCtx._renderBarrierHandleSnapshot ??
+            buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
+          return collectHandleData(item, snapshot, segmentOrder);
+        }
+
+        // Loader case
+        return useLoader(item as LoaderDefinition<any, any>, currentLoaderId);
+      }) as LoaderContext["use"],
       method: "GET",
       body: undefined,
       reverse: ctx.reverse as LoaderContext["reverse"],
+      rendered: (): Promise<void> => {
+        // Guard: only DSL loaders may use rendered()
+        if (!isDslLoader) {
+          throw new Error(
+            `ctx.rendered() is only available in DSL loaders (registered via loader() in urls()). ` +
+              `Handler-invoked loaders (ctx.use(Loader) inside a handler) cannot use rendered().`,
+          );
+        }
+
+        // Guard: reject streaming trees
+        const reqCtx = reqCtxRef ?? _getRequestContext();
+        if (reqCtx?._treeHasStreaming) {
+          throw new Error(
+            `ctx.rendered() is not supported when the matched route tree uses loading(). ` +
+              `Streaming handlers may not have settled when rendered() resolves. ` +
+              `Remove loading() from the route tree or restructure to avoid rendered().`,
+          );
+        }
+
+        if (renderedPromise) return renderedPromise;
+
+        if (!reqCtx) {
+          throw new Error(
+            `ctx.rendered() failed: request context not available.`,
+          );
+        }
+
+        // Bidirectional deadlock check: if a handler already started
+        // awaiting this loader, calling rendered() would deadlock.
+        if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
+          throw new Error(
+            `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
+              `is already awaiting this loader via ctx.use(). The handler blocks ` +
+              `segment resolution, which blocks the barrier, which blocks this loader. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+
+        // Register this loader as waiting for the barrier so that
+        // setupLoaderAccess can detect deadlocks when a handler
+        // tries to await the same loader via ctx.use().
+        if (!reqCtx._renderBarrierWaiters) {
+          reqCtx._renderBarrierWaiters = new Set();
+        }
+        reqCtx._renderBarrierWaiters.add(currentLoaderId);
+
+        renderedPromise = reqCtx._renderBarrier.then(() => {
+          renderedResolved = true;
+        });
+        return renderedPromise;
+      },
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`);
+    const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(
       loaderFn(loaderCtx as LoaderContext<any, TEnv>),
     ).finally(() => {
@@ -295,15 +380,22 @@ export function setupLoaderAccess<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   loaderPromises: Map<string, Promise<any>>,
 ): void {
-  // Eagerly capture the HandleStore at setup time (before pipeline async ops).
-  // In workerd/Cloudflare, dynamic imports and fetch() in the match pipeline
-  // can disrupt AsyncLocalStorage, causing getRequestContext() to return
-  // undefined when handlers later call ctx.use(handle). Capturing early
-  // ensures the store reference survives ALS disruption.
-  const handleStoreRef = getRequestContext()?._handleStore;
+  // Eagerly capture the request context and HandleStore at setup time
+  // (before pipeline async ops). In workerd/Cloudflare, dynamic imports and
+  // fetch() in the match pipeline can disrupt AsyncLocalStorage, causing
+  // getRequestContext() to return undefined when handlers later call
+  // ctx.use(handle). Capturing early ensures references survive ALS disruption.
+  const reqCtxRef = _getRequestContext();
+  const handleStoreRef = reqCtxRef?._handleStore;
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
+  // Track whether we're inside a handle push callback. Loaders started
+  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
+  // block segment resolution, so they must not be registered as handler
+  // dependencies for deadlock detection.
+  let insideHandlePush = false;
+
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -323,16 +415,57 @@ export function setupLoaderAccess<TEnv>(
       ) => {
         if (!store) return;
 
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
+        if (typeof dataOrFn === "function") {
+          // Mark scope so ctx.use(loader) calls inside the callback
+          // are not registered as handler-to-loader deps.
+          insideHandlePush = true;
+          try {
+            const result = (dataOrFn as () => Promise<unknown>)();
+            store.push(handle.$$id, segmentId, result);
+          } finally {
+            insideHandlePush = false;
+          }
+          return;
+        }
 
-        store.push(handle.$$id, segmentId, valueOrPromise);
+        store.push(handle.$$id, segmentId, dataOrFn);
       };
     }
 
-    return useLoader(item as LoaderDefinition<any, any>, null);
+    // Deadlock guard and handler-to-loader dependency tracking.
+    // Skip when inside a DSL loader scope (resolveLoaderData also calls
+    // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
+    // inside a handle push callback (push callbacks don't block segment
+    // resolution so they can't cause rendered() deadlocks).
+    const loader = item as LoaderDefinition<any, any>;
+    if (!isInsideLoaderScope() && !insideHandlePush) {
+      const reqCtx = reqCtxRef ?? _getRequestContext();
+      if (reqCtx) {
+        // Direction 1: handler awaits loader that already called rendered()
+        if (
+          loaderPromises.has(loader.$$id) &&
+          reqCtx._renderBarrierWaiters?.has(loader.$$id)
+        ) {
+          throw new Error(
+            `Deadlock: handler is awaiting loader "${loader.$$id}" which called ctx.rendered(). ` +
+              `The loader is waiting for segment resolution, but the handler blocks resolution. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+        // Direction 2: track dep so rendered() can detect the deadlock
+        // if the loader calls it later. Skip when the barrier has already
+        // resolved — no deadlock is possible (rendered() resolves immediately).
+        // _renderBarrierSegmentOrder is undefined before resolution, string[]
+        // after. This also prevents false positives from handle push callbacks
+        // that resume after their first await (post-barrier-resolution).
+        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+          if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
+          reqCtx._handlerLoaderDeps.add(loader.$$id);
+        }
+      }
+    }
+
+    return useLoader(loader, null);
   }) as typeof ctx.use;
 }
 
@@ -342,7 +475,7 @@ export function setupLoaderAccess<TEnv>(
  */
 export function setupBuildUse<TEnv>(ctx: HandlerContext<any, TEnv>): void {
   // Eagerly capture the HandleStore (same ALS protection as setupLoaderAccess).
-  const handleStoreRef = getRequestContext()?._handleStore;
+  const handleStoreRef = _getRequestContext()?._handleStore;
 
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     // Handle case: return a push function bound to the current segment

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;
 
@@ -94,9 +132,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 +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

@@ -9,6 +9,7 @@ import { createRouteHelpers } from "../route-definition";
 import {
   getContext,
   runWithPrefixes,
+  getIsolatedLazyParent,
   type EntryData,
   type MetricsStore,
 } from "../server/context";
@@ -65,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();
@@ -112,21 +115,49 @@ export async function loadManifest(
     // 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 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 && (lazyContext as any).counters) {
-      const captured = (lazyContext as any).counters as Record<string, number>;
-      for (const [key, value] of Object.entries(captured)) {
+    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,
@@ -178,15 +209,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