@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

package/src/router/segment-resolution/fresh.ts

@@ -40,6 +40,8 @@ import {
   track,
   RangoContext,
   runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
@@ -650,6 +652,12 @@ export async function resolveAllSegments<TEnv>(
   const allSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // ppr routes are document-scoped cached territory: the whole chain (root
+  // layout down to the page) bakes into the shared shell, so the header-write
+  // guard latches BEFORE any entry resolves (unlike the positional cache()
+  // latch below). See assertCachedHeaderWriteAllowed (server/context.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   // Safe request access: during build-time prerendering, context.request
   // is a throwing getter. Use undefined when unavailable.
   let safeRequest: Request | undefined;
@@ -665,11 +673,13 @@ export async function resolveAllSegments<TEnv>(
 
   for (const entry of entries) {
     // Set ALS flag when entering a cache() boundary so that ctx.get()
-    // can guard non-cacheable variable reads. Also guards response-level
-    // side effects (headers.set). Persists for all descendant entries.
+    // can guard non-cacheable variable reads. Also latch the header-write
+    // scope (response-level side effects — headers/cookies/status).
+    // Persists for all descendant entries.
     if (entry.type === "cache") {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
@@ -718,6 +728,15 @@ export async function resolveLoadersOnly<TEnv>(
   const loaderSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // Loader-only serves (cached non-loader segments) still run loaders live —
+  // on a ppr route their header writes are dead letters (headers flushed with
+  // the shell), so the guard latches here too. cache() needs no latch: loader
+  // writes are exempt under cache() (see assertCachedHeaderWriteAllowed).
+  latchPprHeaderScopeForEntries(
+    entries,
+    (context as InternalHandlerContext<any, TEnv>)._routeName,
+  );
+
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,

package/src/router/segment-resolution/helpers.ts

@@ -71,7 +71,7 @@ export function buildLoaderErrorContext<TEnv>(
  * the short-circuit mechanism. Otherwise return the ReactNode.
  */
 export function handleHandlerResult(
-  result: ReactNode | Response | Promise<ReactNode> | Promise<Response>,
+  result: ReactNode | Response | Promise<ReactNode | Response>,
 ): ReactNode {
   if (result instanceof Response) {
     throw result;

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

@@ -185,14 +185,45 @@ export function resolveLoaderData<TEnv>(
   if (bakeSegmentKey) {
     const seed = reqCtx?._shellLoaderSeed;
     if (seed && seed.has(bakeSegmentKey)) {
-      const recorded = seed.get(bakeSegmentKey);
-      // HIT tail: run fresh (only the loader body can mint the live nested
-      // promises), then pin the recorded paths over it. A fresh REJECTION here
-      // skips the overlay and flows to the per-loader error boundary — the
-      // payload then diverges from the prelude (same residual class as uncached
-      // nondeterminism in shell material).
+      const recorded = seed.get(bakeSegmentKey)!;
+      if (!recorded.holes) {
+        // Pin-first (hole-free record): the pinned container is what the
+        // payload serves either way (recorded paths win wholesale), so
+        // resolve it immediately instead of gating on the fresh run's
+        // latency — a slow bake-lane loader body otherwise stalls the HIT
+        // tail for values that get discarded. The fresh run still executes
+        // for its side effects and cache read-through writes, lifetime-
+        // extended so the runtime cannot cancel it when the stream closes
+        // first; its rejection is swallowed here (the payload already
+        // matches the prelude, which a fresh error value never could).
+        //
+        // CONTRACT (deliberate divergence from the gated overlay's
+        // fresh-only-keys passthrough): a hole-free pin serves the pinned
+        // SHAPE wholesale — a key the fresh run adds mid-TTL is dropped.
+        // It could never render server-side anyway: no hole was postponed
+        // for it at capture, so the prelude froze the without-that-field
+        // branch and the resume pass has nothing to fill; passing it
+        // through only made the hydration payload disagree with the frozen
+        // prelude (client-side mismatch repair — the divergence class the
+        // snapshot exists to prevent). A field that is per-request must be
+        // promise-shaped at capture (masked -> hole marker -> holes: 1 ->
+        // the gated path below, which preserves fresh-only passthrough) or
+        // live behind loading(). Anything else is uncached nondeterminism
+        // in shell material — the documented drift residual.
+        const fresh = executeLoaderData(loaderEntry, ctx, pathname);
+        fresh.catch(() => {});
+        reqCtx?.executionContext?.waitUntil?.(fresh);
+        return Promise.resolve(
+          overlayLoaderContainer(undefined, recorded.container),
+        );
+      }
+      // Hole-carrying record: run fresh (only the loader body can mint the
+      // live nested promises), then pin the recorded paths over it. A fresh
+      // REJECTION here skips the overlay and flows to the per-loader error
+      // boundary — the payload then diverges from the prelude (same residual
+      // class as uncached nondeterminism in shell material).
       return executeLoaderData(loaderEntry, ctx, pathname).then(
-        (fresh: unknown) => overlayLoaderContainer(fresh, recorded),
+        (fresh: unknown) => overlayLoaderContainer(fresh, recorded.container),
       );
     }
   }

package/src/router/segment-resolution/mask-nested.ts

@@ -51,11 +51,27 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * rule, semantic-matrix PPR3) shares the raw container and must keep real
  * values. Cycles are preserved as cycles in the copy.
  */
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The shell fast path
+ * reads it at handle-push time — a pushed container with a nested thenable
+ * declares per-request data, and a shell entry whose HANDLER layer made such
+ * a declaration cannot be served handler-free (the hole would never fill).
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+  thenable: boolean;
+}
+
 export function maskNestedContainerThenables(
   value: unknown,
   seen: Map<object, unknown> = new Map(),
+  report?: MaskReport,
 ): unknown {
-  if (isThenable(value)) return createMaskedLoaderPromise();
+  if (isThenable(value)) {
+    if (report) report.thenable = true;
+    return createMaskedLoaderPromise();
+  }
 
   if (Array.isArray(value)) {
     const cached = seen.get(value);
@@ -63,7 +79,7 @@ export function maskNestedContainerThenables(
     const out: unknown[] = new Array(value.length);
     seen.set(value, out);
     for (let i = 0; i < value.length; i++) {
-      out[i] = maskNestedContainerThenables(value[i], seen);
+      out[i] = maskNestedContainerThenables(value[i], seen, report);
     }
     return out;
   }
@@ -74,7 +90,7 @@ export function maskNestedContainerThenables(
     const out: Record<string, unknown> = {};
     seen.set(value, out);
     for (const key of Object.keys(value)) {
-      out[key] = maskNestedContainerThenables(value[key], seen);
+      out[key] = maskNestedContainerThenables(value[key], seen, report);
     }
     return out;
   }

package/src/router/segment-resolution/revalidation.ts

@@ -50,6 +50,8 @@ import {
   track,
   RangoContext,
   runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
 /**
@@ -250,6 +252,9 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
   const allMatchedIds: string[] = [];
   const seenIds = new Set<string>();
 
+  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,
@@ -1260,6 +1265,9 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   const seenSegIds = new Set<string>();
   const seenMatchIds = new Set<string>();
 
+  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   const telemetry = getRouterContext()?.telemetry;
 
   for (const entry of entries) {
@@ -1283,6 +1291,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     if (entry.type === "cache") {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(

package/src/router/telemetry-otel.ts

@@ -227,6 +227,17 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           };
           if (event.routeKey) attrs["rango.route_key"] = event.routeKey;
           if (event.actionId) attrs["rango.action_id"] = event.actionId;
+          if (event.render) {
+            attrs["rango.render.mode"] = event.render.mode;
+            attrs["rango.render.phase"] = event.render.phase;
+            attrs["rango.render.state"] = event.render.state;
+            attrs["rango.render.completed"] = event.render.completed;
+            attrs["rango.render.total"] = event.render.total;
+            if (event.render.phaseDurationMs !== undefined) {
+              attrs["rango.render.phase_duration_ms"] =
+                event.render.phaseDurationMs;
+            }
+          }
           const span = instant("rango.request.timeout", attrs);
           span.setStatus({
             code: STATUS_ERROR,

package/src/router/telemetry.ts

@@ -154,6 +154,7 @@ export interface RequestTimeoutEvent extends BaseEvent {
   actionId?: string;
   durationMs: number;
   customHandler: boolean;
+  render?: import("./timeout.js").RenderTimeoutContext;
 }
 
 export interface OriginCheckRejectedEvent extends BaseEvent {

package/src/router/timeout.ts

@@ -17,6 +17,33 @@ export interface RouterTimeouts {
 
 export type TimeoutPhase = "action" | "render-start" | "stream-idle";
 
+/**
+ * Canonical render-pipeline unions, defined here (the dependency-free timeout
+ * leaf) and shared by `import type` so the render driver
+ * (rsc/render-pipeline.ts RscRenderMode/RscRenderPhase), the foreground cursor
+ * (server/request-context.ts RenderForegroundCursor), and RenderTimeoutContext
+ * below cannot drift out of sync.
+ */
+export type RenderMode =
+  | "unknown"
+  | "full"
+  | "partial"
+  | "action-revalidation"
+  | "progressive-enhancement"
+  | "progressive-enhancement-error";
+
+/** Terminal response-construction stage of the render driver. */
+export type RenderPhase = "flight" | "html" | "response";
+
+export interface RenderTimeoutContext {
+  mode: RenderMode;
+  phase: RenderPhase;
+  state: "paused" | "running";
+  completed: number;
+  total: number;
+  phaseDurationMs?: number;
+}
+
 export interface TimeoutContext<TEnv = any> {
   phase: TimeoutPhase;
   request: Request;
@@ -25,6 +52,8 @@ export interface TimeoutContext<TEnv = any> {
   routeKey?: string;
   actionId?: string;
   durationMs: number;
+  /** Foreground render operation active when a render-start timeout fired. */
+  render?: RenderTimeoutContext;
 }
 
 export type OnTimeoutCallback<TEnv = any> = (
@@ -73,6 +102,17 @@ type TimeoutResult<T> =
   | { result: T; timedOut: false }
   | { timedOut: true; durationMs: number };
 
+/**
+ * A timeout phase is active only when its budget is a positive number.
+ * `undefined`/`null` (unset) and `<= 0` (explicit opt-out, e.g.
+ * `timeouts: { renderStartMs: 0 }`) both mean pass-through. withTimeout and the
+ * render-diagnostics gate (rsc/handler.ts) share this so a disabled budget can
+ * never leave one of them still doing bookkeeping the other can never read.
+ */
+export function isTimeoutEnabled(timeoutMs: number | undefined): boolean {
+  return timeoutMs != null && timeoutMs > 0;
+}
+
 /**
  * Race an operation against a deadline.
  *
@@ -87,7 +127,7 @@ export async function withTimeout<T>(
   timeoutMs: number | undefined,
   phase: TimeoutPhase,
 ): Promise<TimeoutResult<T>> {
-  if (timeoutMs == null || timeoutMs <= 0) {
+  if (!isTimeoutEnabled(timeoutMs)) {
     return { result: await operation, timedOut: false };
   }
 

package/src/router.ts

@@ -158,7 +158,6 @@ export function createRouter<TEnv = any>(
     prefetchConcurrency: prefetchConcurrencyOption,
     stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
-    allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
     tracing: tracingOption,
     ssr: ssrOption,
@@ -168,6 +167,7 @@ export function createRouter<TEnv = any>(
     originCheck: originCheckOption,
     viewTransition: viewTransitionOption = "auto",
     debugCacheSignal: debugCacheSignalOption = false,
+    debugShellCapture: debugShellCaptureOption,
     strictMode: strictModeOption = true,
   } = options;
 
@@ -1007,6 +1007,10 @@ export function createRouter<TEnv = any>(
     // Expose router-wide performance debugging for request-level metrics setup
     debugPerformance,
 
+    // Expose the PPR shell-capture debug sink for the render layer
+    // (rsc-rendering resolves it into the capture descriptor)
+    debugShellCapture: debugShellCaptureOption,
+
     // Expose resolved span tracing for the handler (Cloudflare custom spans)
     tracing: resolvedTracing,
 
@@ -1016,9 +1020,6 @@ export function createRouter<TEnv = any>(
     // undefined when unconfigured and call sites gate on truthiness.
     telemetry: telemetrySink,
 
-    // Expose debug manifest flag for handler
-    allowDebugManifest: allowDebugManifestOption,
-
     // Expose origin check configuration for handler (default: enabled)
     originCheck: originCheckOption ?? true,
 

package/src/rsc/capture-queue.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-isolate shell-capture serialization.
+ *
+ * Captures are CPU-bound background renders whose quiet detection is
+ * task-quantized (FLIGHT_QUIET_HOPS macrotask hops with zero new bytes). Two
+ * captures running concurrently starve each other: one grinding capture —
+ * e.g. a prerender+ppr route whose capture round-trips the dev
+ * /__rsc_prerender endpoint, whose per-request module re-import can peg a
+ * slow CI runner for seconds — keeps the sibling's render byte-silent past
+ * its abort budget, so the sibling freezes a trivial prelude and stores
+ * nothing. Observed on GH runners as ROTATING eternal-MISS victims (the
+ * warmup on one shard, a composition probe, then /ppr-shell?probe=stream once
+ * the first was quieted) while every local run passed.
+ *
+ * Serializing capture execution removes the cross-talk: each capture's quiet
+ * window observes only its own work. Captures are TTL-scale background work,
+ * so queueing costs latency-to-HIT only — never a served response. On workerd
+ * a queued capture rides the scheduling request's waitUntil, whose lifetime
+ * 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.
+ */
+let captureQueue: Promise<void> = Promise.resolve();
+
+/**
+ * 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
+ * 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
+ * before its fetch was time-bounded) — must not block every later capture in
+ * the isolate. At the cap the QUEUE is released; the wedged task itself stays
+ * detached (its own per-key guards clean up when/if it settles).
+ */
+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).
+ */
+export function enqueueSerializedCapture(
+  task: () => Promise<void>,
+): Promise<void> {
+  const prior = captureQueue;
+  let releaseQueue!: () => void;
+  captureQueue = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  return (async () => {
+    await prior.catch(() => {});
+    let capTimer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        task(),
+        new Promise<void>((resolve) => {
+          capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+          (capTimer as { unref?: () => void }).unref?.();
+        }),
+      ]);
+    } finally {
+      if (capTimer) clearTimeout(capTimer);
+      releaseQueue();
+    }
+  })();
+}