@rangojs/router 0.17.0 → 0.19.0

package/dist/types/rsc/shell-capture.d.ts

@@ -6,28 +6,24 @@
  * from the route's `ppr` path option after the served response is built and calls
  * scheduleShellCapture. The capture then runs as a background task that re-derives
  * the page via `ctx.router.match()` under its OWN derived request context — fresh
- * handle store, `_shellCaptureRun: true` so loaders mask (loader-mask.ts) and every
- * loading() subtree postpones. The render is MIXED-CHAIN: cache()'d segments replay
- * from ring 3, uncached segments execute their handlers fresh. It drives the static
- * prerender to a quiescent shell, aborts to freeze the prelude + postponed state,
- * and stores the pair via putShell. Because it uses match() rather than the HTTP
- * pipeline, the middleware chain (auth, logging) never re-runs — it already ran for
- * the triggering request, and the derived context inherits its post-middleware
- * state (variables, cache store). Guarding is serve-time.
+ * handle store, `_shellCaptureRun: true` so live-lane loaders mask (loader-mask.ts)
+ * and postpone at their loading() or inline <Suspense> boundary. The match is
+ * MIXED-CHAIN: cache()'d segments replay from ring 3, uncached segments execute
+ * their handlers. The record-first step (settleCaptureRecord) waits for the
+ * handler layer, writes the doc record every HIT replays, and renders the
+ * capture's Flight payload from it; the static prerender runs to a quiescent
+ * shell, aborts to freeze the prelude + postponed state, and putShell stores the
+ * pair with the snapshot. Because it uses match() rather than the HTTP pipeline,
+ * the middleware chain (auth, logging) never re-runs — it already ran for the
+ * triggering request, and the derived context inherits its post-middleware state
+ * (variables, cache store). Guarding is serve-time.
  */
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
-import { type RequestContext } from "../server/request-context.js";
+import { type MatchResult } from "../types.js";
+import { type RequestContext, type RouteRecordWindow } from "../server/request-context.js";
 import { type HandleStore } from "../server/handle-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { SSRModule } from "./types.js";
-/**
- * Default capture budget. Canonical value, raise rationale, and ceiling math
- * live on the leaf module (shell-capture-constants.ts, importable from the ssr
- * graph too). Re-exported here so shell-build-manifest.ts's envelope math
- * keeps its existing import site and cannot drift from the capture.
- */
-export { SHELL_CAPTURE_MAX_WAIT_MS };
 /**
  * Delay before the in-place retry of a capture that produced no usable shell.
  *
@@ -79,6 +75,7 @@ declare const REFUSED_CAPTURE_MAX_MS = 60000;
  * docs/design/ppr-shell-resume.md ("Refused-capture backoff").
  */
 declare const REFUSED_CAPTURE_DEV_MAX_MS = 2000;
+/** True iff `key` is still inside its (exponential) backoff window. */
 declare function isCaptureBackedOff(key: string): boolean;
 /**
  * Record a refused/failed capture, escalating the backoff window exponentially up
@@ -91,6 +88,13 @@ declare function isCaptureBackedOff(key: string): boolean;
 declare function markCaptureBackoff(key: string): void;
 /** Clear any backoff for a key that just captured successfully. */
 declare function clearCaptureBackoff(key: string): void;
