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

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,9 +255,20 @@ 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 () => {
@@ -165,34 +276,22 @@ export function createMatchHandlers<TEnv = any>(
           const pathname =
             _getRequestContext()?.url?.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 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: [],
@@ -212,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,
@@ -296,11 +369,16 @@ 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 () => {
@@ -308,17 +386,17 @@ export function createMatchHandlers<TEnv = any>(
             const pathname =
               _getRequestContext()?.url?.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 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 +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;
             }
 
@@ -365,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/middleware.ts

@@ -550,22 +550,28 @@ export async function executeMiddleware<TEnv>(
     // when neither surface is active.
     let result: Response | void;
     try {
-      result = await observePhase(PHASES.middleware(metricLabel), () =>
-        entry.handler(ctx, wrappedNext),
-      );
-    } catch (error) {
-      // Thrown Response is short-circuit control flow, not an error.
-      // Fall through to the `if (result instanceof Response)` branch below
-      // so stub headers and request-context cookies merge as they do for
-      // an explicit `return new Response(...)`. Real errors propagate.
-      if (error instanceof Response) {
-        result = error;
-      } else {
-        finishMiddleware();
-        throw error;
-      }
+      result = await observePhase(PHASES.middleware(metricLabel), async () => {
+        try {
+          return await entry.handler(ctx, wrappedNext);
+        } catch (error) {
+          // Thrown Response is short-circuit control flow, not an error —
+          // absorb it INSIDE the span so the tracing runner settles the
+          // rango.middleware span as success, not STATUS_ERROR (every auth
+          // redirect would otherwise inflate trace error rates). Returning it
+          // routes through the `if (result instanceof Response)` branch below,
+          // so stub headers and request-context cookies merge identically to an
+          // explicit `return new Response(...)`. Segment handlers already follow
+          // this convention (segment-resolution/helpers.ts keeps result handling
+          // outside the span). Real errors propagate past the span.
+          if (error instanceof Response) return error;
+          throw error;
+        }
+      });
+    } finally {
+      // Settle the middleware own-time metric once on both the success and
+      // error paths (idempotent guard in finishMiddleware).
+      finishMiddleware();
     }
-    finishMiddleware();
 
     // Record post-next() processing time when middleware did work after
     // the downstream chain resolved (e.g. adding headers, logging).
@@ -725,20 +731,21 @@ export async function executeInterceptMiddleware<TEnv>(
       ordinal,
     );
 
-    let result: Response | void;
-    try {
-      result = await observePhase(PHASES.middleware(label), () =>
-        middleware(ctx, guardedNext),
-      );
-    } catch (error) {
-      // Thrown Response is short-circuit control flow, parity with the
-      // explicit-return path below. Real errors propagate.
-      if (error instanceof Response) {
-        result = error;
-      } else {
-        throw error;
-      }
-    }
+    const result: Response | void = await observePhase(
+      PHASES.middleware(label),
+      async () => {
+        try {
+          return await middleware(ctx, guardedNext);
+        } catch (error) {
+          // Thrown Response is short-circuit control flow, parity with the
+          // explicit-return path below. Absorb it INSIDE the span so the tracing
+          // runner settles rango.middleware as success, not STATUS_ERROR (same
+          // reasoning as executeMiddleware's main chain). Real errors propagate.
+          if (error instanceof Response) return error;
+          throw error;
+        }
+      },
+    );
 
     if (result instanceof Response) {
       earlyResponse = result;

package/src/router/router-interfaces.ts

@@ -16,6 +16,7 @@ import type { RangoOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
 import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 import type { ResolvedTracing } from "./tracing.js";
+import type { TelemetrySink } from "./telemetry.js";
 
 /**
  * Options passed to router.fetch(), router.match(), and other request entrypoints.
@@ -350,6 +351,14 @@ export interface RangoInternal<
    */
   readonly tracing?: ResolvedTracing;
 
+  /**
+   * Raw telemetry sink from RangoOptions, exposed so handler-level emitters
+   * (rsc/handler.ts timeout/origin/late-handle) can emit WITHOUT the
+   * RouterContext ALS, which only match()/matchPartial() enter. See
+   * observeEvent's emitter list in router/instrument.ts.
+   */
+  readonly telemetry?: TelemetrySink;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.

package/src/router/segment-resolution/loader-snapshot.ts

@@ -10,15 +10,20 @@
  *
  *   - elide:   deep-walk the settled container; a SETTLED nested promise baked
  *              its value (physics: it won the quiet window), so it is pinned as
- *              that value; a PENDING nested promise is a hole, replaced by
- *              {@link LOADER_HOLE_MARKER}. The result is promise-free and
+ *              that value wrapped in a SETTLED marker — the wrapper remembers
+ *              "this was a promise" so the overlay can rehydrate the shape; a
+ *              PENDING nested promise is a hole, replaced by
+ *              {@link LOADER_HOLE_KEY}. The result is promise-free and
  *              Flight-serializable.
  *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
  *              the live nested promises), then the recorded container is laid
  *              over it: recorded paths win (they are what the prelude froze),
- *              marker paths take the fresh run's value (the live hole), and
- *              fresh-only paths pass through (they cannot contradict prelude
- *              bytes that never rendered them).
+ *              hole-marker paths take the fresh run's value (the live hole),
+ *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
+ *              wrote use(data.x) against a promise-shaped container, and
+ *              handing them the raw value throws React #438 on every HIT (the
+ *              storefront PDP regression) — and fresh-only paths pass through
+ *              (they cannot contradict prelude bytes that never rendered them).
  */
 
 import { isThenable } from "../../handles/is-thenable.js";
@@ -42,6 +47,37 @@ export function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker {
   );
 }
 
+/**
+ * Marker wrapping the inlined value of a NESTED promise that settled during
+ * capture. The value baked (physics), but the container key was a promise —
+ * the overlay must hand consumers a Promise.resolve(value), not the raw value,
+ * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
+ * container is never wrapped: loader-cache overlays against the awaited fresh
+ * container value.
+ */
+export const LOADER_SETTLED_KEY = "$rangoLoaderSettled" as const;
+
+export interface LoaderSettledMarker {
+  [LOADER_SETTLED_KEY]: 1;
+  value: unknown;
+  /**
+   * Present when the pinned subtree contains hole markers. Computed once at
+   * capture (elide already visits every node) so the per-HIT overlay never
+   * rescans the pinned structure to pick its rehydration path.
+   */
+  holes?: 1;
+}
+
+export function isLoaderSettledMarker(
+  value: unknown,
+): value is LoaderSettledMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_SETTLED_KEY] === 1
+  );
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (typeof value !== "object" || value === null) return false;
   const proto = Object.getPrototypeOf(value);
@@ -77,17 +113,22 @@ async function probeSettled(
 }
 
 export type ElideResult =
-  | { state: "ok"; value: unknown }
+  | { state: "ok"; value: unknown; hasHole: boolean }
   | { state: "rejected" };
 
 /**
  * Deep-elide a settled bake-lane container for recording. Settled nested
- * promises are inlined (they baked); pending ones become hole markers; a
- * REJECTED nested promise poisons the record (error UI must never bake into a
- * shared shell) — the caller refuses the capture. Only plain objects/arrays are
+ * promises pin their value behind a settled marker (they baked, but consumers
+ * hold a promise-shaped key); pending ones become hole markers; a REJECTED
+ * nested promise poisons the record (error UI must never bake into a shared
+ * shell) — the caller refuses the capture. Only plain objects/arrays are
  * traversed; anything else (Date, Map, class instance) is a pinned leaf.
  * Cycles are cut as pinned references (best effort — Flight rejects true
  * cycles later regardless).
+ *
+ * The ROOT container promise-chain unwraps with NO marker: loader-cache
+ * overlays against the AWAITED fresh container, so the recorded root must be
+ * the unwrapped structure. Everything below it goes through elideNested.
  */
 export async function elideLoaderContainer(
   value: unknown,
@@ -96,37 +137,61 @@ export async function elideLoaderContainer(
   if (isThenable(value)) {
     const probed = await probeSettled(value);
     if (probed.state === "pending") {
-      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 } };
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
     }
     if (probed.state === "rejected") return { state: "rejected" };
     return elideLoaderContainer(probed.value, seen);
   }
+  return elideNested(value, seen);
+}
+
+async function elideNested(
+  value: unknown,
+  seen: Set<object>,
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    const inner = await elideNested(probed.value, seen);
+    if (inner.state === "rejected") return inner;
+    const marker: LoaderSettledMarker = inner.hasHole
+      ? { [LOADER_SETTLED_KEY]: 1, value: inner.value, holes: 1 }
+      : { [LOADER_SETTLED_KEY]: 1, value: inner.value };
+    return { state: "ok", value: marker, hasHole: inner.hasHole };
+  }
 
   if (Array.isArray(value)) {
-    if (seen.has(value)) return { state: "ok", value };
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
     seen.add(value);
     const out: unknown[] = new Array(value.length);
+    let hasHole = false;
     for (let i = 0; i < value.length; i++) {
-      const r = await elideLoaderContainer(value[i], seen);
+      const r = await elideNested(value[i], seen);
       if (r.state === "rejected") return r;
       out[i] = r.value;
+      hasHole ||= r.hasHole;
     }
-    return { state: "ok", value: out };
+    return { state: "ok", value: out, hasHole };
   }
 
   if (isPlainObject(value)) {
-    if (seen.has(value)) return { state: "ok", value };
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
     seen.add(value);
     const out: Record<string, unknown> = {};
+    let hasHole = false;
     for (const key of Object.keys(value)) {
-      const r = await elideLoaderContainer(value[key], seen);
+      const r = await elideNested(value[key], seen);
       if (r.state === "rejected") return r;
       out[key] = r.value;
+      hasHole ||= r.hasHole;
     }
-    return { state: "ok", value: out };
+    return { state: "ok", value: out, hasHole };
   }
 
-  return { state: "ok", value };
+  return { state: "ok", value, hasHole: false };
 }
 
 /**
@@ -142,6 +207,22 @@ export function overlayLoaderContainer(
 ): unknown {
   if (isLoaderHoleMarker(recorded)) return fresh;
 
+  if (isLoaderSettledMarker(recorded)) {
+    const pinned = recorded.value;
+    // Deep holes inside a settled container (capture-computed `holes` bit)
+    // need the fresh promise's resolved value to fill them; a fully-pinned
+    // container resolves immediately (the prelude already shows it — never
+    // gate it on fresh latency). A rejecting fresh run degrades holes to
+    // undefined instead of poisoning the pin.
+    if (recorded.holes === 1) {
+      return Promise.resolve(fresh).then(
+        (freshValue) => overlayLoaderContainer(freshValue, pinned),
+        () => overlayLoaderContainer(undefined, pinned),
+      );
+    }
+    return Promise.resolve(overlayLoaderContainer(undefined, pinned));
+  }
+
   if (Array.isArray(recorded)) {
     const freshArr = Array.isArray(fresh) ? fresh : [];
     return recorded.map((item, i) => overlayLoaderContainer(freshArr[i], item));