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

package/src/router/match-api.ts

@@ -26,6 +26,7 @@ import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.js";
 import {
   getRequestContext,
+  _getRequestContext,
   setRequestContextPrevRouteKey,
 } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
@@ -47,31 +48,67 @@ export async function createMatchContextForFull<TEnv>(
   deps: MatchApiDeps<TEnv>,
   findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"],
 ): Promise<MatchContext<TEnv> | { type: "redirect"; redirectUrl: string }> {
-  const url = new URL(request.url);
-  const pathname = url.pathname;
+  const reqCtx = _getRequestContext();
+  const cleanUrl = reqCtx?.url ?? stripInternalParams(new URL(request.url));
+  const pathname = cleanUrl.pathname;
 
   const metricsStore = deps.getMetricsStore();
 
-  const result = await resolveRoute<TEnv>(pathname, {
-    findMatch: (p) => deps.findMatch(p, metricsStore),
-    metricsStore,
-    isSSR: true,
-  });
+  const isHmr = !!request.headers.get("X-RSC-HMR");
+  // HMR: clear the manifest cache so stale handler references are discarded.
+  if (isHmr) {
+    clearManifestCache();
+  }
+
+  // Reuse the snapshot classifyRequest already resolved when it is a full-render
+  // snapshot (isSSR:true) and HMR has not invalidated it — mirrors the partial
+  // path. A partial-mode snapshot (isSSR:false) carries the wrong loading()
+  // entries and lives in a different manifest partition, so it is NOT reusable.
+  const classified = reqCtx?._classifiedRoute;
+  const classifiedRoute =
+    !isHmr && classified?.isSSR === true ? classified : undefined;
+
+  // On the reuse path, findMatch + manifest-loading already ran during
+  // classifyRequest (which carries no metricsStore), so only the cheap
+  // entries/cacheScope materialization is timed here under a distinct label. On
+  // the fresh path, resolveRoute emits route-matching + manifest-loading as usual.
+  const routeMatchStart = metricsStore ? performance.now() : 0;
 
-  if (!result) {
-    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
-      cause: { pathname, method: request.method },
+  let snapshot: RouteSnapshot<TEnv>;
+  if (classifiedRoute && classifiedRoute.manifestEntry) {
+    snapshot = ensureFullRouteSnapshot(classifiedRoute);
+    if (metricsStore) {
+      metricsStore.metrics.push({
+        label: "route-matching:reuse",
+        duration: performance.now() - routeMatchStart,
+        startTime: routeMatchStart - metricsStore.requestStart,
+      });
+    }
+  } else {
+    const result = await resolveRoute<TEnv>(pathname, {
+      findMatch: (p) => deps.findMatch(p, metricsStore),
+      metricsStore,
+      isSSR: true,
     });
-  }
 
-  if (result.type === "redirect") {
-    return {
-      type: "redirect",
-      redirectUrl: result.redirectTo + url.search,
-    };
-  }
+    if (!result) {
+      throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+        cause: { pathname, method: request.method },
+      });
+    }
+
+    if (result.type === "redirect") {
+      // Preserve the raw query string (including internal _rsc* params) on the
+      // redirect target, matching the pre-reuse behavior of `url.search`.
+      const rawSearch = (reqCtx?.originalUrl ?? new URL(request.url)).search;
+      return {
+        type: "redirect",
+        redirectUrl: result.redirectTo + rawSearch,
+      };
+    }
 
-  const snapshot = result.snapshot;
+    snapshot = result.snapshot;
+  }
 
   const { matched } = snapshot;
 
@@ -79,8 +116,6 @@ export async function createMatchContextForFull<TEnv>(
     matched.pt = true;
   }
 
