@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/src/router/match-handlers.ts

@@ -33,10 +33,116 @@ 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";
+
+/**
+ * Per-call telemetry lifecycle emitter for match()/matchPartial(). Each method
+ * reproduces the exact event object the two functions used to emit inline and is
+ * gated on the same per-call flag (`enabled` = the request's `emitTelemetry`), so
+ * a PPR shell-capture run (enabled=false) emits nothing while a foreground run
+ * emits byte-identical events. Extracted so the two transactions can't drift;
+ * pinned by thrown-response-telemetry.test.ts and
+ * shell-capture-telemetry-suppression.test.ts.
+ */
+interface LifecycleEmitter {
+  start(): void;
+  end(segmentCount: number, cacheHit: boolean, status?: number): void;
+  cacheDecision(
+    routeKey: string,
+    state: {
+      cacheHit: boolean;
+      cacheSource?: "runtime" | "prerender";
+      shouldRevalidate?: boolean;
+    },
+    segments: CacheSegmentSignal[],
+  ): void;
+  error(error: Error, phase: string): void;
+}
+
+function createLifecycleEmitter(args: {
+  enabled: boolean;
+  sink: TelemetrySink;
+  requestId: string | undefined;
+  method: string;
+  pathname: string;
+  transaction: "match" | "matchPartial";
+  isPartial: boolean;
+  matchStart: number;
+}): LifecycleEmitter {
+  return {
+    start(): void {
+      if (!args.enabled) return;
+      safeEmit(args.sink, {
+        type: "request.start",
+        timestamp: args.matchStart,
+        requestId: args.requestId,
+        method: args.method,
+        pathname: args.pathname,
+        transaction: args.transaction,
+        isPartial: args.isPartial,
+      });
+    },
+    end(segmentCount: number, cacheHit: boolean, status?: number): void {
+      if (!args.enabled) return;
+      safeEmit(args.sink, {
+        type: "request.end",
+        timestamp: performance.now(),
+        requestId: args.requestId,
+        method: args.method,
+        pathname: args.pathname,
+        transaction: args.transaction,
+        durationMs: performance.now() - args.matchStart,
+        segmentCount,
+        cacheHit,
+        // Only a thrown-Response short-circuit passes a status; a normal render
+        // completion omits it (the Response is built after match()).
+        ...(status !== undefined && { status }),
+      });
+    },
+    cacheDecision(
+      routeKey: string,
+      state: {
+        cacheHit: boolean;
+        cacheSource?: "runtime" | "prerender";
+        shouldRevalidate?: boolean;
+      },
+      segments: CacheSegmentSignal[],
+    ): void {
+      if (!args.enabled) return;
+      safeEmit(args.sink, {
+        type: "cache.decision",
+        timestamp: performance.now(),
+        requestId: args.requestId,
+        pathname: args.pathname,
+        routeKey,
+        hit: state.cacheHit,
+        shouldRevalidate: !!state.shouldRevalidate,
+        source: state.cacheSource,
+        segments,
+      });
+    },
+    error(error: Error, phase: string): void {
+      if (!args.enabled) return;
+      safeEmit(args.sink, {
+        type: "request.error",
+        timestamp: performance.now(),
+        requestId: args.requestId,
+        method: args.method,
+        pathname: args.pathname,
+        transaction: args.transaction,
+        error,
+        phase,
+        durationMs: performance.now() - args.matchStart,
+      });
+    },
+  };
+}
 
 export interface MatchHandlerDeps<TEnv = any> {
   buildRouterContext: () => RouterContext<TEnv>;
@@ -51,6 +157,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 +192,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 +211,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,57 +257,49 @@ 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;
+    // Silence telemetry for the PPR background shell capture: it re-runs match()
+    // under a derived request context flagged _shellCaptureRun (shell-capture.ts
+    // attemptCapture), re-using the foreground Request — a second request.start/
+    // cache.decision/request.end stamped with the same WeakMap-keyed requestId
+    // would double-count dashboards. Derived here (inside the capture's active
+    // request-context ALS) so the read sees the derived context, not module state.
+    const emitTelemetry =
+      hasTelemetry && !_getRequestContext()?._shellCaptureRun;
+    const requestId = emitTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext({ request, transaction: "match" }, () => {
       const routerCtx = buildRouterContext();
+      // Also mute in-pipeline observeEvent emitters (revalidation.decision,
+      // cache-lookup's cache.decision) which read routerCtx.telemetry.
+      if (!emitTelemetry) routerCtx.telemetry = undefined;
       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 pathname =
+            _getRequestContext()?.url?.pathname ??
+            new URL(request.url).pathname;
+          const emitter = createLifecycleEmitter({
+            enabled: emitTelemetry,
+            sink: telemetry,
+            requestId,
+            method: request.method,
+            pathname,
+            transaction: "match",
+            isPartial: false,
+            matchStart,
+          });
+          emitter.start();
 
           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,
-              });
-            }
+            emitter.end(0, false);
             return {
               segments: [],
               matched: [],
               diff: [],
+              resolvedIds: [],
               params: {},
               redirect: result.redirectUrl,
             };