+/**
+ * Default limit (bytes) on a whole stored shell entry — prelude, postponed
+ * state, and snapshot — when the store declares none
+ * (SegmentCacheStore.maxShellEntryBytes). Cloudflare KV's 25 MiB value limit:
+ * the tightest common store tier a shell entry lands in.
+ */
+export declare const DEFAULT_SHELL_ENTRY_MAX_BYTES: number;
 /**
  * Default cap (serialized UTF-8 bytes) on the capture data snapshot riding
  * inside a shell entry, when the route's `ppr` option does not set
@@ -100,8 +104,9 @@ declare function clearCaptureBackoff(key: string): void;
  * while still fitting any sane pinned-ring payload. Applied ONLY in
  * captureAndStoreShell (the single defaulting site — resolvePprConfig passes
  * the option through undefaulted), so every producer and direct caller gets
- * the same policy. Over the cap the snapshot is skipped (shell still stored;
- * pinned reads drift — see PartialPrerenderProps.maxSnapshotBytes).
+ * the same policy. The doc record is exempt; over the cap the other records
+ * are dropped (shell still stored and replayed; the pins' loaders read the
+ * live store — see PartialPrerenderProps.maxSnapshotBytes).
  */
 export declare const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number;
 /**
@@ -116,10 +121,13 @@ export interface ShellCaptureDebugEvent {
     key: string;
     /**
      * What happened:
-     * - stored / redirect / no-shell / refused: one capture ATTEMPT's outcome
-     *   (see CaptureAttemptOutcome for the semantics of each)
+     * - stored / redirect / no-shell / refused / expired: one capture
+     *   ATTEMPT's outcome (see CaptureAttemptOutcome for the semantics of each)
      * - error: the capture task failed with a genuine error (also routed through
      *   reportCacheError; the key is backed off)
+     * - skip-stored: a capture for the key stored after the scheduling request
+     *   read the store and missed (ShellCaptureDescriptor.storedSeqAtRead), so
+     *   the shell that request missed exists now
      * - skip-in-flight: scheduleShellCapture found a capture already running for
      *   the key (stampede guard) and scheduled nothing
      * - skip-backoff: the key is inside its refused-capture backoff window and
@@ -137,7 +145,7 @@ export interface ShellCaptureDebugEvent {
      * - backoff: the key entered (or escalated) backoff after a terminal
      *   no-shell — carries the new backoff state
      */
-    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "skip-inert-store" | "skip-queue-timeout" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "expired" | "error" | "skip-in-flight" | "skip-stored" | "skip-backoff" | "skip-capacity" | "skip-inert-store" | "skip-queue-timeout" | "backoff";
     /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
     attempt?: number;
     /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
@@ -176,14 +184,13 @@ export interface ShellCaptureDebugEvent {
      */
     queueAhead?: number;
     /**
-     * Ms the capture gate was HELD waiting for the slowest bake source — a
-     * top-level pushed handle promise or a bake-lane loader container — to
-     * settle, measured from capture start. Bake time is by-design shell latency
-     * (the hole doctrine: top-level promises bake), but it recurs on EVERY
-     * capture of the route and occupies the serialized queue; this field makes
-     * it attributable. Absent when nothing held the gate.
+     * How long the capture waited for its doc record: the handler layer's
+     * promises, async server components and handle pushes settling, then the
+     * record's encode (settleCaptureRecord). Part of the one capture deadline.
      */
-    bakeWaitMs?: number;
+    recordSettleMs?: number;
+    /** Bytes of the stored entry: prelude, postponed state, and snapshot. */
+    entryBytes?: number;
 }
 /**
  * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
@@ -245,19 +252,12 @@ export interface FlightCaptureGate {
  * closing (no holes) fires quiesce immediately for the DATA variant — the
  * TransformStream then closes the readable, so fizz completes with postponed null.
  *
- * `holdUntil` keeps the gate from FREEZING before shell material with real latency
- * has emitted. The hole doctrine bakes TOP-LEVEL pushed handle promises into the
- * shell (resolvedHandleStream awaits them before the handles row emits), but a
- * pushed promise that takes longer than the quiet window would otherwise be frozen
- * out — the handles row would never reach fizz and the prelude would come back
- * trivial. While `holdUntil` is pending, byte-quiet detection keeps running but the
- * gate neither fires nor freezes; once it resolves, the quiet counter restarts so a
- * burst of rows unblocked by it (the resolved handles row) is still captured. It
- * never delays a HOLE from postponing: holes are pending promises that emit no
- * bytes, so holding the gate open longer only ever admits shell rows. Bounded by
- * captureShellHTML's maxWaitMs like every other quiesce input.
+ * Nothing the shell bakes can still be pending here: settleCaptureRecord already
+ * waited for the top-level handle promises and the bake-lane loader containers
+ * before the capture's Flight render began, so the handles row and the baked
+ * loader rows emit at once and only the holes stay silent.
  */