-  const cleanUrl = stripInternalParams(url);
-
   const handlerContext = createHandlerContext(
     matched.params,
     request,
@@ -164,8 +199,13 @@ export async function createMatchContextForPartial<TEnv>(
   findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"],
   actionContext?: ActionContext,
 ): Promise<MatchContext<TEnv> | null> {
-  const url = new URL(request.url);
-  const pathname = url.pathname;
+  const reqCtx = _getRequestContext();
+  // resolveNavigation needs the raw URL (reads internal _rsc_segments /
+  // _rsc_stale params that stripInternalParams removes); the clean URL feeds the
+  // handler context. Both come off the request context when present.
+  const rawUrl = reqCtx?.originalUrl ?? new URL(request.url);
+  const cleanUrl = reqCtx?.url ?? stripInternalParams(rawUrl);
+  const pathname = cleanUrl.pathname;
 
   const metricsStore = deps.getMetricsStore();
 
@@ -177,11 +217,13 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   // Reuse the classified snapshot when available and not invalidated by HMR.
-  // classifyRequest already called resolveRoute(lite) with isSSR=false, which
-  // matches the partial path. On HMR, discard to pick up manifest changes.
-  const classifiedRoute = isHmr
-    ? undefined
-    : getRequestContext()?._classifiedRoute;
+  // classifyRequest resolves a partial request with isSSR=false, matching this
+  // path. Never reuse an isSSR:true (full-render) snapshot — its loading()
+  // entries and manifest partition are wrong here. On HMR, discard to pick up
+  // manifest changes.
+  const classified = reqCtx?._classifiedRoute;
+  const classifiedRoute =
+    !isHmr && classified?.isSSR !== true ? classified : undefined;
 
   // Time route matching. On the reuse path, only nav findMatch calls are new
   // (current-route findMatch and manifest-loading were already timed during
@@ -220,7 +262,7 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt = true;
   }
 
-  const nav = resolveNavigation(request, url, matched.routeKey, {
+  const nav = await resolveNavigation(request, rawUrl, matched.routeKey, {
     findMatch: deps.findMatch,
   });
   if (!nav) {
@@ -243,8 +285,6 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  const cleanUrl = stripInternalParams(url);
-
   const handlerContext = createHandlerContext(
     matched.params,
     request,
@@ -287,7 +327,11 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
+  setRequestContextPrevRouteKey(
+    nav.effectiveFromMatch?.routeKey,
+    nav.effectiveFromUrl,
+    nav.effectiveFromMatch?.params ?? nav.prevParams,
+  );
 
   const interceptSelectorContext: InterceptSelectorContext = {
     from: nav.effectiveFromUrl,
@@ -400,7 +444,7 @@ export async function matchError<TEnv>(
 
   debugLog("matchError", "matching error", { pathname });
 
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (!matched) {
     debugWarn("matchError", "no route matched", { pathname });
     return null;

package/src/router/match-handlers.ts

@@ -41,6 +41,109 @@ import {
 } 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>;
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
@@ -155,42 +258,43 @@ export function createMatchHandlers<TEnv = any>(
   }
 
   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);
 
           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: [],
@@ -210,51 +314,26 @@ export function createMatchHandlers<TEnv = any>(
             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: "request.end",
-                timestamp: performance.now(),
-                requestId,
-                method: request.method,
-                pathname,
-                transaction: "match",
-                durationMs: performance.now() - matchStart,
-                segmentCount: matchResult.segments.length,
-                cacheHit: state.cacheHit,
-              });
+              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;
+            emitter.error(
+              error instanceof Error ? error : new Error(String(error)),
+              "routing",
+            );
             callOnError(error, "routing", {
               request,
               url: ctx.url,
@@ -294,27 +373,34 @@ export function createMatchHandlers<TEnv = any>(
     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,
@@ -322,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;
             }
 
@@ -361,53 +435,25 @@ export function createMatchHandlers<TEnv = any>(
               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: "request.end",
-                  timestamp: performance.now(),
-                  requestId: partialRequestId,
-                  method: request.method,
-                  pathname,
-                  transaction: "matchPartial",
-                  durationMs: performance.now() - matchStart,
-                  segmentCount: matchResult.segments.length,
-                  cacheHit: state.cacheHit,
-                });
+                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;
+              emitter.error(
+                error instanceof Error ? error : new Error(String(error)),
+                actionContext ? "action" : "revalidation",
+              );
               callOnError(error, actionContext ? "action" : "revalidation", {
                 request,
                 url: ctx.url,

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

@@ -105,6 +105,10 @@ import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.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
@@ -183,33 +187,46 @@ export function withBackgroundRevalidation<TEnv>(
         const freshLoaderPromises = new Map<string, Promise<any>>();
         setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
 
-        const freshSegments = await ctx.Store.run(() =>
-          resolveAllSegments(
-            ctx.entries,
-            ctx.routeKey,
-            ctx.matched.params,
-            freshHandlerContext,
-            freshLoaderPromises,
-            { skipLoaders: true },
-          ),
+        // 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 },
+              ),
+            ),
         );
 
         let freshInterceptSegments: ResolvedSegment[] = [];
         if (ctx.interceptResult) {
-          freshInterceptSegments = await 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 },
-            ),
+          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 },
+                ),
+              ),
           );
         }