@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d5d3070a

package/src/router/match-handlers.ts

@@ -33,10 +33,13 @@ import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import {
   type TelemetrySink,
+  type CacheSegmentSignal,
   safeEmit,
   resolveSink,
   getRequestId,
+  buildCacheSignalSegments,
 } from "./telemetry.js";
+import { _getRequestContext } from "../server/request-context.js";
 
 export interface MatchHandlerDeps<TEnv = any> {
   buildRouterContext: () => RouterContext<TEnv>;
@@ -51,6 +54,12 @@ export interface MatchHandlerDeps<TEnv = any> {
     isAction: boolean,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
   telemetry?: TelemetrySink;
+  /**
+   * DEVELOPMENT/TEST ONLY gate for the X-Rango-Cache debug header. When true,
+   * match/matchPartial stash a coarse route-level cache signal on the request
+   * context for the response-finalization path to emit. Default off.
+   */
+  cacheSignalEnabled?: boolean;
 }
 
 export interface MatchHandlers<TEnv = any> {
@@ -80,20 +89,6 @@ export interface MatchHandlers<TEnv = any> {
     negotiated?: boolean;
     manifestEntry?: EntryData;
   } | null>;
-  createMatchContextForFull: (
-    request: Request,
-    env: TEnv,
-  ) => Promise<MatchContext<TEnv> | { type: "redirect"; redirectUrl: string }>;
-  createMatchContextForPartial: (
-    request: Request,
-    env: TEnv,
-    actionContext?: {
-      actionId?: string;
-      actionUrl?: URL;
-      actionResult?: any;
-      formData?: FormData;
-    },
-  ) => Promise<MatchContext<TEnv> | null>;
 }
 
 /**
@@ -113,6 +108,20 @@ export function createMatchHandlers<TEnv = any>(
   } = deps;
   const hasTelemetry = !!deps.telemetry;
   const telemetry = resolveSink(deps.telemetry);
+  const cacheSignalEnabled = !!deps.cacheSignalEnabled;
+  const buildSignal = (
+    routeKey: string,
+    state: {
+      cacheHit: boolean;
+      cacheSource?: "runtime" | "prerender";
+      shouldRevalidate?: boolean;
+    },
+  ): CacheSegmentSignal[] => buildCacheSignalSegments(routeKey, state);
+  const recordSignalIfEnabled = (segments: CacheSegmentSignal[]): void => {
+    if (!cacheSignalEnabled) return;
+    const reqCtx = _getRequestContext();
+    if (reqCtx) reqCtx._cacheSignal = segments;
+  };
 
   async function createMatchContextForFull(
     request: Request,
@@ -145,15 +154,6 @@ export function createMatchHandlers<TEnv = any>(
     );
   }
 
-  /**
-   * Match request and return segments (document/SSR requests)
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
   async function match(request: Request, env: TEnv): Promise<MatchResult> {
     const requestId = hasTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext({ request, transaction: "match" }, () => {
@@ -177,7 +177,6 @@ export function createMatchHandlers<TEnv = any>(
 
           const result = await createMatchContextForFull(request, env);
 
-          // Handle redirect case
           if ("type" in result && result.type === "redirect") {
             if (hasTelemetry) {
               safeEmit(telemetry, {
@@ -196,6 +195,7 @@ export function createMatchHandlers<TEnv = any>(
               segments: [],
               matched: [],
               diff: [],
+              resolvedIds: [],
               params: {},
               redirect: result.redirectUrl,
             };
@@ -207,17 +207,24 @@ export function createMatchHandlers<TEnv = any>(
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
             const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (hasTelemetry || cacheSignalEnabled) {
+              const signalSegments = buildSignal(ctx.routeKey, state);
+              recordSignalIfEnabled(signalSegments);
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "cache.decision",
+                  timestamp: performance.now(),
+                  requestId,
+                  pathname,
+                  routeKey: ctx.routeKey,
+                  hit: state.cacheHit,
+                  shouldRevalidate: !!state.shouldRevalidate,
+                  source: state.cacheSource,
+                  segments: signalSegments,
+                });
+              }
+            }
             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(),
@@ -248,7 +255,6 @@ export function createMatchHandlers<TEnv = any>(
               });
             }
             if (error instanceof Response) throw error;
-            // Report unhandled errors during full match pipeline
             callOnError(error, "routing", {
               request,
               url: ctx.url,
@@ -283,16 +289,6 @@ export function createMatchHandlers<TEnv = any>(
     );
   }
 
-  /**
-   * Match partial request with revalidation
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - intercept-resolution: Handle intercept routes
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
   async function matchPartial(
     request: Request,
     context: TEnv,
@@ -362,17 +358,24 @@ export function createMatchHandlers<TEnv = any>(
                 state,
               );
               flushRevalidationTrace();
+              if (hasTelemetry || cacheSignalEnabled) {
+                const signalSegments = buildSignal(ctx.routeKey, state);
+                recordSignalIfEnabled(signalSegments);
+                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,
+                    segments: signalSegments,
+                  });
+                }
+              }
               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(),
@@ -405,7 +408,6 @@ export function createMatchHandlers<TEnv = any>(
                 });
               }
               if (error instanceof Response) throw error;
-              // Report unhandled errors during partial match pipeline
               callOnError(error, actionContext ? "action" : "revalidation", {
                 request,
                 url: ctx.url,
@@ -434,7 +436,5 @@ export function createMatchHandlers<TEnv = any>(
     matchPartial: matchPartial,
     matchError: matchError,
     previewMatch: previewMatch,
-    createMatchContextForFull: createMatchContextForFull,
-    createMatchContextForPartial: createMatchContextForPartial,
   };
 }

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

@@ -149,6 +149,13 @@ export function withBackgroundRevalidation<TEnv>(
       : undefined;
 
     requestCtx?.waitUntil(async () => {
+      // Prevent background metrics from polluting foreground timeline.
+      // The foreground uses its own metricsStore reference directly (via
+      // appendMetric), so nulling Store.metrics only affects track() calls
+      // inside this background Store.run() scope.
+      const savedMetrics = ctx.Store.metrics;
+      ctx.Store.metrics = undefined;
+
       const start = performance.now();
       debugLog("backgroundRevalidation", "revalidating stale route", {
         pathname: ctx.pathname,
@@ -161,8 +168,6 @@ export function withBackgroundRevalidation<TEnv>(
       requestCtx._handleStore = createHandleStore();
 
       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,
@@ -178,8 +183,6 @@ export function withBackgroundRevalidation<TEnv>(
         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,
@@ -187,10 +190,10 @@ export function withBackgroundRevalidation<TEnv>(
             ctx.matched.params,
             freshHandlerContext,
             freshLoaderPromises,
+            { skipLoaders: true },
           ),
         );
 
-        // Also resolve intercept segments fresh if applicable
         let freshInterceptSegments: ResolvedSegment[] = [];
         if (ctx.interceptResult) {
           freshInterceptSegments = await ctx.Store.run(() =>
@@ -200,6 +203,12 @@ export function withBackgroundRevalidation<TEnv>(
               ctx.matched.params,
               freshHandlerContext,
               true,
+              undefined,
+              // Skip intercept middleware: this is a post-response background
+              // re-render to refresh a stale cached route. The foreground
+              // already ran the middleware; re-running it would double its side
+              // effects and a short-circuit Response would abort the write.
+              { skipMiddleware: true },
             ),
           );
         }
@@ -234,6 +243,7 @@ export function withBackgroundRevalidation<TEnv>(
         });
       } finally {
         requestCtx._handleStore = originalHandleStore;
+        ctx.Store.metrics = savedMetrics;
       }
     });
   };