@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/router/match-handlers.ts

@@ -22,9 +22,21 @@ import {
   matchError as _matchError,
 } from "./match-api.js";
 import { previewMatch as _previewMatch } from "./preview-match.js";
-import { runWithRouterLogContext, withRouterLogScope } from "./logging.js";
+import {
+  runWithRouterLogContext,
+  withRouterLogScope,
+  isRouterDebugEnabled,
+  startRevalidationTrace,
+  flushRevalidationTrace,
+} from "./logging.js";
 import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
+import {
+  type TelemetrySink,
+  safeEmit,
+  resolveSink,
+  getRequestId,
+} from "./telemetry.js";
 
 export interface MatchHandlerDeps<TEnv = any> {
   buildRouterContext: () => RouterContext<TEnv>;
@@ -38,6 +50,7 @@ export interface MatchHandlerDeps<TEnv = any> {
     selectorContext: InterceptSelectorContext | null,
     isAction: boolean,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
+  telemetry?: TelemetrySink;
 }
 
 export interface MatchHandlers<TEnv = any> {
@@ -98,6 +111,8 @@ export function createMatchHandlers<TEnv = any>(
     defaultErrorBoundary,
     findInterceptForRoute,
   } = deps;
+  const hasTelemetry = !!deps.telemetry;
+  const telemetry = resolveSink(deps.telemetry);
 
   async function createMatchContextForFull(
     request: Request,
@@ -140,13 +155,43 @@ export function createMatchHandlers<TEnv = any>(
    * - background-revalidation: SWR revalidation
    */
   async function match(request: Request, env: TEnv): Promise<MatchResult> {
-    return runWithRouterLogContext({ request, transaction: "match" }, () =>
-      runWithRouterContext(buildRouterContext(), async () =>
+    const requestId = hasTelemetry ? getRequestId(request) : undefined;
+    return runWithRouterLogContext({ request, transaction: "match" }, () => {
+      const routerCtx = buildRouterContext();
+      routerCtx.requestId = requestId;
+      return runWithRouterContext(routerCtx, async () =>
         withRouterLogScope("match", async () => {
+          const matchStart = performance.now();
+          const pathname = new URL(request.url).pathname;
+          if (hasTelemetry) {
+            safeEmit(telemetry, {
+              type: "request.start",
+              timestamp: matchStart,
+              requestId,
+              method: request.method,
+              pathname,
+              transaction: "match",
+              isPartial: false,
+            });
+          }
+
           const result = await createMatchContextForFull(request, env);
 
           // Handle redirect case
           if ("type" in result && result.type === "redirect") {
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "request.end",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                durationMs: performance.now() - matchStart,
+                segmentCount: 0,
+                cacheHit: false,
+              });
+            }
             return {
               segments: [],
               matched: [],
@@ -161,8 +206,47 @@ export function createMatchHandlers<TEnv = any>(
           try {
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
-            return await collectMatchResult(pipeline, ctx, state);
+            const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "cache.decision",
+                timestamp: performance.now(),
+                requestId,
+                pathname,
+                routeKey: ctx.routeKey,
+                hit: state.cacheHit,
+                shouldRevalidate: !!state.shouldRevalidate,
+                source: state.cacheSource,
+              });
+              safeEmit(telemetry, {
+                type: "request.end",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                durationMs: performance.now() - matchStart,
+                segmentCount: matchResult.segments.length,
+                cacheHit: state.cacheHit,
+              });
+            }
+            return matchResult;
           } catch (error) {
+            if (hasTelemetry) {
+              const errorObj =
+                error instanceof Error ? error : new Error(String(error));
+              safeEmit(telemetry, {
+                type: "request.error",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                error: errorObj,
+                phase: error instanceof Response ? "redirect" : "routing",
+                durationMs: performance.now() - matchStart,
+              });
+            }
             if (error instanceof Response) throw error;
             // Report unhandled errors during full match pipeline
             callOnError(error, "routing", {
@@ -175,8 +259,8 @@ export function createMatchHandlers<TEnv = any>(
             throw sanitizeError(error);
           }
         }),
-      ),
-    );
+      );
+    });
   }
 
   async function matchError(
@@ -214,23 +298,112 @@ export function createMatchHandlers<TEnv = any>(
     context: TEnv,
     actionContext?: ActionContext,
   ): Promise<MatchResult | null> {
+    const partialRequestId = hasTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext(
       { request, transaction: "matchPartial" },
-      () =>
-        runWithRouterContext(buildRouterContext(), async () =>
+      () => {
+        const routerCtx = buildRouterContext();
+        routerCtx.requestId = partialRequestId;
+        return runWithRouterContext(routerCtx, async () =>
           withRouterLogScope("matchPartial", async () => {
+            const matchStart = performance.now();
+            const pathname = new URL(request.url).pathname;
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "request.start",
+                timestamp: matchStart,
+                requestId: partialRequestId,
+                method: request.method,
+                pathname,
+                transaction: "matchPartial",
+                isPartial: true,
+              });
+            }
+
             const ctx = await createMatchContextForPartial(
               request,
               context,
               actionContext,
             );
-            if (!ctx) return null;
+            if (!ctx) {
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "request.end",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  durationMs: performance.now() - matchStart,
+                  segmentCount: 0,
+                  cacheHit: false,
+                });
+              }
+              return null;
+            }
+
+            if (isRouterDebugEnabled()) {
+              startRevalidationTrace({
+                method: request.method,
+                prevUrl: ctx.prevUrl.href,
+                nextUrl: ctx.url.href,
+                routeKey: ctx.routeKey,
+                isAction: !!actionContext,
+                stale: ctx.stale || undefined,
+              });
+            }
 
             try {
               const state = createPipelineState();
               const pipeline = createMatchPartialPipeline(ctx, state);
-              return await collectMatchResult(pipeline, ctx, state);
+              const matchResult = await collectMatchResult(
+                pipeline,
+                ctx,
+                state,
+              );
+              flushRevalidationTrace();
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "cache.decision",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  pathname,
+                  routeKey: ctx.routeKey,
+                  hit: state.cacheHit,
+                  shouldRevalidate: !!state.shouldRevalidate,
+                  source: state.cacheSource,
+                });
+                safeEmit(telemetry, {
+                  type: "request.end",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  durationMs: performance.now() - matchStart,
+                  segmentCount: matchResult.segments.length,
+                  cacheHit: state.cacheHit,
+                });
+              }
+              return matchResult;
             } catch (error) {
+              flushRevalidationTrace();
+              if (hasTelemetry) {
+                const errorObj =
+                  error instanceof Error ? error : new Error(String(error));
+                const phase = actionContext ? "action" : "revalidation";
+                safeEmit(telemetry, {
+                  type: "request.error",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  error: errorObj,
+                  phase: error instanceof Response ? "redirect" : phase,
+                  durationMs: performance.now() - matchStart,
+                });
+              }
               if (error instanceof Response) throw error;
               // Report unhandled errors during partial match pipeline
               callOnError(error, actionContext ? "action" : "revalidation", {
@@ -244,7 +417,8 @@ export function createMatchHandlers<TEnv = any>(
               throw sanitizeError(error);
             }
           }),
-        ),
+        );
+      },
     );
   }
 

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,6 +92,8 @@
 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 {
@@ -185,6 +187,7 @@ async function* yieldFromStore<TEnv>(
   }
 
   state.cacheHit = true;
+  state.cacheSource = "prerender";
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
@@ -306,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(
@@ -331,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(
@@ -367,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(
@@ -389,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(
@@ -442,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);
@@ -460,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;
       }
@@ -474,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;
@@ -495,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;
@@ -541,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,