-export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>, quietHops?: number, holdUntil?: Promise<unknown>): FlightCaptureGate;
+export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>): FlightCaptureGate;
 /**
  * The background shell-capture descriptor: everything the capture task needs to
  * store the shell. Built by the integrated PPR serve path (rsc-rendering.ts) from
@@ -304,16 +304,13 @@ export interface ShellCaptureDescriptor {
     tags?: string[];
     /**
      * Per-route capture settle budget in ms (`ppr.captureTimeout`, resolved by
-     * resolvePprConfig). Feeds captureShellHTML's maxWaitMs — the ONE deadline
-     * bounding the whole capture, so it covers BOTH the fizz prerender AND the
-     * deferred-material settle window (the handlesBaked/loader-container
-     * holdUntil that keeps the gate from freezing while top-level pushes are
-     * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (15_000).
+     * resolvePprConfig): the ONE deadline bounding the whole capture — the match,
+     * the record-first settle (settleCaptureRecord), then the fizz prerender with
+     * what is left (captureShellHTML's maxWaitMs). Undefined =
+     * SHELL_CAPTURE_MAX_WAIT_MS (15_000).
      */
     captureTimeout?: number;
     store?: SegmentCacheStore<any>;
-    /** Gates the concise per-attempt capture breadcrumbs (INTERNAL_RANGO_DEBUG). */
-    debug?: boolean;
     /**
      * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
      * the snapshot is skipped and the shell stored without it (reported once per
@@ -330,7 +327,17 @@ export interface ShellCaptureDescriptor {
     debugSink?: (event: ShellCaptureDebugEvent) => void;
     /** Store the snapshot for navigation replay, never the captured HTML prelude. */
     navigationOnly?: true;
+    /**
+     * lastStoredCaptureSeq(key) when a document request read the store and
+     * missed. The request schedules its capture only after rendering the MISS,
+     * so a capture another request started can store in between; a later
+     * sequence number then skips the redundant one (`skip-stored`), which would
+     * re-render the page and drop the isolate's memo of the shell just stored.
+     */
+    storedSeqAtRead?: number;
 }
+/** The latest stored capture's sequence number for `key` in this isolate, or 0. */
+export declare function lastStoredCaptureSeq(key: string): number;
 /**
  * Schedule the background shell capture for a served document. Stampede-guarded:
  * one capture per key per isolate. Runs via runBackground (waitUntil on workerd,
@@ -343,6 +350,26 @@ export interface ShellCaptureDescriptor {
  * capture enters the guarded background queue, never on response latency.
  */
 export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule | ((request: Request, url: URL) => Promise<SSRModule | null>), descriptor: ShellCaptureDescriptor): void;
+/**
+ * The ttl/swr a shell is stored with: the route's ppr policy, capped by the
+ * route cache() records the capture replayed or wrote
+ * (RequestContext._routeRecordWindow). A HIT replays the capture's handler
+ * output, while a client navigation reads the route's cache() tier first, so
+ * a shell that outlived its record would show a document request other
+ * handler output than a navigation of the same URL. Freshness and total
+ * lifetime are capped separately, like the record's own SWR: the shell is
+ * fresh while the record is (at most `ttl`), and servable while the record
+ * is (at most `ttl + swr`), so a record already inside its swr window yields
+ * a shell that is stale from the start and serves while it recaptures.
+ *
+ * Whole seconds, rounded up (the SegmentCacheStore.putShell contract), so the
+ * shell may outlast the record by under a second. Null when the record's
+ * total lifetime has run out: the shell would be dead on arrival.
+ */
+export declare function capShellWindow(ttl: number, swr: number, record: Pick<RouteRecordWindow, "freshUntil" | "staleUntil">, now: number): {
+    ttl: number;
+    swr: number;
+} | null;
 /**
  * The outcome of one capture attempt.
  * - `stored`: a usable shell was captured (and a putShell was attempted; a store
@@ -350,18 +377,49 @@ export declare function scheduleShellCapture(ctx: HandlerContext<any>, request:
  *   the capture itself worked).
  * - `redirect`: the matched route redirects, so there is no shell to capture.
  * - `no-shell`: captureShellHTML returned null because the prelude was unusable
- *   or its private capture abort landed before the shell completed. This is the
- *   only RETRYABLE outcome.
+ *   or its private capture abort landed before the shell completed, or the
+ *   capture ran out of ppr.captureTimeout. Retried once in place, when no
+ *   deadline ran out (CaptureAttemptStats.noShellCause).
+ * - `expired`: the route cache() record the capture read (not wrote) ran out
+ *   before the store (capShellWindow null): it was near its end (its age,
+ *   queue wait). Retried once in place, where a fresh match reads or renders
+ *   a newer record; an `expired` retry, or no hard-cap budget left for the
+ *   retry, is terminal `no-shell` (backoff, warned once per route).
+ */
+type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused" | "expired";
+/**
+ * What a capture task ends with (runShellCapture): a refusal and a terminal
+ * `expired` are `no-shell`, which the scheduler backs off.
  */
