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

package/src/router/match-middleware/background-revalidation.ts

@@ -30,23 +30,15 @@
  *         |
  *         v (async, doesn't block response)
  *   +---------------------------+
- *   | Create fresh handleStore |  Isolate from response stream
+ *   | Create fresh context     |  Fresh handleStore, handlerContext,
+ *   | (full isolation)         |  and loaderPromises map
  *   +---------------------------+
  *         |
  *         v
- *   +---------------------+
- *   | isFullMatch?        |
- *   +---------------------+
- *         |
- *   +-----+-----+
- *   |           |
- *  yes          no
- *   |           |
- *   v           v
- * resolveAll  resolveWithRevalidation
- * Segments    + resolveIntercepts
- *   |           |
- *   +-----------+
+ *   +---------------------------+
+ *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
+ *   | + resolveIntercepts()   |  Ensures complete components
+ *   +---------------------------+
  *         |
  *         v
  *   +---------------------------+
@@ -90,27 +82,22 @@
  * ISOLATION FROM RESPONSE
  * =======================
  *
- * The background revalidation creates a fresh handleStore:
- *
- *   requestCtx._handleStore = createHandleStore();
+ * Background revalidation creates fully isolated context:
+ *   - Fresh handleStore (prevents polluting the response stream)
+ *   - Fresh handlerContext + loaderPromises (prevents reusing memoized
+ *     loader results from the foreground pass)
+ *   - handleStore is saved/restored in try/finally
  *
- * This prevents background handle.push() calls from:
- *   - Polluting the current response stream
- *   - Causing duplicate data in the client
- *   - Creating race conditions
+ * This matches the proactive caching pattern in cache-store.ts.
  *
  *
- * FULL VS PARTIAL REVALIDATION
- * ============================
+ * FRESH RESOLUTION (NO REVALIDATION)
+ * ===================================
  *
- * Full Match (document request):
- *   - Simple resolveAllSegments()
- *   - No need to compare with previous state
- *
- * Partial Match (navigation):
- *   - resolveAllSegmentsWithRevalidation()
- *   - Also resolves intercept segments if applicable
- *   - More complex but handles all scenarios
+ * Both full and partial requests use resolveAllSegments() (without
+ * revalidation logic) to ensure all segments have complete components.
+ * Using revalidation-aware resolution would produce null components
+ * for skipped segments, which would corrupt the cache entry.
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
@@ -148,7 +135,8 @@ export function withBackgroundRevalidation<TEnv>(
     const {
       getRequestContext,
       createHandleStore,
-      resolveAllSegmentsWithRevalidation,
+      createHandlerContext,
+      setupLoaderAccess,
       resolveAllSegments,
       resolveInterceptEntry,
     } = getRouterContext<TEnv>();
@@ -161,72 +149,62 @@ export function withBackgroundRevalidation<TEnv>(
         pathname: ctx.pathname,
         fullMatch: ctx.isFullMatch,
       });
-      try {
-        // Create a fresh handleStore for background revalidation
-        // to avoid polluting the current response's handle stream
-        if (requestCtx) {
-          requestCtx._handleStore = createHandleStore();
-        }
 
-        let freshSegments: ResolvedSegment[];
+      // Save and replace handleStore to avoid polluting the response stream.
+      // Restore in finally (same pattern as proactive caching in cache-store).
+      const originalHandleStore = requestCtx._handleStore;
+      requestCtx._handleStore = createHandleStore();
 
-        if (ctx.isFullMatch) {
-          // Full match (document request) - simple resolution
-          freshSegments = await resolveAllSegments(
-            ctx.entries,
-            ctx.routeKey,
-            ctx.matched.params,
-            ctx.handlerContext,
-            ctx.loaderPromises,
-          );
-        } else {
-          // Partial match (navigation) - resolution with revalidation
-          const freshResult = await resolveAllSegmentsWithRevalidation(
+      try {
+        // Create fresh handler context and loader promises to avoid
+        // reusing memoized results from the foreground pass
+        const freshHandlerContext = createHandlerContext(
+          ctx.matched.params,
+          ctx.request,
+          ctx.url.searchParams,
+          ctx.pathname,
+          ctx.url,
+          ctx.env,
+          ctx.routeMap,
+          ctx.matched.routeKey,
+          ctx.matched.responseType,
+          ctx.matched.pt === true,
+        );
+        const freshLoaderPromises = new Map<string, Promise<any>>();
+        setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
+
+        // Resolve all segments fresh (without revalidation logic)
+        // to ensure complete components for caching
+        const freshSegments = await ctx.Store.run(() =>
+          resolveAllSegments(
             ctx.entries,
             ctx.routeKey,
             ctx.matched.params,
-            ctx.handlerContext,
-            ctx.clientSegmentSet,
-            ctx.prevParams,
-            ctx.request,
-            ctx.prevUrl,
-            ctx.url,
-            ctx.loaderPromises,
-            ctx.actionContext,
-            ctx.interceptResult,
-            ctx.localRouteName,
-            ctx.pathname,
-          );
-
-          freshSegments = freshResult.segments;
+            freshHandlerContext,
+            freshLoaderPromises,
+          ),
+        );
 
-          // For intercept revalidation, also resolve fresh intercept segments
-          if (ctx.interceptResult) {
-            const freshInterceptSegments = await resolveInterceptEntry(
-              ctx.interceptResult.intercept,
-              ctx.interceptResult.entry,
+        // Also resolve intercept segments fresh if applicable
+        let freshInterceptSegments: ResolvedSegment[] = [];
+        if (ctx.interceptResult) {
+          freshInterceptSegments = await ctx.Store.run(() =>
+            resolveInterceptEntry(
+              ctx.interceptResult!.intercept,
+              ctx.interceptResult!.entry,
               ctx.matched.params,
-              ctx.handlerContext,
+              freshHandlerContext,
               true,
-              {
-                clientSegmentIds: ctx.clientSegmentSet,
-                prevParams: ctx.prevParams,
-                request: ctx.request,
-                prevUrl: ctx.prevUrl,
-                nextUrl: ctx.url,
-                routeKey: ctx.routeKey,
-                actionContext: ctx.actionContext,
-                stale: false,
-              },
-            );
-            freshSegments = [...freshSegments, ...freshInterceptSegments];
-          }
+            ),
+          );
         }
 
+        const completeSegments = [...freshSegments, ...freshInterceptSegments];
+        requestCtx._handleStore.seal();
         await cacheScope.cacheRoute(
           ctx.pathname,
           ctx.matched.params,
-          freshSegments,
+          completeSegments,
           ctx.isIntercept,
         );
         debugLog("backgroundRevalidation", "revalidation complete", {
@@ -237,6 +215,8 @@ export function withBackgroundRevalidation<TEnv>(
           pathname: ctx.pathname,
           error: String(error),
         });
+      } finally {
+        requestCtx._handleStore = originalHandleStore;
       }
     });
   };

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

@@ -92,9 +92,14 @@
 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 } from "../../server/request-context.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