@@ -207,48 +311,29 @@ export function createMatchHandlers<TEnv = any>(
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(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,
-              });
+            if (hasTelemetry || cacheSignalEnabled) {
+              const signalSegments = buildSignal(ctx.routeKey, state);
+              recordSignalIfEnabled(signalSegments);
+              emitter.cacheDecision(ctx.routeKey, state, signalSegments);
             }
+            emitter.end(matchResult.segments.length, 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) {
+              // A thrown Response (middleware short-circuit — redirect / auth
+              // gate) is a COMPLETED request from the consumer's seat, not an
+              // error: emit request.end (the same shape the non-thrown redirect
+              // result above already emits), never request.error with a
+              // synthetic "[object Response]" error. Rethrow so the caller
+              // drives the redirect. Carry the Response's status so a sink can
+              // tell a 3xx short-circuit from a 2xx completion.
+              emitter.end(0, false, error.status);
+              throw error;
             }
-            if (error instanceof Response) throw error;
-            // Report unhandled errors during full match pipeline
+            emitter.error(
+              error instanceof Error ? error : new Error(String(error)),
+              "routing",
+            );
             callOnError(error, "routing", {
               request,
               url: ctx.url,
@@ -283,42 +368,39 @@ 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,
     actionContext?: ActionContext,
   ): Promise<MatchResult | null> {
-    const partialRequestId = hasTelemetry ? getRequestId(request) : undefined;
+    // See match() above: the PPR shell capture re-runs matchPartial() under a
+    // _shellCaptureRun context and must stay invisible to the sink.
+    const emitTelemetry =
+      hasTelemetry && !_getRequestContext()?._shellCaptureRun;
+    const partialRequestId = emitTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext(
       { request, transaction: "matchPartial" },
       () => {
         const routerCtx = buildRouterContext();
+        if (!emitTelemetry) routerCtx.telemetry = undefined;
         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 pathname =
+              _getRequestContext()?.url?.pathname ??
+              new URL(request.url).pathname;
+            const emitter = createLifecycleEmitter({
+              enabled: emitTelemetry,
+              sink: telemetry,
+              requestId: partialRequestId,
+              method: request.method,
+              pathname,
+              transaction: "matchPartial",
+              isPartial: true,
+              matchStart,
+            });
+            emitter.start();
 
             const ctx = await createMatchContextForPartial(
               request,
@@ -326,19 +408,7 @@ export function createMatchHandlers<TEnv = any>(
               actionContext,
             );
             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,
-                });
-              }
+              emitter.end(0, false);
               return null;
             }
 
@@ -362,50 +432,28 @@ export function createMatchHandlers<TEnv = any>(
                 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,
-                });
+              if (hasTelemetry || cacheSignalEnabled) {
+                const signalSegments = buildSignal(ctx.routeKey, state);
+                recordSignalIfEnabled(signalSegments);
+                emitter.cacheDecision(ctx.routeKey, state, signalSegments);
               }
