@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

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

@@ -70,9 +70,11 @@
  *   - No segments yielded from this middleware
  *
  * Loaders:
- *   - NEVER cached by design
+ *   - NEVER cached in the segment cache
  *   - Always resolved fresh on every request
  *   - Ensures data freshness even with cached UI components
+ *   - Segment cache staleness does NOT propagate to loader revalidation;
+ *     loaders use their own revalidation rules (actionId, user-defined)
  *
  *
  * REVALIDATION RULES
@@ -91,28 +93,52 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import { getRouterContext } from "../router-context.js";
+import { getRouterContext, type RouterContext } from "../router-context.js";
+import { observeEvent } from "../instrument.js";
+import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
+import { treeHasStreaming } from "./segment-resolution.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";
+import { paramsEqual } from "../params-util.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 _decodeHandles:
+  | typeof import("../../cache/handle-snapshot.js").decodeHandles
+  | undefined;
+let _hashParams:
+  | typeof import("../../prerender/param-hash.js").hashParams
+  | undefined;
+let _lazyGetRequestContext:
+  | typeof import("../../server/request-context.js").getRequestContext
+  | undefined;
 
 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;
+    _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
-    _getRequestContext = reqCtx.getRequestContext;
+    _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
       prerenderStoreInstance = store.createPrerenderStore();
     }
