@rangojs/router 0.4.1 → 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/rsc-rendering.ts

@@ -83,6 +83,10 @@ import type {
   ShellCacheEntry,
   ShellSnapshotRecord,
 } from "../cache/types.js";
+import {
+  SEGMENT_FRAGMENT_CAPABILITY_HEADER,
+  SEGMENT_FRAGMENT_RECOVERY_HEADER,
+} from "../segment-fragments.js";
 
 type PprReplayBypassReason =
   | "method"
@@ -285,6 +289,7 @@ async function handleRscRenderingInner<TEnv>(
   let hasInterceptSlots = false;
   let pprReplayStatus: PprReplayStatus | undefined;
   let partialCaptureNeeded = false;
+  let partialCaptureKey: string | undefined;
 
   // --- Axis 2: integrated PPR shell serve (docs/design/ppr-shell-resume.md) ---
   //
@@ -494,6 +499,7 @@ async function handleRscRenderingInner<TEnv>(
     pprReplayStatus = replay.status;
     partialCaptureNeeded =
       "captureNeeded" in replay && replay.captureNeeded === true;
+    partialCaptureKey = "captureKey" in replay ? replay.captureKey : undefined;
 
     if (!result) {
       // Fall back to full render
@@ -612,7 +618,7 @@ async function handleRscRenderingInner<TEnv>(
 
   const rscHeaders: Record<string, string> = {
     "content-type": "text/x-component;charset=utf-8",
-    vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+    vary: `accept, X-Rango-State, X-RSC-Router-Client-Path, ${SEGMENT_FRAGMENT_CAPABILITY_HEADER}, ${SEGMENT_FRAGMENT_RECOVERY_HEADER}`,
     // Router identity, so the client can verify pre-decode (before importing
     // chunks) that this content payload belongs to its app and refuse a
     // foreign one (cache/proxy/bug). Control-only reload/redirect responses
@@ -721,7 +727,8 @@ async function handleRscRenderingInner<TEnv>(
       },
       createShellCaptureDescriptor(
         ctx,
-        buildNavigationShellKey(url, reqCtx._searchParamsFilter),
+        partialCaptureKey ??
+          buildNavigationShellKey(url, reqCtx._searchParamsFilter),
         pprConfig,
         store,
         true,
@@ -765,8 +772,30 @@ async function matchPartialWithPprReplay<TEnv>(
     recordReplayStatus(finalStatus);
     return finalStatus;
   };
+  let armFragments = false;
+  /**
+   * Every matchPartial in this function runs through this helper so the
+   * fragment flag (#700 passthrough, armed below the navigation-context gate)
+   * can never outlive a match or miss a lane — a thrown-Response redirect
+   * exit included. Mutate-restore on the SHARED reqCtx, never a derived
+   * context: the pipeline writes ambient state during the match that must
+   * land on reqCtx (_pprReplayPostMatchReason, location state,
+   * _treeHasStreaming read by the render-barrier closure). Assign-back
+   * restore leaves an own `undefined` after the first arm, matching the
+   * _shellImplicitCache idiom.
+   */
+  const matchPartialForReplay = async () => {
+    if (!armFragments) return ctx.router.matchPartial(request, { env });
+    const prevFragmentPayload = reqCtx._shellFragmentPayload;
+    reqCtx._shellFragmentPayload = true;
+    try {
+      return await ctx.router.matchPartial(request, { env });
+    } finally {
+      reqCtx._shellFragmentPayload = prevFragmentPayload;
+    }
+  };
   const runMatch = async (status?: PprReplayStatus) => {
-    const result = await ctx.router.matchPartial(request, { env });
+    const result = await matchPartialForReplay();
     // The match may have settled a fact the pre-match gate could only guess
     // at (prerender serve, intercept resolution) — report the truth.
     const finalStatus = status ? finalizeReplayStatus(status) : undefined;
@@ -803,6 +832,14 @@ async function matchPartialWithPprReplay<TEnv>(
   if (!getNavigationContextHeader(request)) {
     return runMatch({ outcome: "BYPASS", reason: "no-navigation-context" });
   }
+  // Fragment passthrough (#700), extended to partial replay. Navigation
+  // context proves the request can be matched; the separate capability header
+  // proves its payload consumer can expand envelopes. Older clients and the
+  // one-shot corruption recovery request still replay the same segment record,
+  // but through the server decode path.
+  armFragments =
+    request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) !== "1" &&
+    request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1";
   // The prerender probe and the cache-opt-out gate below both need the
   // classified snapshot; resolve (and persist) it once.
   const routeSnapshot = classifiedRouteSnapshot(reqCtx);
@@ -863,11 +900,13 @@ async function matchPartialWithPprReplay<TEnv>(
 
   let bypassReason: PprReplayBypassReason | undefined;
   let snapshot: ShellSnapshotRecord[] | undefined;
+  let snapshotStoreKey: string | undefined;
   let freshness: "fresh" | "stale" = "fresh";
   if (cached) {
     const decision = replayableShellSnapshot(cached.entry, ctx.version);
     if ("snapshot" in decision) {
       snapshot = decision.snapshot;
+      snapshotStoreKey = key;
       freshness = cached.shouldRevalidate ? "stale" : "fresh";
     } else {
       bypassReason = decision.reason;
@@ -895,6 +934,7 @@ async function matchPartialWithPprReplay<TEnv>(
       );
       if ("snapshot" in decision) {
         snapshot = decision.snapshot;
+        snapshotStoreKey = navigationKey;
         freshness = navigationCached.shouldRevalidate ? "stale" : "fresh";
       } else {
         bypassReason = decision.reason;
@@ -954,7 +994,7 @@ async function matchPartialWithPprReplay<TEnv>(
         },
       };
       try {
-        const result = await ctx.router.matchPartial(request, { env });
+        const result = await matchPartialForReplay();
         const provisionalStatus: PprReplayStatus = explicitCacheBypass
           ? { outcome: "BYPASS", reason: "cache-disabled" }
           : explicitCacheHit
@@ -999,6 +1039,7 @@ async function matchPartialWithPprReplay<TEnv>(
 
   const previousImplicitCache = reqCtx._shellImplicitCache;
   let segmentReplayHit = false;
+  let segmentReplayCorrupt = false;
   let explicitCacheHit = false;
   let explicitCacheBypass = false;
   reqCtx._shellImplicitCache = {
@@ -1011,6 +1052,9 @@ async function matchPartialWithPprReplay<TEnv>(
     onHit: () => {
       segmentReplayHit = true;
     },
+    onCorrupt: () => {
+      segmentReplayCorrupt = true;
+    },
     // Arms the explicit-scope composition in withCacheLookup: a route-derived
     // cache() scope stays authoritative, the seeded doc record supplies the
     // match only on its miss. An explicit-tier hit must NOT report a replay
@@ -1027,7 +1071,7 @@ async function matchPartialWithPprReplay<TEnv>(
   };
 
   try {
-    const result = await ctx.router.matchPartial(request, { env });
+    const result = await matchPartialForReplay();
     const provisionalStatus: PprReplayStatus = segmentReplayHit
       ? { outcome: "HIT", freshness }
       : explicitCacheHit
@@ -1040,7 +1084,18 @@ async function matchPartialWithPprReplay<TEnv>(
     // keep snapshot.cacheScope) — the "snapshot-miss" guess would blame the
     // capture for a lane that was never in play.
     const status = finalizeReplayStatus(provisionalStatus);
-    return { result, status };
+    return {
+      result,
+      status,
+      captureNeeded:
+        segmentReplayCorrupt && reqCtx._pprReplayPostMatchReason === undefined,
+      // A corrupt document snapshot must be overwritten at the document key;
+      // writing only the secondary navigation key would leave the preferred
+      // document entry shadowing the repair forever. The capture remains marked
+      // navigationOnly, so a document request ignores it and recaptures a
+      // document-safe shell under the same key.
+      captureKey: segmentReplayCorrupt ? snapshotStoreKey : undefined,
+    };
   } finally {
     reqCtx._shellImplicitCache = previousImplicitCache;
   }