+              emitter.end(matchResult.segments.length, 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) {
+                // A thrown Response (middleware short-circuit — redirect / auth
+                // gate) is a COMPLETED request, not an error: emit request.end
+                // (parity with match()), never request.error. Rethrow so the
+                // caller drives the redirect. Carry the Response's status so a
+                // sink can tell a 3xx short-circuit from a 2xx completion.
+                emitter.end(0, false, error.status);
+                throw error;
               }
-              if (error instanceof Response) throw error;
-              // Report unhandled errors during partial match pipeline
+              emitter.error(
+                error instanceof Error ? error : new Error(String(error)),
+                actionContext ? "action" : "revalidation",
+              );
               callOnError(error, actionContext ? "action" : "revalidation", {
                 request,
                 url: ctx.url,
@@ -434,7 +482,5 @@ export function createMatchHandlers<TEnv = any>(
     matchPartial: matchPartial,
     matchError: matchError,
     previewMatch: previewMatch,
-    createMatchContextForFull: createMatchContextForFull,
-    createMatchContextForPartial: createMatchContextForPartial,
   };
 }

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

@@ -103,7 +103,12 @@ import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
-import { debugLog, debugWarn } from "../logging.js";
+import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
 
 /**
  * Creates background revalidation middleware
@@ -143,8 +148,19 @@ export function withBackgroundRevalidation<TEnv>(
 
     const requestCtx = getRequestContext();
     const cacheScope = ctx.cacheScope;
+    const reqId = INTERNAL_RANGO_DEBUG
+      ? getOrCreateRequestId(ctx.request)
+      : 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,
         fullMatch: ctx.isFullMatch,
@@ -156,8 +172,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,
@@ -173,29 +187,46 @@ 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,
-            ctx.routeKey,
-            ctx.matched.params,
-            freshHandlerContext,
-            freshLoaderPromises,
-          ),
+        // Re-establish the request-context ALS around the re-render. ctx.Store
+        // is a different ALS (DSL build context); on workerd a waitUntil task
+        // runs detached from the request's I/O context, so a handler/component
+        // that reads the ambient getRequestContext() during this background
+        // re-render would otherwise throw "called outside of a request context".
+        const freshSegments = await runWithRequestContext(
+          requestCtx as RequestContext<TEnv>,
+          () =>
+            ctx.Store.run(() =>
+              resolveAllSegments(
+                ctx.entries,
+                ctx.routeKey,
+                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(() =>
-            resolveInterceptEntry(
-              ctx.interceptResult!.intercept,
-              ctx.interceptResult!.entry,
-              ctx.matched.params,
-              freshHandlerContext,
-              true,
-            ),
+          freshInterceptSegments = await runWithRequestContext(
+            requestCtx as RequestContext<TEnv>,
+            () =>
+              ctx.Store.run(() =>
+                resolveInterceptEntry(
+                  ctx.interceptResult!.intercept,
+                  ctx.interceptResult!.entry,
+                  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 },
+                ),
+              ),
           );
         }
 
@@ -207,16 +238,29 @@ export function withBackgroundRevalidation<TEnv>(
           completeSegments,
           ctx.isIntercept,
         );
+        if (INTERNAL_RANGO_DEBUG) {
+          const dur = performance.now() - start;
+          console.log(
+            `[RSC Background][req:${reqId}] SWR revalidation ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+          );
+        }
         debugLog("backgroundRevalidation", "revalidation complete", {
           pathname: ctx.pathname,
         });
       } catch (error) {
+        if (INTERNAL_RANGO_DEBUG) {
+          const dur = performance.now() - start;
+          console.log(
+            `[RSC Background][req:${reqId}] SWR revalidation ${ctx.pathname} FAILED (${dur.toFixed(2)}ms) error=${String(error)}`,
+          );
+        }
         debugWarn("backgroundRevalidation", "revalidation failed", {
           pathname: ctx.pathname,
           error: String(error),
         });
       } finally {
         requestCtx._handleStore = originalHandleStore;
+        ctx.Store.metrics = savedMetrics;
       }
     });
   };