@@ -124,52 +150,23 @@ async function ensurePrerenderDeps() {
  * Deserializes segments, replays handle data, yields segments with partial
  * navigation nullification, and resolves fresh loaders.
  */
-async function* yieldFromStore<TEnv>(
-  entry: PrerenderEntry,
+// Resolve loaders fresh on a cache hit (loaders are NEVER cached) and yield
+// the loader segments, updating state.matchedIds and pushing the loader-resolve
+// + cache-hit metrics. Shared verbatim by the prerender-store path
+// (yieldFromStore) and the runtime cache-hit path (withCacheLookup). The router
+// resolve fns are passed in (captured early by the callers) rather than re-read
+// from getRouterContext() here, because that is ALS-backed and the callers run
+// awaits before reaching this point (workerd can disrupt ALS mid-pipeline).
+async function* resolveFreshLoadersAndYield<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   pipelineStart: number,
+  ms: MatchContext<TEnv>["metricsStore"],
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
 ): AsyncGenerator<ResolvedSegment> {
-  const {
-    resolveLoadersOnlyWithRevalidation,
-    resolveLoadersOnly,
-  } = getRouterContext<TEnv>();
-
-  if (!_deserializeSegments || !_hashParams || !_getRequestContext) {
-    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;
-  if (handleStore) {
-    for (const [segId, segHandles] of Object.entries(entry.handles)) {
-      if (Object.keys(segHandles).length > 0) {
-        handleStore.replaySegmentData(segId, segHandles);
-      }
-    }
-  }
-
-  state.cacheHit = true;
-  state.cachedSegments = segments;
-  state.cachedMatchedIds = segments.map((s) => s.id);
-
-  // For partial navigation, nullify components the client already has
-  // 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);
-  for (const segment of segments) {
-    if (!ctx.isFullMatch && !paramsChanged && ctx.clientSegmentSet.has(segment.id)) {
-      segment.component = null;
-      segment.loading = undefined;
-    }
-    yield segment;
-  }
+  const loaderStart = performance.now();
 
-  // Resolve loaders fresh (loaders are never pre-rendered/cached)
   if (ctx.isFullMatch) {
     if (resolveLoadersOnly) {
       const loaderSegments = await ctx.Store.run(() =>
@@ -195,6 +192,9 @@ async function* yieldFromStore<TEnv>(
           ctx.url,
           ctx.routeKey,
           ctx.actionContext,
+          // Loaders are never cached in the segment cache, so segment staleness
+          // must not propagate; browser-sent staleness (ctx.stale) still must.
+          ctx.stale || undefined,
         ),
       );
       state.matchedIds = [
@@ -209,17 +209,136 @@ 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-hit",
+      duration: loaderEnd - pipelineStart,
+      startTime: pipelineStart - ms.requestStart,
+    });
+  }
+}
+
+async function* yieldFromStore<TEnv>(
+  entry: PrerenderEntry,
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  pipelineStart: number,
+  handleStoreRef?: HandleStore,
+): AsyncGenerator<ResolvedSegment> {
+  const { resolveLoadersOnlyWithRevalidation, resolveLoadersOnly } =
+    getRouterContext<TEnv>();
+
+  if (
+    !_deserializeSegments ||
+    !_restoreHandles ||
+    !_decodeHandles ||
+    !_hashParams ||
+    !_lazyGetRequestContext
+  ) {
+    throw new Error("yieldFromStore called before ensurePrerenderDeps");
+  }
+
+  const segments = await _deserializeSegments(entry.segments);
+
+  // Replay handle data (same as runtime cache hit path). entry.handles is a
+  // Flight-encoded string ("" when none) — decode before restore so
+  // Promise/ReactNode handle values are revived, not the corrupted JSON form.
+  const handleStore = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
+  if (handleStore && entry.handles) {
+    const handlesRecord = await _decodeHandles(entry.handles);
+    if (handlesRecord) {
+      _restoreHandles(handlesRecord, handleStore);
+    }
+  }
+
+  state.cacheHit = true;
+  state.cacheSource = "prerender";
+  state.cachedSegments = segments;
+  state.cachedMatchedIds = segments.map((s) => s.id);
+
+  // Set streaming flag (once) and resolve render barrier.
+  const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
+  const barrierReqCtx = reqCtx ?? _getRequestContext();
+  if (barrierReqCtx) {
+    if (barrierReqCtx._treeHasStreaming === undefined) {
+      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+    barrierReqCtx._resolveRenderBarrier(segments);
+  }
+
+  // For partial navigation, nullify components the client already has
+  // 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 && !paramsEqual(ctx.matched.params, ctx.prevParams);
+  for (const segment of segments) {
+    if (
+      !ctx.isFullMatch &&
+      !paramsChanged &&
+      ctx.clientSegmentSet.has(segment.id)
+    ) {
+      segment.component = null;
+      segment.loading = undefined;
+    }
+    yield segment;
   }
+
+  // Resolve loaders fresh (loaders are never pre-rendered/cached).
+  yield* resolveFreshLoadersAndYield(
+    ctx,
+    state,
+    pipelineStart,
+    ctx.metricsStore,
+    resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation,
+  );
+}
+
+/**
+ * Look up a prerendered (build-time cached) entry for the current route and, on
+ * a hit, yield its segments. Returns true when an entry was served (the caller
+ * should stop the pipeline) and false on a miss. Intercept navigations consult
+ * only the intercept-specific entry (`paramHash + "/i"`); a miss there falls
+ * through to the normal pipeline so intercept-resolution can run. Callers must
+ * guard on `prerenderStoreInstance` after `ensurePrerenderDeps()`.
+ */
+async function* tryPrerenderLookup<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  pipelineStart: number,
+  handleStoreRef?: HandleStore,
+): AsyncGenerator<ResolvedSegment, boolean> {
+  const paramHash = _hashParams!(ctx.matched.params);
+  const isPassthroughPrerenderRoute = ctx.entries.some(
+    (entry) => entry.type === "route" && entry.isPassthrough === true,
+  );
+  const lookupHash = ctx.isIntercept ? paramHash + "/i" : paramHash;
+  const entry = await prerenderStoreInstance!.get(
+    ctx.matched.routeKey,
+    lookupHash,
+    {
+      pathname: ctx.pathname,
+      isPassthroughRoute: isPassthroughPrerenderRoute,
+    },
+  );
+  if (!entry) return false;
+  yield* yieldFromStore(entry, ctx, state, pipelineStart, handleStoreRef);
+  return true;
 }
 
 /**
  * Async generator middleware type
  */
 export type GeneratorMiddleware<T> = (
-  source: AsyncGenerator<T>
+  source: AsyncGenerator<T>,
 ) => AsyncGenerator<T>;
 
 /**
@@ -237,14 +356,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,
@@ -252,108 +378,156 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    // Prerender lookup: check build-time cached data before runtime cache.
-    // Prerender data is available regardless of runtime cache configuration.
-    if (!ctx.isAction && ctx.matched.pr) {
+    const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
+    if (!ctx.isAction && !isHmr && ctx.matched.pr) {
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
-        const paramHash = _hashParams!(ctx.matched.params);
-        const entry = await prerenderStoreInstance.get(
-          ctx.matched.routeKey, paramHash, { pathname: ctx.pathname }
+        const served = yield* tryPrerenderLookup(
+          ctx,
+          state,
+          pipelineStart,
+          handleStoreRef,
         );
-        if (entry) {
-          yield* yieldFromStore(entry, ctx, state, pipelineStart);
-          return;
-        }
+        if (served) return;
       }
     }
 
-    // Dev-mode static handler interception for non-Node.js runtimes.
-    // __PRERENDER_DEV_URL is set by the Vite plugin when the RSC environment
-    // lacks a Node.js module runner (e.g. workerd, Deno workers). In those
-    // runtimes, handlers that depend on Node APIs like node:fs can't run
-    // in-process. We redirect them to the /__rsc_prerender endpoint which
-    // resolves segments in a Node.js temp server, same as prerender routes.
-    // In Node.js dev mode this variable is undefined -- handlers run
-    // 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 served = yield* tryPrerenderLookup(
+            ctx,
+            state,
+            pipelineStart,
+            handleStoreRef,
           );
-          if (entry) {
-            yield* yieldFromStore(entry, ctx, state, pipelineStart);
-            return;
-          }
+          if (served) return;
         }
       }
     }
 
-    // Skip cache during actions
     if (ctx.isAction || !ctx.cacheScope?.enabled) {
-      // 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-miss",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
       }
       return;
     }
 
-    // Lookup cache
     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-miss",
+          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);
+    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;
       }
 
-      // Skip intercept segments - they're handled separately
       if (segment.namespace?.startsWith("intercept:")) {
         yield segment;
         continue;
       }
 
-      // Look up revalidation rules for this segment
       const entryInfo = entryRevalidateMap?.get(segment.id);
+
+      const searchChanged = ctx.prevUrl.search !== ctx.url.search;
+      const routeParamsChanged = !paramsEqual(
+        ctx.matched.params,
+        ctx.prevParams,
+      );
+      const shouldDefaultRevalidate =
+        (searchChanged || routeParamsChanged) &&
+        (segment.type === "route" ||
+          (segment.belongsToRoute &&
+            (segment.type === "layout" || segment.type === "parallel")));
+
       if (!entryInfo || entryInfo.revalidate.length === 0) {
-        // No revalidation rules, use default behavior (skip if client has)
+        if (shouldDefaultRevalidate) {
+          if (isTraceActive()) {
+            pushRevalidationTraceEntry({
+              segmentId: segment.id,
+              segmentType: segment.type,
+              belongsToRoute: segment.belongsToRoute ?? false,
+              source: "cache-hit",
+              defaultShouldRevalidate: true,
+              finalShouldRevalidate: true,
+              reason: routeParamsChanged
+                ? "cached-params-changed"
+                : "cached-search-changed",
+            });
+          }
+          yield segment;
+          continue;
+        }
+        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;
         continue;
       }
 
-      // Evaluate revalidation rules
       const shouldRevalidate = await evaluateRevalidation({
         segment,
         prevParams: ctx.prevParams,
@@ -368,10 +542,20 @@ export function withCacheLookup<TEnv>(
         routeKey: ctx.routeKey,
         context: ctx.handlerContext,
         actionContext: ctx.actionContext,
+        stale: cacheResult.shouldRevalidate || ctx.stale || undefined,
+        traceSource: "cache-hit",
+      });
+
+      observeEvent({
+        type: "revalidation.decision",
+        timestamp: performance.now(),
+        segmentId: segment.id,
+        pathname: ctx.pathname,
+        routeKey: ctx.routeKey,
+        shouldRevalidate,
       });
 
       if (!shouldRevalidate) {
-        // Client has it, no revalidation needed
         segment.component = null;
         segment.loading = undefined;
       }
@@ -379,60 +563,23 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    // Resolve loaders fresh (loaders are NOT cached by default)
-    // This ensures fresh data even on cache hit
-    const Store = ctx.Store;
-
-    if (ctx.isFullMatch) {
-      // Full match (document request) - simple loader resolution without revalidation
-      if (resolveLoadersOnly) {
-        const loaderSegments = await Store.run(() =>
-          resolveLoadersOnly(ctx.entries, ctx.handlerContext)
-        );
-
-        // Update state - full match doesn't track matchedIds separately
-        state.matchedIds = state.cachedMatchedIds!;
-
-        // Yield fresh loader segments
-        for (const segment of loaderSegments) {
-          yield segment;
-        }
-      } else {
-        state.matchedIds = state.cachedMatchedIds!;
-      }
-    } else {
-      // Partial match (navigation) - loader resolution with revalidation
-      if (resolveLoadersOnlyWithRevalidation) {
-        const loaderResult = await Store.run(() =>
-          resolveLoadersOnlyWithRevalidation(
-            ctx.entries,
-            ctx.handlerContext,
-            ctx.clientSegmentSet,
-            ctx.prevParams,
-            ctx.request,
-            ctx.prevUrl,
-            ctx.url,
-            ctx.routeKey,
-            ctx.actionContext
-          )
-        );
-
-        // Update state with fresh loader matchedIds
-        state.matchedIds = [
-          ...state.cachedMatchedIds!,
-          ...loaderResult.matchedIds,
-        ];
-
-        // Yield fresh loader segments
-        for (const segment of loaderResult.segments) {
-          yield segment;
-        }
-      } else {
-        state.matchedIds = state.cachedMatchedIds!;
+    const barrierReqCtx = _getRequestContext();
+    if (barrierReqCtx) {
+      if (barrierReqCtx._treeHasStreaming === undefined) {
+        barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
       }
+      barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
     }
-    if (ms) {
-      ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
-    }
+
+    // Resolve loaders fresh (loaders are never cached). Shared with the
+    // prerender-store path via resolveFreshLoadersAndYield.
+    yield* resolveFreshLoadersAndYield(
+      ctx,
+      state,
+      pipelineStart,
+      ms,
+      resolveLoadersOnly,
+      resolveLoadersOnlyWithRevalidation,
+    );
   };
 }