@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.143

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 },
+      });
+    }
 
-  const snapshot = result.snapshot;
+    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,
+      };
+    }
+
+    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 = await 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,

package/src/router/match-handlers.ts

@@ -41,6 +41,106 @@ 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): 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): 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,
+      });
+    },
+    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 +255,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 +311,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,
-                  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.
+              emitter.end(0, false);
+              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 +369,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 +404,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 +431,24 @@ 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.
+                emitter.end(0, false);
+                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-result.ts

@@ -201,17 +201,23 @@ export function buildMatchResult<TEnv>(
 
   let allIds: string[];
   let segmentsToRender: ResolvedSegment[];
+  let resolvedIds: string[];
 
   if (ctx.isFullMatch) {
+    // One pass over allSegments: dedup by id (segmentsToRender + allIds) while
+    // collecting every id for resolvedIds, which keeps duplicates unlike allIds.
     const seen = new Set<string>();
     segmentsToRender = [];
+    allIds = [];
+    resolvedIds = [];
     for (const s of allSegments) {
+      resolvedIds.push(s.id);
       if (!seen.has(s.id)) {
         seen.add(s.id);
         segmentsToRender.push(s);
+        allIds.push(s.id);
       }
     }
-    allIds = segmentsToRender.map((s) => s.id);
   } else {
     allIds = ctx.interceptResult
       ? ctx.clientSegmentIds.length > 0
@@ -221,11 +227,21 @@ export function buildMatchResult<TEnv>(
 
     allIds = [...new Set(allIds)];
 
+    // One pass over allSegments: keep renderable segments and collect the
+    // handler-ran ids (resolvedIds) together.
     const clientIdSet = new Set(ctx.clientSegmentIds);
-    segmentsToRender = allSegments.filter(
-      (s) =>
-        s.component !== null || s.type === "loader" || !clientIdSet.has(s.id),
-    );
+    segmentsToRender = [];
+    resolvedIds = [];
+    for (const s of allSegments) {
+      if (s._handlerRan) resolvedIds.push(s.id);
+      if (
+        s.component !== null ||
+        s.type === "loader" ||
+        !clientIdSet.has(s.id)
+      ) {
+        segmentsToRender.push(s);
+      }
+    }
   }
 
   const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
@@ -236,20 +252,24 @@ export function buildMatchResult<TEnv>(
   const matchedIds =
     removedIds.size > 0 ? allIds.filter((id) => !removedIds.has(id)) : allIds;
 
-  const resolvedIds = ctx.isFullMatch
-    ? allSegments.map((s) => s.id)
-    : allSegments.filter((s) => s._handlerRan).map((s) => s.id);
-
-  const cleanedSegments = dedupedSegments.map((s) => {
-    if (s._handlerRan === undefined) return s;
-    const { _handlerRan: _drop, ...rest } = s;
-    return rest as ResolvedSegment;
-  });
+  // One pass over dedupedSegments: strip the internal _handlerRan marker and
+  // collect the diff ids (id is unchanged by the strip) together.
+  const cleanedSegments: ResolvedSegment[] = [];
+  const diff: string[] = [];
+  for (const s of dedupedSegments) {
+    if (s._handlerRan === undefined) {
+      cleanedSegments.push(s);
+    } else {
+      const { _handlerRan: _drop, ...rest } = s;
+      cleanedSegments.push(rest as ResolvedSegment);
+    }
+    diff.push(s.id);
+  }
 
   return {
     segments: cleanedSegments,
     matched: matchedIds,
-    diff: cleanedSegments.map((s) => s.id),
+    diff,
     resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,