@rangojs/router 0.4.2 → 0.5.0

package/src/rsc/capture-queue.ts

@@ -19,15 +19,55 @@
  * is bounded; a capture killed mid-queue by that bound simply recaptures on a
  * later request (the existing best-effort contract).
  *
- * The chain link resolves in `finally` and the prior link is awaited with a
- * swallow, so one rejected capture can never wedge every later one.
+ * Document shells outrank queued navigation-only snapshots. Production Link
+ * prefetching can enqueue several expensive navigation captures at once; a
+ * strict FIFO made the requesting page's document capture wait
+ * behind speculative work until its queue budget expired. The active capture
+ * is never interrupted, and each priority remains FIFO.
  */
-let captureQueue: Promise<void> = Promise.resolve();
 let admittedCaptures = 0;
+let captureRunning = false;
+
+interface QueuedCapture {
+  waitStart: number;
+  state: "waiting" | "running" | "settled";
+  signalStart: () => void;
+}
+
+const documentCaptures: QueuedCapture[] = [];
+const navigationCaptures: QueuedCapture[] = [];
 
 /** Bound queued/running capture closures retained by one isolate. */
 export const MAX_ADMITTED_CAPTURES: number = 32;
 
+/** Point-in-time queue occupancy, for capture-scheduling telemetry. */
+export interface CaptureQueueDepths {
+  /** A capture is currently executing (never preempted). */
+  running: boolean;
+  /** Waiting document-priority captures (run before every navigation capture). */
+  document: number;
+  /** Waiting navigation-priority captures. */
+  navigation: number;
+}
+
+/**
+ * Snapshot the queue's waiting/running state. Wait-timed-out entries still
+ * sitting in the arrays (pruned lazily by takeNextCapture) are excluded — they
+ * will never run, so counting them would overstate the backlog.
+ */
+export function captureQueueDepths(): CaptureQueueDepths {
+  const waiting = (queue: QueuedCapture[]): number => {
+    let count = 0;
+    for (const queued of queue) if (queued.state === "waiting") count++;
+    return count;
+  };
+  return {
+    running: captureRunning,
+    document: waiting(documentCaptures),
+    navigation: waiting(navigationCaptures),
+  };
+}
+
 /** The caller may drop this best-effort capture and retry on a later request. */
 export class CaptureQueueFullError extends Error {
   constructor() {
@@ -37,7 +77,35 @@ export class CaptureQueueFullError extends Error {
 }
 
 /**
- * Upper bound on how long one queue link may hold the queue. A capture task
+ * 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 running capture may hold the queue. A capture task
  * normally settles well inside this (attempt + in-place retry + writes), but
  * a task wedged on never-settling I/O — a workerd waitUntil fetch that pends
  * instead of rejecting (seen on GH runners with the dev prerender store
@@ -48,43 +116,103 @@ export class CaptureQueueFullError extends Error {
 const QUEUE_LINK_CAP_MS = 60_000;
 
 /**
- * Run `task` after every previously enqueued capture has settled. Returns a
- * promise for THIS task's completion (rejections propagate to the caller —
- * the queue itself is insulated).
+ * Run `task` after the active capture and every higher/equal-priority capture
+ * ahead of it have settled. Returns a promise for THIS task's completion
+ * (rejections propagate to the caller — the queue itself is insulated).
  */
 export function enqueueSerializedCapture(
   task: () => Promise<void>,
+  opts?: {
+    maxQueueWaitMs?: number;
+    priority?: "document" | "navigation";
+  },
 ): Promise<void> {
   if (admittedCaptures >= MAX_ADMITTED_CAPTURES) {
     return Promise.reject(new CaptureQueueFullError());
   }
   admittedCaptures++;
-  const prior = captureQueue;
-  let releaseQueue!: () => void;
-  captureQueue = new Promise<void>((resolve) => {
-    releaseQueue = resolve;
+
+  let signalStart!: () => void;
+  const startGate = new Promise<void>((resolve) => {
+    signalStart = resolve;
   });
-  return (async () => {
-    await prior.catch(() => {});
+  const queued: QueuedCapture = {
+    waitStart: performance.now(),
+    state: "waiting",
+    signalStart,
+  };
+
+  const completion = (async () => {
+    const budget = opts?.maxQueueWaitMs ?? CAPTURE_QUEUE_WAIT_BUDGET_MS;
+    let waitTimer: ReturnType<typeof setTimeout> | undefined;
+    const waitTimedOut = await Promise.race([
+      startGate.then(() => false),
+      new Promise<boolean>((resolve) => {
+        waitTimer = setTimeout(() => {
+          if (queued.state !== "waiting") return;
+          queued.state = "settled";
+          admittedCaptures--;
+          resolve(true);
+        }, budget);
+        (waitTimer as { unref?: () => void }).unref?.();
+      }),
+    ]);
+    if (waitTimer) clearTimeout(waitTimer);
+    if (waitTimedOut) {
+      throw new CaptureQueueWaitTimeoutError(
+        performance.now() - queued.waitStart,
+      );
+    }
+
     let capTimer: ReturnType<typeof setTimeout> | undefined;
     const taskPromise = Promise.resolve()
       .then(task)
       .finally(() => {
-        // A timed-out link releases serialization, but its detached task still
+        // A capped capture releases serialization, but its detached task still
         // counts against admission until it actually settles.
         admittedCaptures--;
       });
+    const cap = new Promise<void>((resolve) => {
+      capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+      (capTimer as { unref?: () => void }).unref?.();
+    });
+
     try {
-      await Promise.race([
-        taskPromise,
-        new Promise<void>((resolve) => {
-          capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
-          (capTimer as { unref?: () => void }).unref?.();
-        }),
-      ]);
+      await Promise.race([taskPromise, cap]);
     } finally {
       if (capTimer) clearTimeout(capTimer);
-      releaseQueue();
+      queued.state = "settled";
+      captureRunning = false;
+      // Handoff must happen before this caller's waitUntil promise settles.
+      // Resolving first lets workerd terminate the context with the queue lock
+      // still held, permanently parking later captures in the isolate.
+      startNextCapture();
     }
   })();
+
+  const queue =
+    opts?.priority === "document" ? documentCaptures : navigationCaptures;
+  queue.push(queued);
+  startNextCapture();
+  return completion;
+}
+
+function takeNextCapture(): QueuedCapture | undefined {
+  for (const queue of [documentCaptures, navigationCaptures]) {
+    let queued: QueuedCapture | undefined;
+    while ((queued = queue.shift())) {
+      if (queued.state === "waiting") return queued;
+    }
+  }
+  return undefined;
+}
+
+function startNextCapture(): void {
+  if (captureRunning) return;
+  const queued = takeNextCapture();
+  if (!queued) return;
+
+  captureRunning = true;
+  queued.state = "running";
+  queued.signalStart();
 }

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

@@ -79,6 +79,7 @@ import { reportCacheError } from "../cache/cache-error.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type {
+  DocumentShellCacheEntry,
   SegmentCacheStore,
   ShellCacheEntry,
   ShellSnapshotRecord,
@@ -212,7 +213,14 @@ function replayableShellSnapshot(
   if (!isValidShellHit(entry, buildVersion)) {
     return { reason: "invalid-version" };
   }
-  if (!hasIntactShellPayload(entry)) return { reason: "corrupt-entry" };
+  // navigationOnly entries store no document half (prelude/postponed absent),
+  // so the payload gate applies to document-snapshot entries alone. Replay
+  // consumes only the snapshot; fragment corruption inside it is caught by the
+  // consumer-side Flight decoders (SegmentFragmentDecodeError →
+  // segmentReplayCorrupt → healing capture at the document key).
+  if (!entry.navigationOnly && !hasIntactShellPayload(entry)) {
+    return { reason: "corrupt-entry" };
+  }
   if (entry.handlerLiveHoles) return { reason: "handler-live-holes" };
   if (entry.transitionWhen) return { reason: "transition-when" };
   // Eligibility requires the CANONICAL doc segment record (`docKey`), not just
@@ -386,7 +394,7 @@ async function handleRscRenderingInner<TEnv>(
           // build-manifest hit further down): schedule the background
           // recapture when asked, then commit the composed response.
           const serveHit = (
-            entry: ShellCacheEntry,
+            entry: DocumentShellCacheEntry,
             revalidate: boolean | undefined,
           ): Response => {
             if (revalidate) {
@@ -1159,7 +1167,7 @@ function serveShellHit(
   reqCtx: RequestContext<any>,
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   ssrModule: SSRModule,
-  entry: ShellCacheEntry,
+  entry: DocumentShellCacheEntry,
   descriptor: ShellCaptureDescriptor,
 ): Response {
   const preludeBytes = base64ToBytes(entry.prelude);

package/src/rsc/shell-build-manifest.ts

@@ -25,7 +25,11 @@
  *   markers say whether it is still current.
  */
 
-import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import type {
+  DocumentShellCacheEntry,
+  SegmentCacheStore,
+  ShellCacheEntry,
+} from "../cache/types.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import {
@@ -88,20 +92,29 @@ function loadManifest(): Promise<ShellManifestModule | null> {
  * Spec-only keying is sound because buildVersion is process-constant on the
  * manifest path (folded into the shipped worker; dev never loads a manifest).
  */
-const validatedSpecs = new Map<string, BuildShellEntry | null>();
+const validatedSpecs = new Map<string, ValidatedBuildShellEntry | null>();
+
+/**
+ * A manifest record whose document half passed hasIntactShellPayload — the
+ * casts below sit directly on that runtime gate (build entries are always
+ * document-shaped; the predicate narrows entry, not the record around it).
+ */
+type ValidatedBuildShellEntry = BuildShellEntry & {
+  entry: DocumentShellCacheEntry;
+};
 
 async function validatedManifestRecord(
   mod: ShellManifestModule,
   spec: string,
   buildVersion: string,
-): Promise<BuildShellEntry | undefined> {
+): Promise<ValidatedBuildShellEntry | undefined> {
   let verdict = validatedSpecs.get(spec);
   if (verdict === undefined) {
     const record = (await mod.loadShellAsset(spec)).default;
     verdict =
       isValidShellHit(record.entry, buildVersion) &&
       hasIntactShellPayload(record.entry)
-        ? record
+        ? (record as ValidatedBuildShellEntry)
         : null;
     validatedSpecs.set(spec, verdict);
   }
@@ -118,7 +131,7 @@ export function resetBuildShellManifestForTests(): void {
 const warnedTagCheckUnsupported = new Set<string>();
 
 export interface BuildShellHit {
-  entry: ShellCacheEntry;
+  entry: DocumentShellCacheEntry;
   /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
   stale: boolean;
 }
@@ -273,7 +286,7 @@ export async function lookupBuildShell(
     const hasManifest = globalThis.__loadShellManifestModule !== undefined;
     if (!hasManifest && !dev) return null;
     if (sortedSearchString(url.searchParams, filter) !== "") return null;
-    let record: BuildShellEntry | undefined;
+    let record: ValidatedBuildShellEntry | undefined;
     if (hasManifest) {
       const mod = await loadManifest();
       if (!mod) return null;
@@ -286,7 +299,7 @@ export async function lookupBuildShell(
         fetched !== undefined &&
         isValidShellHit(fetched.entry, buildVersion) &&
         hasIntactShellPayload(fetched.entry)
-          ? fetched
+          ? (fetched as ValidatedBuildShellEntry)
           : undefined;
     }
     if (!record) return null;