@rangojs/router 0.4.2 → 0.4.3

package/src/rsc/capture-queue.ts

@@ -36,6 +36,34 @@ export class CaptureQueueFullError extends Error {
   }
 }
 
+/**
+ * Budget on how long a capture may WAIT in the queue before it is dropped
+ * instead of run. On workerd a queued capture rides the scheduling request's
+ * waitUntil, whose post-response lifetime is bounded (~30s): a capture that
+ * already burned 15s+ parked behind a slow predecessor would start its own
+ * up-to-15s attempt (captureTimeout) with no budget left and risk being
+ * killed mid-store-write. Dropping at the budget is safe — captures are
+ * best-effort by contract, and a later request re-probes the key (the drop
+ * does NOT mark backoff: the route is not doomed, the isolate was busy).
+ * Matches one attempt's SHELL_CAPTURE_MAX_WAIT_MS so wait + attempt fits the
+ * platform budget. Field-observed: a navigation-shell capture parked ~24s
+ * behind a predecessor's two-attempt cycle.
+ */
+export const CAPTURE_QUEUE_WAIT_BUDGET_MS: number = 15_000;
+
+/** Thrown (async) when the queue wait exceeded the budget; the task never ran. */
+export class CaptureQueueWaitTimeoutError extends Error {
+  readonly waitedMs: number;
+  constructor(waitedMs: number) {
+    super(
+      `shell capture waited ${Math.round(waitedMs)}ms in the queue ` +
+        `(budget ${CAPTURE_QUEUE_WAIT_BUDGET_MS}ms)`,
+    );
+    this.name = "CaptureQueueWaitTimeoutError";
+    this.waitedMs = waitedMs;
+  }
+}
+
 /**
  * Upper bound on how long one queue link may hold the queue. A capture task
  * normally settles well inside this (attempt + in-place retry + writes), but
@@ -54,6 +82,7 @@ const QUEUE_LINK_CAP_MS = 60_000;
  */
 export function enqueueSerializedCapture(
   task: () => Promise<void>,
+  opts?: { maxQueueWaitMs?: number },
 ): Promise<void> {
   if (admittedCaptures >= MAX_ADMITTED_CAPTURES) {
     return Promise.reject(new CaptureQueueFullError());
@@ -65,25 +94,51 @@ export function enqueueSerializedCapture(
     releaseQueue = resolve;
   });
   return (async () => {
-    await prior.catch(() => {});
-    let capTimer: ReturnType<typeof setTimeout> | undefined;
-    const taskPromise = Promise.resolve()
-      .then(task)
-      .finally(() => {
-        // A timed-out link releases serialization, but its detached task still
-        // counts against admission until it actually settles.
-        admittedCaptures--;
-      });
+    const waitStart = performance.now();
+    const budget = opts?.maxQueueWaitMs ?? CAPTURE_QUEUE_WAIT_BUDGET_MS;
+    // The wait itself is budget-raced: the drop fires AT the budget, not once
+    // the predecessor eventually settles — a waiter parked behind a wedged
+    // link must not stay pending until that link's 60s cap just to learn it
+    // was already over budget.
+    let waitTimer: ReturnType<typeof setTimeout> | undefined;
+    const waitTimedOut = await Promise.race([
+      prior.catch(() => {}).then(() => false),
+      new Promise<boolean>((resolve) => {
+        waitTimer = setTimeout(() => resolve(true), budget);
+        (waitTimer as { unref?: () => void }).unref?.();
+      }),
+    ]);
+    if (waitTimer) clearTimeout(waitTimer);
+    if (waitTimedOut) {
+      // Never started: hand the admission slot back here (the taskPromise
+      // finally below does it for tasks that ran). Serialization stays
+      // intact: THIS link releases only once the predecessor settles —
+      // releasing now would let a successor run concurrently with it.
+      admittedCaptures--;
+      prior.catch(() => {}).then(releaseQueue, releaseQueue);
+      throw new CaptureQueueWaitTimeoutError(performance.now() - waitStart);
+    }
     try {
-      await Promise.race([
-        taskPromise,
-        new Promise<void>((resolve) => {
-          capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
-          (capTimer as { unref?: () => void }).unref?.();
-        }),
-      ]);
+      let capTimer: ReturnType<typeof setTimeout> | undefined;
+      const taskPromise = Promise.resolve()
+        .then(task)
+        .finally(() => {
+          // A timed-out link releases serialization, but its detached task still
+          // counts against admission until it actually settles.
+          admittedCaptures--;
+        });
+      try {
+        await Promise.race([
+          taskPromise,
+          new Promise<void>((resolve) => {
+            capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+            (capTimer as { unref?: () => void }).unref?.();
+          }),
+        ]);
+      } finally {
+        if (capTimer) clearTimeout(capTimer);
+      }
     } finally {
-      if (capTimer) clearTimeout(capTimer);
       releaseQueue();
     }
   })();

package/src/rsc/handler.ts

@@ -77,6 +77,7 @@ import {
   type ActionContinuation,
 } from "./server-action.js";
 import { handleLoaderFetch } from "./loader-fetch.js";
+import { applyStreamIdleTimeout } from "./stream-idle.js";
 import {
   checkRequestOrigin,
   ORIGIN_CHECK_PHASE_BY_MODE,
@@ -618,88 +619,179 @@ export function createRSCHandler<
           return coreRequestHandler(request, env, url, variables, nonce);
         };
 
-        // Execute middleware chain if any, otherwise call core handler directly
-        let response: Response;
-        if (matchedMiddleware.length > 0) {
-          const mwResponse = await executeMiddleware(
-            matchedMiddleware,
-            request,
-            env,
-            variables,
-            coreHandler,
-            createReverseFunction(getRequiredRouteMap()),
+        // Execute middleware chain if any, otherwise call core handler
+        // directly; the response is finalized below, inside the response span.
+        const hasMiddleware = matchedMiddleware.length > 0;
+        const downstream = hasMiddleware
+          ? await executeMiddleware(
+              matchedMiddleware,
+              request,
+              env,
+              variables,
+              coreHandler,
+              createReverseFunction(getRequiredRouteMap()),
+            )
+          : await coreHandler();
+
+        // Final response construction + host handoff, wrapped in rango.response
+        // — the explicit stream-handoff marker. The callback is synchronous, so
+        // the span ends immediately before the handler returns the response to
+        // the host; it never reads or wraps response.body. A downstream throw
+        // skips it entirely (no response exists to hand off).
+        return observePhase(PHASES.response, (responseSpan) => {
+          let response: Response;
+          if (hasMiddleware) {
+            if (
+              url.searchParams.has("_rsc_partial") ||
+              url.searchParams.has("_rsc_action")
+            ) {
+              const intercepted = interceptRedirectForPartial(
+                downstream,
+                createRedirectFlightResponse,
+                { requestOrigin: url.origin, basename: router.basename },
+              );
+              response = intercepted ?? finalizeResponse(downstream);
+            } else {
+              response = finalizeResponse(downstream);
+            }
+          } else {
+            response = downstream;
+          }
+
+          // Finalize metrics after all middleware (including post-next work)
+          // has completed so :post spans are captured in the timeline.
+          // Handler timing parts are always emitted (even without debug metrics)
+          // so non-debug requests still get bootstrap Server-Timing entries.
+          const handlerTimingArr: string[] = variables.__handlerTiming || [];
+          // Preserve any existing Server-Timing set by response routes or middleware
+          const existingTiming = response.headers.get("Server-Timing");
+          const timingParts = existingTiming
+            ? [existingTiming, ...handlerTimingArr]
+            : [...handlerTimingArr];
+
+          const metricsStore = requestContext._metricsStore;
+          if (metricsStore) {
+            // When the store was created at handler start (earlyMetricsStore),
+            // handler:total covers the full request. When ctx.debugPerformance()
+            // created the store mid-request its requestStart is now the threaded
+            // _handlerStart (== handlerStart), so both branches yield the true
+            // request entry; reading the store's own anchor keeps this correct even
+            // if a store ever lands without the threading (falls back to its start).
+            const totalStart = earlyMetricsStore
+              ? handlerStart
+              : metricsStore.requestStart;
+            appendMetric(
+              metricsStore,
+              "handler:total",
+              totalStart,
+              performance.now() - totalStart,
+            );
+            const metricsTiming = buildMetricsTiming(
+              request.method,
+              url.pathname,
+              metricsStore,
+            );
+            if (metricsTiming) timingParts.push(metricsTiming);
+          }
+
+          const fullTiming = timingParts.join(", ");
+          if (fullTiming && !isWebSocketUpgradeResponse(response)) {
+            try {
+              response.headers.set("Server-Timing", fullTiming);
+            } catch {
+              // Immutable headers (e.g. a passed-through platform Response) — drop
+              // the timing header, never the response. Instrumentation must not
+              // 500 a request.
+            }
+          }
+
+          // Single open-redirect chokepoint: every response (PE, full-page,
+          // middleware short-circuit, response-route) funnels through here, so
+          // guarding browser-followed (3xx) redirects once covers them all and any
+          // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
+          // through untouched (validated client-side instead).
+          const guarded = guardOutgoingRedirect(
+            response,
+            url.origin,
+            router.basename,
           );
 
+          // Stream-idle watchdog (opt-in via timeouts.streamIdleMs): bounds
+          // end-to-end idle flow on the streamed body — see rsc/stream-idle.ts
+          // for the semantics. Applied at this finalization chokepoint so every
+          // streaming exit is covered; websocket upgrades must never be
+          // reconstructed and bodiless responses have nothing to bound. The
+          // trip fires POST-handoff (the request ALS may be gone), so it
+          // reports via the eagerly captured surfaces — callOnError +
+          // router.telemetry directly — mirroring handleStore.onError.
+          // onTimeout does NOT apply: the response already left the handler,
+          // so no replacement Response can be served mid-stream.
+          let finalResponse = guarded;
+          const streamIdleMs = router.timeouts.streamIdleMs;
+          // Websocket check FIRST: a workerd upgrade response must never have
+          // its body getter poked (same invariant as the body_kind attribute
+          // below).
           if (
-            url.searchParams.has("_rsc_partial") ||
-            url.searchParams.has("_rsc_action")
+            isTimeoutEnabled(streamIdleMs) &&
+            !isWebSocketUpgradeResponse(guarded) &&
+            guarded.body
           ) {
-            const intercepted = interceptRedirectForPartial(
-              mwResponse,
-              createRedirectFlightResponse,
-              { requestOrigin: url.origin, basename: router.basename },
+            const routeKey = requestContext._routeName;
+            finalResponse = applyStreamIdleTimeout(
+              guarded,
+              streamIdleMs!,
+              (tripInfo) => {
+                callOnError(tripInfo.error, "handler", {
+                  request,
+                  url,
+                  env,
+                  routeKey,
+                  handledByBoundary: false,
+                  metadata: {
+                    timeout: true,
+                    phase: "stream-idle",
+                    durationMs: tripInfo.totalMs,
+                  },
+                });
+                if (router.telemetry) {
+                  safeEmit(resolveSink(router.telemetry), {
+                    type: "request.timeout",
+                    timestamp: performance.now(),
+                    requestId: getRequestId(request),
+                    phase: "stream-idle",
+                    pathname: url.pathname,
+                    routeKey,
+                    durationMs: tripInfo.totalMs,
+                    customHandler: false,
+                  });
+                }
+              },
             );
-            response = intercepted ?? finalizeResponse(mwResponse);
-          } else {
-            response = finalizeResponse(mwResponse);
           }
-        } else {
-          response = await coreHandler();
-        }
 
-        // Finalize metrics after all middleware (including post-next work)
-        // has completed so :post spans are captured in the timeline.
-        // Handler timing parts are always emitted (even without debug metrics)
-        // so non-debug requests still get bootstrap Server-Timing entries.
-        const handlerTimingArr: string[] = variables.__handlerTiming || [];
-        // Preserve any existing Server-Timing set by response routes or middleware
-        const existingTiming = response.headers.get("Server-Timing");
-        const timingParts = existingTiming
-          ? [existingTiming, ...handlerTimingArr]
-          : [...handlerTimingArr];
-
-        const metricsStore = requestContext._metricsStore;
-        if (metricsStore) {
-          // When the store was created at handler start (earlyMetricsStore),
-          // handler:total covers the full request. When ctx.debugPerformance()
-          // created the store mid-request its requestStart is now the threaded
-          // _handlerStart (== handlerStart), so both branches yield the true
-          // request entry; reading the store's own anchor keeps this correct even
-          // if a store ever lands without the threading (falls back to its start).
-          const totalStart = earlyMetricsStore
-            ? handlerStart
-            : metricsStore.requestStart;
-          appendMetric(
-            metricsStore,
-            "handler:total",
-            totalStart,
-            performance.now() - totalStart,
+          // Attributes describe the response actually handed to the host (after
+          // unsafe-redirect replacement), low-cardinality only. body_kind checks
+          // the websocket marker before the body getter so a workerd upgrade
+          // Response is never poked; `.body` is a getter access, not a read of
+          // the stream.
+          responseSpan.setAttribute(
+            "http.response.status_code",
+            finalResponse.status,
           );
-          const metricsTiming = buildMetricsTiming(
-            request.method,
-            url.pathname,
-            metricsStore,
+          responseSpan.setAttribute(
+            "rango.response.mode",
+            requestContext._requestMode ?? "middleware-short-circuit",
           );
-          if (metricsTiming) timingParts.push(metricsTiming);
-        }
-
-        const fullTiming = timingParts.join(", ");
-        if (fullTiming && !isWebSocketUpgradeResponse(response)) {
-          try {
-            response.headers.set("Server-Timing", fullTiming);
-          } catch {
-            // Immutable headers (e.g. a passed-through platform Response) — drop
-            // the timing header, never the response. Instrumentation must not
-            // 500 a request.
-          }
-        }
-
-        // Single open-redirect chokepoint: every response (PE, full-page,
-        // middleware short-circuit, response-route) funnels through here, so
-        // guarding browser-followed (3xx) redirects once covers them all and any
-        // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
-        // through untouched (validated client-side instead).
-        return guardOutgoingRedirect(response, url.origin, router.basename);
+          responseSpan.setAttribute(
+            "rango.response.body_kind",
+            isWebSocketUpgradeResponse(finalResponse)
+              ? "websocket"
+              : finalResponse.body === null
+                ? "empty"
+                : "stream",
+          );
+          return finalResponse;
+        });
       }),
     );
   };
@@ -755,6 +847,12 @@ export function createRSCHandler<
     const classifyDur = performance.now() - classifyStart;
     handlerTiming.push(`handler-classify;dur=${classifyDur.toFixed(2)}`);
 
+    // Stash the classified mode for the rango.response span (rango.response.mode)
+    // — the outer handler tail cannot see the plan. Stays unset when middleware
+    // short-circuits before core execution runs (reported as
+    // "middleware-short-circuit").
+    getRequestContext()._requestMode = plan.mode;
+
     // ---- 2. Terminal plans (no execution needed) ----
     if (plan.mode === "redirect") {
       // Redirects are handled by the pipeline (match/matchPartial),

package/src/rsc/shell-capture.ts

@@ -22,11 +22,13 @@ import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
 import {
   CaptureQueueFullError,
+  CaptureQueueWaitTimeoutError,
   enqueueSerializedCapture,
 } from "./capture-queue.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import type { TraceSpan } from "../router/tracing.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
@@ -416,6 +418,10 @@ export interface ShellCaptureDebugEvent {
    * - skip-backoff: the key is inside its refused-capture backoff window and
    *   the capture was not attempted
    * - skip-capacity: the isolate capture queue is full; a later request may retry
+   * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
+   *   behind other captures and was dropped unrun (no backoff — the route is
+   *   not doomed, the isolate was busy; a later request re-probes). Carries
+   *   queueWaitMs.
    * - backoff: the key entered (or escalated) backoff after a terminal
    *   no-shell — carries the new backoff state
    */
@@ -428,6 +434,7 @@ export interface ShellCaptureDebugEvent {
     | "skip-in-flight"
     | "skip-backoff"
     | "skip-capacity"
+    | "skip-queue-timeout"
     | "backoff";
   /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
   attempt?: number;
@@ -457,6 +464,8 @@ export interface ShellCaptureDebugEvent {
   backoffFailures?: number;
   /** Ms remaining in the key's backoff window, when one exists. */
   backoffRemainingMs?: number;
+  /** Ms the capture waited in the serialized queue (skip-queue-timeout). */
+  queueWaitMs?: number;
 }
 
 /**
@@ -503,6 +512,9 @@ export function describeShellCaptureEvent(
   if (event.backoffRemainingMs !== undefined) {
     parts.push(`backoff-remaining=${event.backoffRemainingMs}ms`);
   }
+  if (event.queueWaitMs !== undefined) {
+    parts.push(`queue-wait=${event.queueWaitMs}ms`);
+  }
   return parts.join(" ");
 }
 
@@ -853,7 +865,7 @@ export function scheduleShellCapture(
     return;
   }
   inFlightCaptures.add(key);
-  const captureTask = async () => {
+  const captureTask = async (span: TraceSpan) => {
     try {
       const setupUrl = descriptor.navigationOnly
         ? stripInternalParams(url)
@@ -881,6 +893,7 @@ export function scheduleShellCapture(
         resolvedSsrModule,
         descriptor,
       );
+      span.setAttribute("rango.background.outcome", outcome);
       // Update the negative cache off the terminal outcome. A stored shell clears
       // any prior backoff; a `no-shell` (after the in-place retry) backs the key
       // off so the next requests don't re-probe it. A `redirect` has no shell but
@@ -899,6 +912,7 @@ export function scheduleShellCapture(
       // context is gone. A genuine failure recurs, so back it off too (re-probe
       // once per window, not every request) and report it once.
       markCaptureBackoff(key);
+      span.setAttribute("rango.background.outcome", "error");
       publishCaptureDebugEvent(descriptor, {
         key,
         outcome: "error",
@@ -914,20 +928,58 @@ export function scheduleShellCapture(
   // capture makes the sibling freeze a trivial prelude and store nothing
   // (rotating eternal-MISS victims on GH runners). The stampede guard above
   // stays per-key (dedupe while queued); the queue is cross-key.
+  //
+  // The whole serialized task — queue wait INCLUDED — is wrapped in the
+  // rango.background span (kind=shell-capture). The span is the explanatory
+  // parent for the capture's platform KV/fetch/cache spans (the capture's own
+  // rango.* phase spans stay suppressed — deriveShellCaptureContext strips
+  // _tracing), and queue_wait_ms makes a capture parked behind a slow
+  // predecessor link visible instead of reading as an unexplained dead gap
+  // (observed in production: ~24s of zero I/O before capture start).
+  // observePhase reads tracing off the ALS context captured when runBackground
+  // registered the task — the foreground request context, tracing intact.
   const serializedTask = async () => {
-    try {
-      await enqueueSerializedCapture(captureTask);
-    } catch (error) {
-      if (error instanceof CaptureQueueFullError) {
-        inFlightCaptures.delete(key);
-        publishCaptureDebugEvent(descriptor, {
-          key,
-          outcome: "skip-capacity",
+    await observePhase(PHASES.background("shell-capture"), async (span) => {
+      span.setAttribute("rango.shell_key", key);
+      const queueStart = performance.now();
+      try {
+        await enqueueSerializedCapture(() => {
+          span.setAttribute(
+            "rango.background.queue_wait_ms",
+            Math.round(performance.now() - queueStart),
+          );
+          return captureTask(span);
         });
-        return;
+      } catch (error) {
+        if (error instanceof CaptureQueueFullError) {
+          inFlightCaptures.delete(key);
+          span.setAttribute("rango.background.outcome", "skip-capacity");
+          publishCaptureDebugEvent(descriptor, {
+            key,
+            outcome: "skip-capacity",
+          });
+          return;
+        }
+        if (error instanceof CaptureQueueWaitTimeoutError) {
+          // Dropped unrun after waiting past the queue budget: no backoff (the
+          // route is not doomed, the isolate was busy) — a later request
+          // re-probes the key.
+          inFlightCaptures.delete(key);
+          span.setAttribute("rango.background.outcome", "skip-queue-timeout");
+          span.setAttribute(
+            "rango.background.queue_wait_ms",
+            Math.round(error.waitedMs),
+          );
+          publishCaptureDebugEvent(descriptor, {
+            key,
+            outcome: "skip-queue-timeout",
+            queueWaitMs: Math.round(error.waitedMs),
+          });
+          return;
+        }
+        throw error;
       }
-      throw error;
-    }
+    });
   };
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),

package/src/rsc/stream-idle.ts

@@ -0,0 +1,137 @@
+/**
+ * Stream-idle timeout — the enforcement for `timeouts.streamIdleMs` (the
+ * "stream-idle" TimeoutPhase, reserved since the timeout API landed).
+ *
+ * WHY: nothing else bounds a streaming response body's lifetime.
+ * `renderStartMs` only bounds time-to-Response-construction; once the body is
+ * streaming, a single never-settling promise embedded in the payload (a
+ * deferred loader that never resolves, an orphaned ctx.rendered() barrier)
+ * holds the Flight/HTML stream — and the client's connection — open forever.
+ * Deferred HANDLES have a 10s auto-resolve net (defer.ts); loader promises
+ * and everything else have none. Field-observed as multi-second dead
+ * connections only closed by client cancellation.
+ *
+ * SEMANTICS — end-to-end idle flow, deliberately: the watchdog re-arms on
+ * every chunk that flows THROUGH to the client, so "idle" means "no bytes
+ * reached the wire for N ms". A stalled slow client counts as idle the same
+ * as a wedged producer — the two are indistinguishable here without buffering,
+ * and buffering is banned on the streaming path. Pick budgets accordingly
+ * (generous, seconds not millis); the feature is OPT-IN (unset = today's
+ * unbounded behavior, and the `timeout` shorthand deliberately does not apply
+ * to streamIdleMs — see resolveTimeouts).
+ *
+ * ON TRIP: the client-facing stream is errored with a RouterTimeoutError
+ * ("stream-idle") — the host terminates the response visibly (truncated
+ * chunked encoding), which is debuggable, unlike a silent clean close that
+ * would present a half-document as complete. Erroring the transform makes the
+ * pipe cancel its SOURCE, which aborts React's fizz/flight render — but only
+ * when the watchdog's branch is the sole consumer. When an upstream layer
+ * teed or cloned the body first (the document-cache MISS drain,
+ * response-cache clones), the watchdog holds one tee branch: tee semantics
+ * cancel the underlying source only once EVERY branch cancels, so the cache
+ * branch keeps the wedged render alive, bounded only by the platform's
+ * waitUntil budget — exactly as it was before this feature. The client-facing
+ * bound is unconditional; source teardown is best-effort. `onTimeout` does
+ * NOT apply: the response already left the handler, so no replacement
+ * Response can be served — the trip is reported via onError + the
+ * request.timeout telemetry event instead.
+ *
+ * COST: one identity TransformStream hop per chunk, only when the timeout is
+ * enabled. Never buffers, never reads ahead, adds no work when disabled.
+ */
+
+import { RouterTimeoutError } from "../router/timeout.js";
+
+/** What the watchdog observed when it tripped. */
+export interface StreamIdleTrip {
+  /** ms since the watchdog armed (response handoff) — the stream's lifetime. */
+  totalMs: number;
+  /** Chunks forwarded before the trip. */
+  chunks: number;
+  /** The error the client-facing stream was terminated with. */
+  error: RouterTimeoutError;
+}
+
+/**
+ * Wrap `response`'s body in an idle watchdog. Returns a NEW Response with the
+ * same status/headers whose body errors (and cancels the source) once no chunk
+ * has flowed for `idleMs`. Callers gate on isTimeoutEnabled + body presence +
+ * NOT a websocket upgrade (a 101/webSocket response must never be
+ * reconstructed); this function assumes those checks were made. `onTrip` fires
+ * at most once, after the client-facing stream has been errored.
+ */
+export function applyStreamIdleTimeout(
+  response: Response,
+  idleMs: number,
+  onTrip: (trip: StreamIdleTrip) => void,
+): Response {
+  const source = response.body;
+  if (!source) return response;
+
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let chunks = 0;
+  let settled = false;
+  let controllerRef!: TransformStreamDefaultController<unknown>;
+
+  const disarm = () => {
+    settled = true;
+    if (timer) clearTimeout(timer);
+  };
+
+  const trip = () => {
+    if (settled) return;
+    const error = new RouterTimeoutError(
+      "stream-idle",
+      performance.now() - start,
+    );
+    try {
+      controllerRef.error(error);
+    } catch {
+      // The stream already terminated (raced a close/cancel) — nothing was
+      // interrupted, so do not report a timeout.
+      return;
+    }
+    // Erroring the transform makes the pipe abort and CANCEL the source
+    // stream (React aborts the wedged render). Mark settled AFTER the error
+    // took, then report.
+    disarm();
+    onTrip({ totalMs: error.durationMs, chunks, error });
+  };
+
+  const arm = () => {
+    if (settled) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(trip, idleMs);
+    (timer as { unref?: () => void }).unref?.();
+  };
+
+  // `cancel` is the spec's newer transformer hook (client-side cancellation);
+  // TS's lib.dom Transformer type lags it, hence the intersection. Runtimes
+  // without it fall back to the settled/try-catch guards in trip().
+  const transformer: Transformer<unknown, unknown> & { cancel?: () => void } = {
+    start(controller) {
+      controllerRef = controller;
+      arm();
+    },
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+      chunks++;
+      arm();
+    },
+    flush() {
+      // Natural end of the source stream.
+      disarm();
+    },
+    cancel() {
+      disarm();
+    },
+  };
+  const watchdog = new TransformStream<unknown, unknown>(transformer);
+
+  return new Response(source.pipeThrough(watchdog) as ReadableStream, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}