-type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
+type CaptureTaskOutcome = "stored" | "redirect" | "no-shell";
 /**
- * Per-attempt observability fields, filled along the capture path (barrier in
- * attemptCapture, the rest in captureAndStoreShell) and folded into the
- * attempt's {@link ShellCaptureDebugEvent} by runShellCapture. A plain mutable
- * bag, not a return value: captureAndStoreShell's outcome type stays a string
- * union its existing callers (producer B, tests) consume unchanged.
+ * One attempt's record, filled along the capture path (barrier and deadline
+ * causes in attemptCapture, the rest in captureAndStoreShell). runShellCapture
+ * folds the observability fields into the attempt's
+ * {@link ShellCaptureDebugEvent} and reads the rest to decide the retry and
+ * the warning. A plain mutable bag, not a return value: captureAndStoreShell's
+ * outcome type stays a string union producer B consumes unchanged.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "bakeWaitMs">;
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "recordSettleMs" | "entryBytes"> & {
+    /**
+     * Why a no-shell attempt ran out of ppr.captureTimeout (the match, the
+     * handler output, or the prerender after them). A set cause skips the
+     * in-place retry: the attempt's match may still be running.
+     */
+    noShellCause?: string;
+    /**
+     * Dev only: component stacks of the tasks still pending at a no-shell
+     * attempt's abort, reported through prerender's onError (captureShellHTML's
+     * onAbortedTask).
+     */
+    pendingStacks?: string[];
+    /** The route cache() record an `expired` attempt ran out on. */
+    expired?: {
+        route: string;
+        record: RouteRecordWindow;
+        captureMs: number;
+    };
+};
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -373,26 +431,84 @@ type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "write
  * when we froze the shell; the attempt itself warmed the module graph, so a second
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
- * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`; a
- * genuine render error is NOT retried — it propagates to scheduleShellCapture's
- * reportCacheError. See docs/design/ppr-shell-resume.md.
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`
+ * that did not run out of ppr.captureTimeout (CaptureAttemptStats.noShellCause),
+ * and on `expired`; a genuine render error is NOT retried — it propagates to
+ * scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
  *
- * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
- * drive the retry without a real 400ms wall-clock wait.
+ * `request` and `url` are the capture's own identity (scheduleShellCapture
+ * strips a navigation-only capture's transport parameters). `retryDelayMs` is
+ * a parameter (defaulting to the module const) so unit tests can drive the
+ * retry without a real 400ms wall-clock wait.
+ */
+declare function runShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor, retryDelayMs?: number): Promise<CaptureTaskOutcome>;
+/**
+ * What the record-first step produced ({@link settleCaptureRecord}):
+ * - `record`: the doc record settled; `match` carries its fragments in place
+ *   of the handler layer's elements, so the capture's Flight payload is the
+ *   bytes every HIT replays.
+ * - `prerender`: the prerender store supplied the handler layer (a
+ *   Prerender route); its HIT tail replays the same build-time segments, so
+ *   the capture renders the match as is.
+ * - `timeout`: handler output did not settle within the capture budget.
+ * - `refused`: a deterministic refusal (a capture guard tripped, the route
+ *   opted out, or the handler output failed); the warning already fired.
  */
