@rangojs/router 0.4.2 → 0.5.0

package/src/cache/types.ts

@@ -198,6 +198,16 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<"stored" | "invalidated" | void>;
 
+  /**
+   * Declares the shell family present-but-inert: getShell/putShell exist but
+   * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
+   * captures whose only write target is inert — the background render would be
+   * dead work that still occupies the per-isolate serialized capture queue
+   * (a promise-heavy route bakes for seconds per MISS with nothing stored).
+   * Absent/false means the family, when present, actually stores.
+   */
+  shellFamilyInert?: boolean;
+
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.
@@ -264,8 +274,8 @@ export interface CacheItemResult {
 /**
  * A cached PPR (Partial Pre-rendering) shell entry.
  *
- * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
- * and React's postponed state — because the pair is version- and
+ * A DOCUMENT entry carries BOTH artifacts a resume needs — the rendered HTML
+ * prelude and React's postponed state — because the pair is version- and
  * generation-coupled and must never be mixed across a React upgrade or a build
  * change. The reactVersion and buildVersion fields are the read-time gates that
  * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
@@ -274,15 +284,28 @@ export interface CacheItemResult {
  * positions against one exact tree; resuming it against a different React or a
  * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
  * are committed — an unrecoverable broken serve).
+ *
+ * A `navigationOnly` entry stores NEITHER half: nothing ever serves its HTML
+ * (document serving skips navigationOnly entries at the read gate, and partial
+ * replay consumes only `snapshot`/`docKey`), so the prelude would ride every
+ * store write and read as dead weight at KV-value scale. The capture still runs
+ * the full fizz prerender — it is the completeness arbiter and sanity gate —
+ * but its output is dropped before putShell. hasIntactShellPayload is the
+ * document-half gate; navigationOnly entries never satisfy it.
  */
 export interface ShellCacheEntry {
-  /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
-  prelude: string;
+  /**
+   * Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing).
+   * Absent on `navigationOnly` entries (no document half is stored — see the
+   * interface doc); present on every document-servable entry.
+   */
+  prelude?: string;
   /**
    * JSON.stringify of React's postponed state, or null when the shell settled
-   * with no holes (the DATA variant — served without a fizz resume).
+   * with no holes (the DATA variant — served without a fizz resume). Absent
+   * exactly when `prelude` is (navigationOnly entries).
    */
-  postponed: string | null;
+  postponed?: string | null;
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
   /**
@@ -366,6 +389,18 @@ export interface ShellCacheEntry {
   createdAt: number;
 }
 
+/**
+ * A shell entry whose document half is present — what the document HIT path
+ * (serveShellHit / lookupBuildShell) consumes. hasIntactShellPayload
+ * (rsc/shell-serve.ts) is the runtime gate AND the type narrowing to this
+ * shape; navigationOnly entries never pass it (their document half is not
+ * stored).
+ */
+export type DocumentShellCacheEntry = ShellCacheEntry & {
+  prelude: string;
+  postponed: string | null;
+};
+
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family

package/src/cache/vercel/vercel-cache-store.ts

@@ -184,10 +184,13 @@ interface VercelResponseEnvelope {
 
 /** Stored envelope for a PPR shell entry (getShell/putShell). */
 interface VercelShellEnvelope {
-  /** base64-encoded prelude bytes. */
-  p: string;
-  /** postponed state JSON, or null (DATA variant). */
-  po: string | null;
+  /**
+   * base64-encoded prelude bytes. Absent iff `no` (navigationOnly entries
+   * store no document half — ShellCacheEntry.prelude).
+   */
+  p?: string;
+  /** postponed state JSON, or null (DATA variant). Absent iff `no`. */
+  po?: string | null;
   /** React.version at capture. */
   rv: string;
   /** Build version at capture (ShellCacheEntry.buildVersion). */
@@ -868,8 +871,11 @@ export class VercelCacheStore<
           ? Math.min(totalTtl, TAG_MARKER_TTL_SECONDS)
           : totalTtl;
       const env: VercelShellEnvelope = {
-        p: entry.prelude,
-        po: entry.postponed,
+        // Presence-keyed: a navigationOnly entry has no document half, and an
+        // omitted key (vs an explicit undefined) also keeps it out of the
+        // serialized JSON.
+        ...(entry.prelude !== undefined ? { p: entry.prelude } : {}),
+        ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
         rv: entry.reactVersion,
         bv: entry.buildVersion,
         c: entry.createdAt,
@@ -1210,13 +1216,21 @@ export class VercelCacheStore<
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
     const { p, po, rv, bv, c, s, e, t, i, sn, dk, lh, tw, no } = raw;
-    if (typeof p !== "string" || typeof rv !== "string") return null;
-    if (po !== null && typeof po !== "string") return null;
+    if (typeof rv !== "string") return null;
+    // Document half: required unless navigationOnly (`no`), which stores
+    // neither field. Tolerate a legacy navigationOnly envelope that still
+    // carries them.
+    if (p === undefined ? no !== true : typeof p !== "string") return null;
+    if (
+      po === undefined ? no !== true : po !== null && typeof po !== "string"
+    ) {
+      return null;
+    }
     if (typeof c !== "number") return null;
     if (typeof s !== "number" || typeof e !== "number") return null;
     return {
-      p,
-      po: po as string | null,
+      ...(typeof p === "string" ? { p } : {}),
+      ...(po !== undefined ? { po: po as string | null } : {}),
       rv,
       bv: typeof bv === "string" ? bv : undefined,
       c,

package/src/cloudflare/tracing.ts

@@ -1,10 +1,11 @@
 /**
  * Cloudflare custom-spans integration.
  *
- * Bridges the router's performance phases (request, middleware, action,
- * loaders, handler, render, ssr) onto Cloudflare Workers custom spans so they show
- * up in the trace waterfall and OpenTelemetry exports next to the platform's
- * automatic spans (KV reads, D1 queries, fetch calls), with correct nesting.
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto Cloudflare Workers custom
+ * spans so they show up in the trace waterfall and OpenTelemetry exports next
+ * to the platform's automatic spans (KV reads, D1 queries, fetch calls), with
+ * correct nesting.
  *
  * Usage (Cloudflare preset only):
  *
@@ -27,12 +28,15 @@
  *
  * Span duration note: enterSpan ends a span when its callback's returned value
  * (or promise) settles. For the streaming phases (request/render/ssr) that is at
- * stream CONSTRUCTION, not body-drain. Instrumentation is best-effort and never
- * wraps or buffers the response body, so it cannot regress streaming or latency.
- * A loader/Suspense child that resolves mid-stream therefore keeps a rango.loader
- * span that can extend past its render parent — overlapping spans are valid. Uses
- * only the typed enterSpan API; spans bound work up to stream-handoff, matching
- * the co-emitted perf metric.
+ * stream CONSTRUCTION, not body-drain; rango.response marks that handoff
+ * boundary explicitly (it wraps only response finalization, never the body).
+ * Instrumentation is best-effort and never wraps or buffers the response body,
+ * so it cannot regress streaming or latency. A loader/Suspense child that
+ * resolves mid-stream therefore keeps a rango.loader span that can extend past
+ * its render parent — overlapping spans are valid. Uses only the typed enterSpan
+ * API; spans bound work up to stream-handoff, matching the co-emitted perf
+ * metric. On deployed Workers a rango.response span may report 0 ms (non-I/O
+ * timers are frozen); its position and attributes are the value.
  */
 
 import { _getRequestContext } from "../server/request-context.js";
@@ -91,8 +95,8 @@ const cloudflareSpanRunner: SpanRunner = (name, fn) => {
 /**
  * Create the tracing config for a Cloudflare router. Pass the result to
  * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
- * action, loaders, handler, render, and ssr phases; pass `spans` to turn
- * individual phases off.
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
  *
  * @see createOTelTracing (`@rangojs/router`) for the same slot on any platform
  *   with an OpenTelemetry SDK.

package/src/router/instrument.ts

@@ -5,13 +5,11 @@
  * The router exposes the same work on three surfaces, and the rule is: each
  * surface has exactly one owner here, so they cannot drift.
  *
- *   - observePhase(): a span of work. Co-emits the `debugPerformance` perf
- *     metric (metrics store -> [RSC Perf] timeline + Server-Timing) AND the
- *     platform span (tracing runner -> Cloudflare custom spans / OTel). From one
- *     wrap site, so the span set is always a subset of the perf phases and the
- *     two can't disagree. Phases that meter their own perf metric with a finer
- *     decomposition (request, middleware) pass `metric: false` and get the span
- *     only — still co-located, still one owner per surface.
+ *   - observePhase(): a span of work. From one wrap site, emits the platform
+ *     span (tracing runner -> Cloudflare custom spans / OTel) and, when the
+ *     phase has one, its `debugPerformance` metric (metrics store -> [RSC Perf]
+ *     timeline + Server-Timing). Phases that meter their own perf metric with a
+ *     finer decomposition, or are deliberately span-only, pass `metric: false`.
  *   - observeEvent(): a discrete fact (TelemetrySink): cache decisions,
  *     revalidation decisions, handler errors, timeouts, origin rejections.
  *     Event-shaped, not phase-shaped — derived from the same call sites but a
@@ -85,6 +83,16 @@ function currentRouteName(): string | undefined {
     : undefined;
 }
 
+/**
+ * The detached background lanes wrapped by the rango.background span (the
+ * `rango.background.kind` attribute). One name per task execution boundary.
+ */
+export type BackgroundTaskKind =
+  | "shell-capture"
+  | "document-revalidation"
+  | "loader-revalidation"
+  | "use-cache-revalidation";
+
 /**
  * The router's observable phases. One definition per phase keeps the `rango.*`
  * span names, perf-metric labels, and identifying attributes from spreading
@@ -176,6 +184,43 @@ export const PHASES = {
     tracePhase: "ssr",
     spanName: "rango.ssr",
   } as PhaseSpec,
+
+  /**
+   * One detached background task (waitUntil work that outlives the response):
+   * a PPR shell capture or an SWR background revalidation. The wrapper is the
+   * explanatory parent for everything the task does — the platform's automatic
+   * KV/fetch/cache spans, and (for the revalidation lanes) the re-run's own
+   * rango.* phase spans — so post-handoff work never appears as orphan spans
+   * dangling under an ended foreground phase. `kind` identifies the lane.
+   * Span only (metric:false): the perf timeline is finalized with the
+   * response, so a background metric could never reach it. The shell-capture
+   * lane keeps its INNER phase spans suppressed (derived context strips
+   * _tracing — a capture re-render duplicating the foreground's span set was
+   * the original #670 leak); the revalidation lanes keep theirs, nested here.
+   */
+  background: (kind: BackgroundTaskKind): PhaseSpec => ({
+    metric: false,
+    tracePhase: "background",
+    spanName: "rango.background",
+    attributes: { "rango.background.kind": kind },
+  }),
+
+  /** Final response construction + host handoff: opened AFTER downstream
+   * middleware/core execution returns a Response, wrapping only finalization
+   * (redirect interception/guarding, Server-Timing mutation, final response
+   * selection) and ending immediately before the router handler returns the
+   * response to the host. Handoff-bound, never drain-bound — it must never
+   * read, tee, buffer, or await response.body, so it cannot regress streaming.
+   * At most one per traced request; absent when the request throws before a
+   * response exists. Span only (metric:false) — a co-emitted metric would
+   * circularly mutate the Server-Timing header this phase itself finalizes.
+   * On Cloudflare it may report 0 ms (non-I/O timers are frozen); its position
+   * and attributes (status/mode/body kind, set by the handler) are the value. */
+  response: {
+    metric: false,
+    tracePhase: "response",
+    spanName: "rango.response",
+  } as PhaseSpec,
 } as const;
 
 /** Apply a phase spec's static attributes to a span (the no-op span ignores them). */
@@ -209,14 +254,15 @@ function recordPhaseMetric(
  * returns a promise both the metric duration and the span end when it settles.
  *
  * This is the ONLY phase primitive: every phase (request/middleware/action/
- * loader/handler/render/ssr) is construction-bound — the span and metric settle
- * when fn's own work completes (for the streaming phases, when the RSC/HTML
- * stream is constructed, NOT when the body drains). Instrumentation is strictly
- * best-effort: it never wraps or buffers the response and adds no work on the
- * streaming path, so it cannot regress response latency or streaming. A loader
- * that resolves while the body streams therefore keeps a rango.loader span that
- * may extend past its render parent — overlapping spans are valid; the loader
- * really did take that long.
+ * loader/handler/render/ssr/response/background) settles when fn's own work
+ * completes. For streaming phases that means when the RSC/HTML stream is
+ * constructed, NOT when the body drains; for response, when finalization hands
+ * the stream to the host. Instrumentation is strictly best-effort: it never
+ * wraps or buffers the response and adds no work on the streaming path, so it
+ * cannot regress response latency or streaming. A loader that resolves while
+ * the body streams therefore keeps a rango.loader span that may extend past its
+ * render parent — overlapping spans are valid; the loader really did take that
+ * long.
  *
  * Reads the metrics store + tracing off the RequestContext ALS, which is active
  * for the WHOLE request — contrast observeEvent, which reads the RouterContext

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

@@ -26,6 +26,7 @@ import {
   _getRequestContext,
   runWithRequestContext,
 } from "../../server/request-context.js";
+import { observePhase, PHASES } from "../instrument.js";
 import { sortedRouteParams } from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
@@ -328,7 +329,17 @@ function executeLoaderData<TEnv>(
       setItem: (k, v, o) => store.setItem!(k, v, o),
       key,
       execute: () => runMiss(loaderEntry.loader),
-      wrapBackground: (run) => runWithRequestContext(requestCtxForExecute, run),
+      // The rango.background span (kind=loader-revalidation) wraps the WHOLE
+      // stale revalidation — the re-execution AND the serialize/setItem write
+      // (read-through-swr routes the full task through wrapBackground) — so
+      // the loader's rango.loader span, its fetch/KV platform spans, and the
+      // store write all nest under one explanatory parent instead of dangling
+      // under the ended foreground phases. Inside runWithRequestContext so
+      // observePhase can read tracing on workerd (ALS detaches in waitUntil).
+      wrapBackground: (run) =>
+        runWithRequestContext(requestCtxForExecute, () =>
+          observePhase(PHASES.background("loader-revalidation"), run),
+        ),
       serialize: (d) => codec.serializeResult(d),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },

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

@@ -33,6 +33,7 @@ import {
   isTraceActive,
 } from "../logging.js";
 import { resolveLoaderData } from "./loader-cache.js";
+import { entryLoadingMasksLoaders } from "./loader-mask.js";
 import {
   handleHandlerResult,
   warnOnStreamedResponse,
@@ -206,6 +207,15 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   // onError/loader.error. isPartial flags the reporting phase accordingly.
   const errorContext = { ...buildLoaderErrorContext(ctx), isPartial: true };
 
+  // PPR lane decision, same rule as the fresh funnel (fresh.ts): an entry
+  // without renderable loading() puts its loaders on the BAKE lane. The key
+  // must thread through EVERY resolveLoaderData funnel — omitting it here made
+  // a capture-active context whole-container-mask every loader on this path
+  // (a never-settling promise for a loader that should have executed).
+  // Outside capture the key only activates the _shellLoaderSeed overlay,
+  // which document-only serveShellHit seeds — inert for partial requests.
+  const bakeLane = !entryLoadingMasksLoaders(entry.loading);
+
   const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
   const segments: ResolvedSegment[] = loadersToRun.map(
     ({ loaderEntry, loader, segmentId, index }) => ({
@@ -218,7 +228,12 @@ export async function resolveLoadersWithRevalidation<TEnv>(
       loaderId: loader.$$id,
       loaderData: deps.wrapLoaderPromise(
         runInsideLoaderScope(() =>
-          resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+          resolveLoaderData(
+            loaderEntry,
+            ctx,
+            ctx.pathname,
+            bakeLane ? segmentId : null,
+          ),
         ),
         entry,
         segmentId,

package/src/router/telemetry-otel.ts

@@ -6,10 +6,10 @@
  *   - createOTelTracing(tracer): the OTel adapter for the `tracing` SLOT — the
  *     canonical phase-span layer. It bridges observePhase's callback boundary
  *     onto OTel's callback-bound `startActiveSpan`, so the router's phase spans
- *     (rango.request/middleware/loader/render/ssr) nest by async context and the
- *     loader's own OTel spans (db/fetch) land under rango.loader. This is the
- *     OTel equivalent of createCloudflareTracing — pass it to
- *     `createRouter({ tracing })`.
+ *     (rango.request/middleware/action/loader/handler/render/ssr/response/
+ *     background) nest by async context and the loader's own OTel spans
+ *     (db/fetch) land under rango.loader. This is the OTel equivalent of
+ *     createCloudflareTracing — pass it to `createRouter({ tracing })`.
  *
  *   - createOTelSink(tracer): the OTel adapter for the `telemetry` SLOT — a
  *     TelemetrySink for the EVENT-shaped facts (handler errors, cache decisions,

package/src/router/timeout.ts

@@ -11,7 +11,18 @@ export interface RouterTimeouts {
   actionMs?: number;
   /** Timeout for initial render/response production (ms). */
   renderStartMs?: number;
-  /** Timeout for idle streaming after render starts (ms). Reserved for PR 2. */
+  /**
+   * Timeout for idle streaming after the response is handed off (ms): when no
+   * chunk flows to the client for this long, the body stream is errored with a
+   * RouterTimeoutError ("stream-idle") and the source render is canceled —
+   * bounding hangs from never-settling promises embedded in the payload.
+   * END-TO-END semantics: a stalled slow client counts as idle the same as a
+   * wedged producer, so pick generous budgets (seconds). Opt-in (unset =
+   * unbounded, and the `timeout` shorthand deliberately does not apply);
+   * onTimeout does NOT fire — no replacement Response can be served
+   * mid-stream — the trip reports via onError + the request.timeout event.
+   * Enforcement: rsc/stream-idle.ts, wired at the handler's response tail.
+   */
   streamIdleMs?: number;
 }
 

package/src/router/tracing.ts

@@ -1,11 +1,12 @@
 /**
  * Span tracing hook (platform-agnostic).
  *
- * The core router emits its existing performance phases (request, middleware, action,
- * loaders, render, ssr) as spans by calling traceSpan() at a small set of
- * execution boundaries. When no tracing is configured the call is a direct
- * pass-through: fn is invoked with a no-op span, with no wrapper and no
- * allocation, so a non-traced request behaves exactly as before.
+ * The core router emits its observable phases (request, middleware, action,
+ * loaders, handler, render, ssr, response, background) as spans by calling
+ * traceSpan() at a small set of execution boundaries. When no tracing is
+ * configured the call is a direct pass-through: fn is invoked with a no-op
+ * span, with no wrapper and no allocation, so a non-traced request behaves
+ * exactly as before.
  *
  * A platform integration supplies a SpanRunner that wraps fn in a real span.
  * Two runners ship: the Cloudflare one (createCloudflareTracing in
@@ -29,7 +30,10 @@
  * useLoader, plus the fetchable path), rango.handler (span-only, one per segment
  * route/layout handler execution; the handler:<id> perf metric is owned by the
  * track() at the call site), rango.render (render:total:<route>; normal AND
- * action-revalidation renders), rango.ssr (ssr:render-html).
+ * action-revalidation renders), rango.ssr (ssr:render-html), rango.response
+ * (span-only; final response construction + host handoff — the explicit
+ * stream-handoff marker), and rango.background (span-only; detached work, see
+ * below).
  *
  * Span-duration caveat (best-effort, never buffers): a span ends when its
  * callback's value (or promise) settles. For the streaming phases (request,
@@ -40,6 +44,19 @@
  * rango.loader span that can extend past its render parent; overlapping spans are
  * valid (the loader really did take that long). Phase spans bound the work up to
  * stream-handoff, which is also what the co-emitted perf metric measures.
+ * rango.response makes that handoff boundary explicit: it wraps only response
+ * finalization (redirect interception/guarding, Server-Timing mutation, final
+ * response selection) after downstream execution returns, ending immediately
+ * before the handler returns the Response to the host. It is handoff-bound,
+ * never drain-bound — it never reads, tees, or awaits response.body, and it is
+ * absent when the request throws before a response exists.
+ *
+ * rango.background wraps DETACHED work (waitUntil tasks that outlive the
+ * response): PPR shell captures and SWR background revalidations. It is the
+ * explanatory parent for spans those tasks produce after the foreground
+ * phases ended — without it, post-handoff work reads as orphan spans dangling
+ * under an ended parent. See PHASES.background (instrument.ts) for the lane
+ * kinds and per-lane inner-span policy.
  *
  * Both shipped runners (Cloudflare, OTel) keep the core agnostic: the
  * platform-specific bridge lives at the edge behind the SpanRunner contract.
@@ -68,18 +85,17 @@ export type TracePhase =
   | "loader"
   | "handler"
   | "render"
-  | "ssr";
+  | "ssr"
+  | "response"
+  | "background";
 
-/** Per-phase span toggles. Omitted phases default to enabled. */
-export interface TracePhaseToggles {
-  request?: boolean;
-  middleware?: boolean;
-  action?: boolean;
-  loader?: boolean;
-  handler?: boolean;
-  render?: boolean;
-  ssr?: boolean;
-}
+/**
+ * Per-phase span toggles. Omitted phases default to enabled. Derived from
+ * TracePhase so a new phase cannot be silently missing here — the other phase
+ * lists in this file (ALL_PHASES_ON, resolveTracing) are exhaustiveness-checked
+ * by their Record<TracePhase, boolean> annotations.
+ */
+export type TracePhaseToggles = Partial<Record<TracePhase, boolean>>;
 
 /**
  * The option pair shared by every tracing factory (enabled master switch +
@@ -125,6 +141,8 @@ const ALL_PHASES_ON: Record<TracePhase, boolean> = {
   handler: true,
   render: true,
   ssr: true,
+  response: true,
+  background: true,
 };
 
 /**
@@ -153,6 +171,8 @@ export function resolveTracing(
           handler: spans.handler ?? true,
           render: spans.render ?? true,
           ssr: spans.ssr ?? true,
+          response: spans.response ?? true,
+          background: spans.background ?? true,
         }
       : ALL_PHASES_ON,
   };