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

package/src/router/match-middleware/cache-lookup.ts

@@ -92,27 +92,61 @@
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
+import { resolveSink, safeEmit } from "../telemetry.js";
+import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
+import type { HandleStore } from "../../server/handle-store.js";
+import {
+  getRequestContext,
+  _getRequestContext,
+} from "../../server/request-context.js";
 
 // Lazily initialized prerender store singleton and dynamically imported deps.
 // Dynamic imports prevent pulling in @vitejs/plugin-rsc/rsc virtual module at
 // top-level, which breaks vitest (only URLs with file:, data:, node: schemes).
 let prerenderStoreInstance: PrerenderStore | null | undefined;
-let _deserializeSegments: typeof import("../../cache/cache-scope.js").deserializeSegments | undefined;
-let _hashParams: typeof import("../../prerender/param-hash.js").hashParams | undefined;
-let _getRequestContext: typeof import("../../server/request-context.js").getRequestContext | undefined;
+let _deserializeSegments:
+  | typeof import("../../cache/segment-codec.js").deserializeSegments
+  | undefined;
+let _restoreHandles:
+  | typeof import("../../cache/handle-snapshot.js").restoreHandles
+  | undefined;
+let _hashParams:
+  | typeof import("../../prerender/param-hash.js").hashParams
+  | undefined;
+let _lazyGetRequestContext:
+  | typeof import("../../server/request-context.js").getRequestContext
+  | undefined;
+
+function paramsEqual(
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean {
+  if (a === b) return true;
+
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+}
 
 async function ensurePrerenderDeps() {
   if (!_deserializeSegments) {
-    const [cache, paramHash, reqCtx, store] = await Promise.all([
-      import("../../cache/cache-scope.js"),
+    const [codec, snapshot, paramHash, reqCtx, store] = await Promise.all([
+      import("../../cache/segment-codec.js"),
+      import("../../cache/handle-snapshot.js"),
       import("../../prerender/param-hash.js"),
       import("../../server/request-context.js"),
       import("../../prerender/store.js"),
     ]);
-    _deserializeSegments = cache.deserializeSegments;
+    _deserializeSegments = codec.deserializeSegments;
+    _restoreHandles = snapshot.restoreHandles;
     _hashParams = paramHash.hashParams;
-    _getRequestContext = reqCtx.getRequestContext;
+    _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
       prerenderStoreInstance = store.createPrerenderStore();
     }
@@ -129,29 +163,31 @@ async function* yieldFromStore<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   pipelineStart: number,
+  handleStoreRef?: HandleStore,
 ): AsyncGenerator<ResolvedSegment> {
-  const {
-    resolveLoadersOnlyWithRevalidation,
-    resolveLoadersOnly,
-  } = getRouterContext<TEnv>();
-
-  if (!_deserializeSegments || !_hashParams || !_getRequestContext) {
+  const { resolveLoadersOnlyWithRevalidation, resolveLoadersOnly } =
+    getRouterContext<TEnv>();
+
+  if (
+    !_deserializeSegments ||
+    !_restoreHandles ||
+    !_hashParams ||
+    !_lazyGetRequestContext
+  ) {
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
 
   const segments = await _deserializeSegments(entry.segments);
 
-  // Replay handle data (same as runtime cache hit path)
-  const handleStore = _getRequestContext()?._handleStore;
+  // Replay handle data (same as runtime cache hit path).
+  // Prefer the eagerly-captured handleStoreRef to avoid ALS disruption in workerd.
+  const handleStore = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
   if (handleStore) {
-    for (const [segId, segHandles] of Object.entries(entry.handles)) {
-      if (Object.keys(segHandles).length > 0) {
-        handleStore.replaySegmentData(segId, segHandles);
-      }
-    }
+    _restoreHandles(entry.handles, handleStore);
   }
 
   state.cacheHit = true;
+  state.cacheSource = "prerender";
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
@@ -159,10 +195,14 @@ async function* yieldFromStore<TEnv>(
   // so parent layouts stay live (client keeps its existing versions).
   // When params changed (e.g., different guide slug), the segments have
   // different content, so we must NOT nullify.
-  const paramsChanged = !ctx.isFullMatch &&
-    JSON.stringify(ctx.matched.params) !== JSON.stringify(ctx.prevParams);
+  const paramsChanged =
+    !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
   for (const segment of segments) {
-    if (!ctx.isFullMatch && !paramsChanged && ctx.clientSegmentSet.has(segment.id)) {
+    if (
+      !ctx.isFullMatch &&
+      !paramsChanged &&
+      ctx.clientSegmentSet.has(segment.id)
+    ) {
       segment.component = null;
       segment.loading = undefined;
     }
@@ -170,6 +210,9 @@ async function* yieldFromStore<TEnv>(
   }
 
   // Resolve loaders fresh (loaders are never pre-rendered/cached)
+  const ms = ctx.metricsStore;
+  const loaderStart = performance.now();
+
   if (ctx.isFullMatch) {
     if (resolveLoadersOnly) {
       const loaderSegments = await ctx.Store.run(() =>
@@ -209,9 +252,19 @@ async function* yieldFromStore<TEnv>(
     }
   }
 
-  const ms = ctx.metricsStore;
   if (ms) {
-    ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+    const loaderEnd = performance.now();
+    ms.metrics.push({
+      label: "pipeline:loader-resolve",
+      duration: loaderEnd - loaderStart,
+      startTime: loaderStart - ms.requestStart,
+      depth: 1,
+    });
+    ms.metrics.push({
+      label: "pipeline:cache-lookup",
+      duration: loaderEnd - pipelineStart,
+      startTime: pipelineStart - ms.requestStart,
+    });
   }
 }
 
@@ -219,7 +272,7 @@ async function* yieldFromStore<TEnv>(
  * Async generator middleware type
  */
 export type GeneratorMiddleware<T> = (
-  source: AsyncGenerator<T>
+  source: AsyncGenerator<T>,
 ) => AsyncGenerator<T>;
 
 /**
@@ -237,14 +290,21 @@ export type GeneratorMiddleware<T> = (
  */
 export function withCacheLookup<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
     const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
+    // Eagerly capture the HandleStore before any async operations.
+    // In workerd/Cloudflare, dynamic imports and fetch() inside the pipeline
+    // can disrupt AsyncLocalStorage, causing getRequestContext() to return
+    // undefined afterward. Capturing the reference early ensures handle replay
+    // and handler handle-push work regardless of ALS state.
+    const handleStoreRef = _getRequestContext()?._handleStore;
+
     const {
       evaluateRevalidation,
       buildEntryRevalidateMap,
@@ -258,12 +318,54 @@ export function withCacheLookup<TEnv>(
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
         const paramHash = _hashParams!(ctx.matched.params);
-        const entry = await prerenderStoreInstance.get(
-          ctx.matched.routeKey, paramHash, { pathname: ctx.pathname }
+        const isPassthroughPrerenderRoute = ctx.entries.some(
+          (entry) =>
+            entry.type === "route" &&
+            entry.prerenderDef?.options?.passthrough === true,
         );
-        if (entry) {
-          yield* yieldFromStore(entry, ctx, state, pipelineStart);
-          return;
+
+        if (ctx.isIntercept) {
+          // Intercept navigation: try intercept-specific prerender entry
+          const entry = await prerenderStoreInstance.get(
+            ctx.matched.routeKey,
+            paramHash + "/i",
+            {
+              pathname: ctx.pathname,
+              isPassthroughRoute: isPassthroughPrerenderRoute,
+            },
+          );
+          if (entry) {
+            yield* yieldFromStore(
+              entry,
+              ctx,
+              state,
+              pipelineStart,
+              handleStoreRef,
+            );
+            return;
+          }
+          // No intercept prerender -- fall through to normal pipeline
+          // (skip non-intercept prerender to let intercept-resolution run)
+        } else {
+          // Normal navigation: existing behavior
+          const entry = await prerenderStoreInstance.get(
+            ctx.matched.routeKey,
+            paramHash,
+            {
+              pathname: ctx.pathname,
+              isPassthroughRoute: isPassthroughPrerenderRoute,
+            },
+          );
+          if (entry) {
+            yield* yieldFromStore(
+              entry,
+              ctx,
+              state,
+              pipelineStart,
+              handleStoreRef,
+            );
+            return;
+          }
         }
       }
     }
@@ -278,18 +380,61 @@ export function withCacheLookup<TEnv>(
     // in-process where Node APIs work, so no interception is needed.
     if (!ctx.isAction && !ctx.matched.pr && globalThis.__PRERENDER_DEV_URL) {
       const hasStatic = ctx.entries.some(
-        (e) => (e.type === "layout" || e.type === "route" || e.type === "parallel") && e.isStaticPrerender
+        (e) =>
+          (e.type === "layout" ||
+            e.type === "route" ||
+            e.type === "parallel") &&
+          e.isStaticPrerender,
       );
       if (hasStatic) {
         await ensurePrerenderDeps();
         if (prerenderStoreInstance) {
           const paramHash = _hashParams!(ctx.matched.params);
-          const entry = await prerenderStoreInstance.get(
-            ctx.matched.routeKey, paramHash, { pathname: ctx.pathname }
+          const isPassthroughPrerenderRoute = ctx.entries.some(
+            (entry) =>
+              entry.type === "route" &&
+              entry.prerenderDef?.options?.passthrough === true,
           );
-          if (entry) {
-            yield* yieldFromStore(entry, ctx, state, pipelineStart);
-            return;
+
+          if (ctx.isIntercept) {
+            const entry = await prerenderStoreInstance.get(
+              ctx.matched.routeKey,
+              paramHash + "/i",
+              {
+                pathname: ctx.pathname,
+                isPassthroughRoute: isPassthroughPrerenderRoute,
+              },
+            );
+            if (entry) {
+              yield* yieldFromStore(
+                entry,
+                ctx,
+                state,
+                pipelineStart,
+                handleStoreRef,
+              );
+              return;
+            }
+            // No intercept prerender -- fall through to normal pipeline
+          } else {
+            const entry = await prerenderStoreInstance.get(
+              ctx.matched.routeKey,
+              paramHash,
+              {
+                pathname: ctx.pathname,
+                isPassthroughRoute: isPassthroughPrerenderRoute,
+              },
+            );
+            if (entry) {
+              yield* yieldFromStore(
+                entry,
+                ctx,
+                state,
+                pipelineStart,
+                handleStoreRef,
+              );
+              return;
+            }
           }
         }
       }
@@ -300,7 +445,11 @@ export function withCacheLookup<TEnv>(
       // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
-        ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:cache-lookup",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
       }
       return;
     }
@@ -309,30 +458,54 @@ export function withCacheLookup<TEnv>(
     const cacheResult = await ctx.cacheScope.lookupRoute(
       ctx.pathname,
       ctx.matched.params,
-      ctx.isIntercept
+      ctx.isIntercept,
     );
 
     if (!cacheResult) {
       // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
-        ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:cache-lookup",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
       }
       return;
     }
 
     // Cache HIT
     state.cacheHit = true;
+    state.cacheSource = "runtime";
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
 
-    // Apply revalidation to cached segments
-    const entryRevalidateMap = buildEntryRevalidateMap?.(ctx.entries);
+    // Apply revalidation to cached segments.
+    // For full matches or empty client segment sets, this map is unnecessary:
+    // we never run segment-level revalidation and can stream segments directly.
+    const canCheckSegmentRevalidation =
+      !ctx.isFullMatch &&
+      ctx.clientSegmentSet.size > 0 &&
+      !!buildEntryRevalidateMap;
+    const entryRevalidateMap = canCheckSegmentRevalidation
+      ? buildEntryRevalidateMap(ctx.entries)
+      : undefined;
 
     for (const segment of cacheResult.segments) {
       // Skip segments client doesn't have - they need their component
       if (!ctx.clientSegmentSet.has(segment.id)) {
+        if (isTraceActive()) {
+          pushRevalidationTraceEntry({
+            segmentId: segment.id,
+            segmentType: segment.type,
+            belongsToRoute: segment.belongsToRoute ?? false,
+            source: "cache-hit",
+            defaultShouldRevalidate: true,
+            finalShouldRevalidate: true,
+            reason: "new-segment",
+          });
+        }
         yield segment;
         continue;
       }
@@ -347,6 +520,17 @@ export function withCacheLookup<TEnv>(
       const entryInfo = entryRevalidateMap?.get(segment.id);
       if (!entryInfo || entryInfo.revalidate.length === 0) {
         // No revalidation rules, use default behavior (skip if client has)
+        if (isTraceActive()) {
+          pushRevalidationTraceEntry({
+            segmentId: segment.id,
+            segmentType: segment.type,
+            belongsToRoute: segment.belongsToRoute ?? false,
+            source: "cache-hit",
+            defaultShouldRevalidate: false,
+            finalShouldRevalidate: false,
+            reason: "cached-no-rules",
+          });
+        }
         segment.component = null;
         segment.loading = undefined;
         yield segment;
@@ -368,8 +552,24 @@ export function withCacheLookup<TEnv>(
         routeKey: ctx.routeKey,
         context: ctx.handlerContext,
         actionContext: ctx.actionContext,
+        stale: cacheResult.shouldRevalidate || undefined,
+        traceSource: "cache-hit",
       });
 
+      const routerCtx = getRouterContext<TEnv>();
+      if (routerCtx.telemetry) {
+        const tSink = resolveSink(routerCtx.telemetry);
+        safeEmit(tSink, {
+          type: "revalidation.decision",
+          timestamp: performance.now(),
+          requestId: routerCtx.requestId,
+          segmentId: segment.id,
+          pathname: ctx.pathname,
+          routeKey: ctx.routeKey,
+          shouldRevalidate,
+        });
+      }
+
       if (!shouldRevalidate) {
         // Client has it, no revalidation needed
         segment.component = null;
@@ -382,12 +582,13 @@ export function withCacheLookup<TEnv>(
     // Resolve loaders fresh (loaders are NOT cached by default)
     // This ensures fresh data even on cache hit
     const Store = ctx.Store;
+    const loaderStart = performance.now();
 
     if (ctx.isFullMatch) {
       // Full match (document request) - simple loader resolution without revalidation
       if (resolveLoadersOnly) {
         const loaderSegments = await Store.run(() =>
-          resolveLoadersOnly(ctx.entries, ctx.handlerContext)
+          resolveLoadersOnly(ctx.entries, ctx.handlerContext),
         );
 
         // Update state - full match doesn't track matchedIds separately
@@ -413,8 +614,9 @@ export function withCacheLookup<TEnv>(
             ctx.prevUrl,
             ctx.url,
             ctx.routeKey,
-            ctx.actionContext
-          )
+            ctx.actionContext,
+            cacheResult.shouldRevalidate || undefined,
+          ),
         );
 
         // Update state with fresh loader matchedIds
@@ -432,7 +634,18 @@ export function withCacheLookup<TEnv>(
       }
     }
     if (ms) {
-      ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      const loaderEnd = performance.now();
+      ms.metrics.push({
+        label: "pipeline:loader-resolve",
+        duration: loaderEnd - loaderStart,
+        startTime: loaderStart - ms.requestStart,
+        depth: 1,
+      });
+      ms.metrics.push({
+        label: "pipeline:cache-lookup",
+        duration: loaderEnd - pipelineStart,
+        startTime: pipelineStart - ms.requestStart,
+      });
     }
   };
 }

package/src/router/match-middleware/cache-store.ts

@@ -104,8 +104,8 @@ import type { ResolvedSegment } from "../../types.js";
 import { getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
+import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
-import { debugLog, debugWarn } from "../logging.js";
 
 /**
  * Creates cache store middleware
@@ -120,7 +120,6 @@ export function withCacheStore<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
     // Collect all segments while passing them through
@@ -130,6 +129,9 @@ export function withCacheStore<TEnv>(
       yield segment;
     }
 
+    // Measure own work only (after source iteration completes)
+    const ownStart = performance.now();
+
     // Skip caching if:
     // 1. Cache miss but cache scope is disabled
     // 2. This is an action (actions don't cache)
@@ -142,16 +144,21 @@ export function withCacheStore<TEnv>(
       ctx.request.method !== "GET"
     ) {
       if (ms) {
-        ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:cache-store",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
 
     const {
       createHandlerContext,
-      setupLoaderAccessSilent,
+      setupLoaderAccess,
       resolveAllSegments,
       resolveInterceptEntry,
+      createHandleStore,
     } = getRouterContext<TEnv>();
 
     // Combine main segments with intercept segments
@@ -167,6 +174,8 @@ export function withCacheStore<TEnv>(
     if (!requestCtx) return;
 
     const cacheScope = ctx.cacheScope;
+    const debugPerf = !!ctx.metricsStore;
+    const reqId = debugPerf ? getOrCreateRequestId(ctx.request) : undefined;
 
     // Register onResponse callback to skip caching for non-200 responses
     // Note: error/notFound status codes are set elsewhere (not caching-specific)
@@ -184,29 +193,35 @@ export function withCacheStore<TEnv>(
         // Proactive caching: render all segments fresh in background
         // This ensures cache has complete components for future requests
         requestCtx.waitUntil(async () => {
+          const start = performance.now();
           debugLog("cacheStore", "proactive caching started", {
             pathname: ctx.pathname,
           });
+          // Swap to a fresh HandleStore so handle.push() calls from
+          // proactive resolution are captured (not silenced). The original
+          // store's stream is already sent by waitUntil time.
+          // cacheRoute reads from requestCtx._handleStore, so this ensures
+          // complete handle data (e.g. breadcrumbs) is cached.
+          const originalHandleStore = requestCtx._handleStore;
+          requestCtx._handleStore = createHandleStore();
           try {
             // Create fresh context for proactive caching
-            // This prevents handle data from polluting the response stream
             const proactiveHandlerContext = createHandlerContext(
               ctx.matched.params,
               ctx.request,
               ctx.url.searchParams,
               ctx.pathname,
               ctx.url,
-              ctx.bindings,
+              ctx.env,
               ctx.routeMap,
-              ctx.matched.routeKey
+              ctx.matched.routeKey,
+              ctx.matched.responseType,
+              ctx.matched.pt === true,
             );
             const proactiveLoaderPromises = new Map<string, Promise<any>>();
 
-            // Set up loader access that ignores handle pushes
-            setupLoaderAccessSilent(
-              proactiveHandlerContext,
-              proactiveLoaderPromises,
-            );
+            // Use normal loader access so handle data is captured
+            setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
 
             // Re-resolve ALL segments without revalidation
             const Store = ctx.Store;
@@ -239,32 +254,54 @@ export function withCacheStore<TEnv>(
               ...freshSegments,
               ...freshInterceptSegments,
             ];
+            requestCtx._handleStore.seal();
             await cacheScope.cacheRoute(
               ctx.pathname,
               ctx.matched.params,
               completeSegments,
               ctx.isIntercept,
             );
+            if (debugPerf) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+              );
+            }
             debugLog("cacheStore", "proactive caching complete", {
               pathname: ctx.pathname,
             });
           } catch (error) {
+            if (debugPerf) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} FAILED (${dur.toFixed(2)}ms) error=${String(error)}`,
+              );
+            }
             debugWarn("cacheStore", "proactive caching failed", {
               pathname: ctx.pathname,
               error: String(error),
             });
+          } finally {
+            requestCtx._handleStore = originalHandleStore;
           }
         });
       } else {
         // All segments have components - cache directly
         // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
         requestCtx.waitUntil(async () => {
+          const start = performance.now();
           await cacheScope.cacheRoute(
             ctx.pathname,
             ctx.matched.params,
             allSegmentsToCache,
             ctx.isIntercept,
           );
+          if (debugPerf) {
+            const dur = performance.now() - start;
+            console.log(
+              `[RSC Background][req:${reqId}] Cache store ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${allSegmentsToCache.length}`,
+            );
+          }
         });
       }
 
@@ -272,7 +309,11 @@ export function withCacheStore<TEnv>(
     });
 
     if (ms) {
-      ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      ms.metrics.push({
+        label: "pipeline:cache-store",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
     }
   };
 }