-declare function runShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor, retryDelayMs?: number): Promise<CaptureAttemptOutcome>;
+export type CaptureRecordOutcome = {
+    kind: "record" | "prerender";
+    match: MatchResult;
+} | {
+    kind: "timeout";
+    reason: string;
+} | {
+    kind: "refused";
+};
+/**
+ * Record-first capture: the doc record is both the settle signal and the
+ * parity source.
+ *
+ * Writing the record Flight-serializes every non-loader segment
+ * (serializeSegments), which runs each handler's async server components and
+ * waits for every promise the handler output carries — the capture's "is the
+ * handler layer done" signal. Live-lane loader data is not in the record
+ * (loader segments are excluded and their masked promises never settle), so
+ * the wait never depends on a hole.
+ *
+ * The capture then renders its OWN Flight payload from the record's
+ * fragments (fragmentSegments, the function a HIT tail uses) instead of from
+ * the elements the match produced. Server components therefore render once
+ * per capture, inside the record's encode: before this, the capture's Flight
+ * render and the record's encode each ran them, so an uncached async
+ * component showed one value in the prelude and another on every HIT.
+ *
+ * Order, all bounded by the one capture deadline (`ppr.captureTimeout`):
+ * top-level handle promises, the handler pushes' nested promises, and the
+ * bake-lane loader containers settle first (the record encodes the handles
+ * a HIT restores, and its handle encode has its own 5s timeout that must
+ * never be the one that fires); then the capture's onResponse callbacks fire
+ * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
+ * scope's own write), and the deferred writes settle.
+ */
+export declare function settleCaptureRecord(match: MatchResult, derivation: CaptureContextDerivation, capture: Pick<ShellCaptureDescriptor, "key">, deadline: number): Promise<CaptureRecordOutcome>;
 /**
  * The derived capture context and its fresh (mask-funneled) handle store,
  * shared by BOTH shell producers: the runtime background capture
  * (attemptCapture, producer A) and the build-time prerender shell capture
  * (prerender/build-shell-capture.ts, producer B — issue #699). One
- * implementation so the capture semantics — the nested-thenable mask funnel,
- * handler-liveness bookkeeping, snapshot recording, the implicit doc-cache
- * scope — cannot drift between producers.
+ * implementation so the capture semantics — the handle push funnel (handler
+ * pushes settled, loader pushes masked), the capture guards, snapshot
+ * recording, the implicit doc-cache scope — cannot drift between producers.
  */
 export interface CaptureContextDerivation {
     derivedCtx: RequestContext;
     freshHandleStore: HandleStore;
+    /**
+     * Resolves once every handler handle push has settled at any depth of
+     * plain objects and arrays (top-level promise, then the promises nested
+     * in what it resolved to). The record-first step awaits it before the doc
+     * record encodes its handles, so that encode never races a pending value.
+     */
+    handlerPushesSettled: () => Promise<void>;
 }
 /**
  * Derive the capture request context from a base context. Producer A passes
@@ -407,19 +523,31 @@ export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, d
     url: URL;
 }): CaptureContextDerivation;
 /**
- * Seal handles, derive the quiesce signal, prerender + abort via the SSR module's
- * captureShellHTML, and store the result. Returns the attempt outcome (the caller
- * owns retry/warn decisions — this function no longer warns). Never throws out of
- * the store write: a failed putShell is routed through reportCacheError so the
- * background task stays best-effort, and the attempt still counts as `stored` (the
- * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
- * present (eligibility is checked before scheduling).
+ * Derive the quiesce signal, prerender + abort via the SSR module's
+ * captureShellHTML, and store the result. Runs after settleCaptureRecord (both
+ * producers), which sealed the capture's handle store (`reqCtx._handleStore`)
+ * and waited for everything the shell bakes. Returns the attempt outcome (the
+ * caller owns retry/warn decisions). Never throws out of the store write: a
+ * failed putShell is routed through reportCacheError so the background task
+ * stays best-effort, and the attempt still counts as `stored` (the capture
+ * worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
+ * present (eligibility is checked before scheduling). `captureStartedAt` is the
+ * capture generation's start, stamped before the match (ShellCacheEntry
+ * .createdAt).
  *
  * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
  * captureShellHTML error propagates to reportCacheError and is NOT retried. The
  * capture handler converts only its own private abort sentinel to null before this
  * layer sees it.
  */
-declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, handleStore: HandleStore, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, stats?: CaptureAttemptStats, captureStartedAt?: number): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
+declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, captureStartedAt: number, stats?: CaptureAttemptStats): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
 export { runShellCapture, captureAndStoreShell, delay, SHELL_CAPTURE_RETRY_DELAY_MS, };
 export { isCaptureBackedOff, markCaptureBackoff, clearCaptureBackoff, REFUSED_CAPTURE_BASE_MS, REFUSED_CAPTURE_MAX_MS, REFUSED_CAPTURE_DEV_MAX_MS, };
+/**
+ * @internal Reset this module's per-isolate state: the capture stampede
+ * guard, the refused-capture backoff, the once-per-key warnings (the shell
+ * path's one registry), the stored-capture sequence and the buffered debug
+ * events. Tests only (testing/serve-shell-request.ts resetShellTestState),
+ * between requests, never while a capture runs.
+ */
+export declare function resetShellCaptureStateForTests(): void;