@@ -109,7 +114,7 @@ let _restoreHandles:
 let _hashParams:
   | typeof import("../../prerender/param-hash.js").hashParams
   | undefined;
-let _getRequestContext:
+let _lazyGetRequestContext:
   | typeof import("../../server/request-context.js").getRequestContext
   | undefined;
 
@@ -141,7 +146,7 @@ async function ensurePrerenderDeps() {
     _deserializeSegments = codec.deserializeSegments;
     _restoreHandles = snapshot.restoreHandles;
     _hashParams = paramHash.hashParams;
-    _getRequestContext = reqCtx.getRequestContext;
+    _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
       prerenderStoreInstance = store.createPrerenderStore();
     }
@@ -167,7 +172,7 @@ async function* yieldFromStore<TEnv>(
     !_deserializeSegments ||
     !_restoreHandles ||
     !_hashParams ||
-    !_getRequestContext
+    !_lazyGetRequestContext
   ) {
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
@@ -176,12 +181,13 @@ async function* yieldFromStore<TEnv>(
 
   // Replay handle data (same as runtime cache hit path).
   // Prefer the eagerly-captured handleStoreRef to avoid ALS disruption in workerd.
-  const handleStore = handleStoreRef ?? _getRequestContext()?._handleStore;
+  const handleStore = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
   if (handleStore) {
     _restoreHandles(entry.handles, handleStore);
   }
 
   state.cacheHit = true;
+  state.cacheSource = "prerender";
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
@@ -288,7 +294,7 @@ export function withCacheLookup<TEnv>(
     // 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 handleStoreRef = _getRequestContext()?._handleStore;
 
     const {
       evaluateRevalidation,
@@ -303,13 +309,21 @@ export function withCacheLookup<TEnv>(
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
         const paramHash = _hashParams!(ctx.matched.params);
+        const isPassthroughPrerenderRoute = ctx.entries.some(
+          (entry) =>
+            entry.type === "route" &&
+            entry.prerenderDef?.options?.passthrough === true,
+        );
 
         if (ctx.isIntercept) {
           // Intercept navigation: try intercept-specific prerender entry
           const entry = await prerenderStoreInstance.get(
             ctx.matched.routeKey,
             paramHash + "/i",
-            { pathname: ctx.pathname },
+            {
+              pathname: ctx.pathname,
+              isPassthroughRoute: isPassthroughPrerenderRoute,
+            },
           );
           if (entry) {
             yield* yieldFromStore(
@@ -328,7 +342,10 @@ export function withCacheLookup<TEnv>(
           const entry = await prerenderStoreInstance.get(
             ctx.matched.routeKey,
             paramHash,
-            { pathname: ctx.pathname },
+            {
+              pathname: ctx.pathname,
+              isPassthroughRoute: isPassthroughPrerenderRoute,
+            },
           );
           if (entry) {
             yield* yieldFromStore(
@@ -364,12 +381,20 @@ export function withCacheLookup<TEnv>(
         await ensurePrerenderDeps();
         if (prerenderStoreInstance) {
           const paramHash = _hashParams!(ctx.matched.params);
+          const isPassthroughPrerenderRoute = ctx.entries.some(
+            (entry) =>
+              entry.type === "route" &&
+              entry.prerenderDef?.options?.passthrough === true,
+          );
 
           if (ctx.isIntercept) {
             const entry = await prerenderStoreInstance.get(
               ctx.matched.routeKey,
               paramHash + "/i",
-              { pathname: ctx.pathname },
+              {
+                pathname: ctx.pathname,
+                isPassthroughRoute: isPassthroughPrerenderRoute,
+              },
             );
             if (entry) {
               yield* yieldFromStore(
@@ -386,7 +411,10 @@ export function withCacheLookup<TEnv>(
             const entry = await prerenderStoreInstance.get(
               ctx.matched.routeKey,
               paramHash,
-              { pathname: ctx.pathname },
+              {
+                pathname: ctx.pathname,
+                isPassthroughRoute: isPassthroughPrerenderRoute,
+              },
             );
             if (entry) {
               yield* yieldFromStore(
@@ -439,6 +467,7 @@ export function withCacheLookup<TEnv>(
 
     // Cache HIT
     state.cacheHit = true;
+    state.cacheSource = "runtime";
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
@@ -457,6 +486,17 @@ export function withCacheLookup<TEnv>(
     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;
       }
@@ -471,6 +511,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;
@@ -492,8 +543,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;
@@ -538,6 +605,7 @@ export function withCacheLookup<TEnv>(
             ctx.url,
             ctx.routeKey,
             ctx.actionContext,
+            cacheResult.shouldRevalidate || undefined,
           ),
         );
 

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

@@ -211,6 +211,7 @@ export function withCacheStore<TEnv>(
               ctx.routeMap,
               ctx.matched.routeKey,
               ctx.matched.responseType,
+              ctx.matched.pt === true,
             );
             const proactiveLoaderPromises = new Map<string, Promise<any>>();
 
@@ -248,6 +249,7 @@ export function withCacheStore<TEnv>(
               ...freshSegments,
               ...freshInterceptSegments,
             ];
+            requestCtx._handleStore.seal();
             await cacheScope.cacheRoute(
               ctx.pathname,
               ctx.matched.params,

package/src/router/match-pipelines.ts

@@ -86,19 +86,14 @@
  *     -> output: cached segments + fresh loader data
  *
  *
- * TWO PIPELINE VARIANTS
- * =====================
- *
- * 1. createMatchPipeline (Full Match)
- *    - Used for document requests (initial page load)
- *    - No revalidation logic (no previous state to compare)
- *    - Simpler segment resolution
- *
- * 2. createMatchPartialPipeline (Partial Match)
- *    - Used for client-side navigation
- *    - Includes revalidation for SWR
- *    - Compares with previous params/URL
- *    - Supports intercepts (soft navigation modals)
+ * PIPELINE VARIANT
+ * ================
+ *
+ * createMatchPartialPipeline handles both full (document) and partial
+ * (navigation) requests. The middleware steps adapt based on ctx.isFullMatch:
+ * - cache-lookup/store work for both
+ * - background-revalidation is a no-op for full matches (no stale state)
+ * - intercept-resolution is a no-op for full matches (no previous navigation)
  */
 import type { ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
@@ -182,33 +177,3 @@ export function createMatchPartialPipeline<TEnv>(
   // Start with empty source - cache lookup or segment resolution will produce segments
   return pipeline(empty());
 }
-
-/**
- * Create the full match pipeline (simpler, no revalidation)
- *
- * Used for document requests (initial page load) where we don't need
- * revalidation logic since there's no previous state to compare against.
- */
-export function createMatchPipeline<TEnv>(
-  ctx: MatchContext<TEnv>,
-  state: MatchPipelineState,
-): AsyncGenerator<ResolvedSegment> {
-  // For full match, we only need:
-  // 1. Cache lookup
-  // 2. Segment resolution (without revalidation)
-  // 3. Intercept resolution
-  // 4. Cache store
-
-  // Note: Full match uses different resolution logic (resolveAllSegments instead of
-  // resolveAllSegmentsWithRevalidation). This will be handled by the segment resolution
-  // middleware checking ctx.isFullMatch or similar flag.
-
-  const pipeline = compose<ResolvedSegment>(
-    withCacheStore(ctx, state),
-    withInterceptResolution(ctx, state),
-    withSegmentResolution(ctx, state),
-    withCacheLookup(ctx, state),
-  );
-
-  return pipeline(empty());
-}

package/src/router/match-result.ts

@@ -108,7 +108,6 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
-import { generateServerTiming, logMetrics } from "./metrics.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -186,20 +185,12 @@ export function buildMatchResult<TEnv>(
     segmentIds: segmentsToRender.map((s) => s.id),
   });
 
-  // Output metrics if enabled
-  let serverTiming: string | undefined;
-  if (ctx.metricsStore) {
-    logMetrics(ctx.request.method, ctx.pathname, ctx.metricsStore);
-    serverTiming = generateServerTiming(ctx.metricsStore);
-  }
-
   return {
     segments: segmentsToRender,
     matched: allIds,
     diff: segmentsToRender.map((s) => s.id),
     params: ctx.matched.params,
     routeName: ctx.routeKey,
-    serverTiming,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
     routeMiddleware:
       ctx.routeMiddleware.length > 0 ? ctx.routeMiddleware : undefined,