Skip to content

Commit 4873773

Browse files
committed
feat(ppr): captureTimeout route option + handle-settle capture gate; nameless-ppr coverage (closes #714, #715)
resolvePprConfig -> ShellCaptureDescriptor -> captureShellHTML maxWaitMs, bounding BOTH the fizz prerender and the deferred-material settle window. The freeze is ORDERED behind full handle-stream convergence: the gate never fires while a top-level push is pending, staged/chained pushes (immediate + slow + Meta chained off the slow one) converge to a single yield, and budget expiry with pending pushes yields a body-less prelude -> sanity-gate refusal — a partial-prefix bake (wrong/missing meta in the snapshot) is unrepresentable. Producer B and the dev /__rsc_shell read-through honor the same knob; the dev fetch bound now models the FULL server envelope (probe + 2x budget + retry margin — the old 2x+10s bound was exceedable even at defaults, aborting healthy captures into spurious MISSes). workerd waitUntil (~30s) documented as ceiling. DSL stores ppr on the synthesized $path_* entry regardless of name (path-helper.ts); the field symptom was a stale-server artifact plus the pre-#705 Accept-negotiation silence. Nameless param-bearing ppr fixtures + MISS->HIT e2e now pin the combination in both apps. Red->green: slow-meta fixture (5.5s push + 1s chained Meta) with the plumb reverted stays eternal-MISS with the once-per-key warning; restored, it HITs with the resolved chained <title> frozen in the stored prelude. The no-knob sibling remains the permanent in-tree red pin. Validated end-to-end in a real storefront (7s deferred meta chain, captureTimeout: 12000 -> HIT at 16s, baked title byte-frozen across HITs, package restored after). Simplify review applied (6): shared normalizeCaptureTimeout (was 3 copies), complete dev fetch-bound formula w/ hoisted DEV_SHELL_PROBE_TIMEOUT_MS, 2 duplicate fixture components deleted, comment triplication collapsed, stale timing comment fixed, duplicate 6.5s live-path test folded into the MISS body read. Skipped (noted): test-local splitPrelude convention; cross-app fixture duplication (different presets/negatives — deliberate). Batteries: router unit 5112; shell-cache+capture-timeout 33 dev/34 prod; cloudflare ppr suites 30 dev/28 prod; typecheck/lint/format/ bucketing/docs-api green.
1 parent 7446cd8 commit 4873773

26 files changed

Lines changed: 1173 additions & 86 deletions

‎packages/rangojs-router/docs/design/ppr-shell-resume.md‎

Lines changed: 76 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -55,13 +55,79 @@ path("/products/:id", PricePage, { name: "product", ppr: { ttl: 600, swr: 120 }
5555
```
5656

5757
`ppr: true` uses the default policy (`DEFAULT_PPR_TTL_SECONDS` = 300);
58-
`PartialPrerenderProps { ttl?, swr?, tags? }` sets it explicitly
59-
(`src/urls/pattern-types.ts`; stored on the route `EntryData` by
58+
`PartialPrerenderProps { ttl?, swr?, tags?, captureTimeout? }` sets it
59+
explicitly (`src/urls/pattern-types.ts`; stored on the route `EntryData` by
6060
`src/urls/path-helper.ts`; normalized by `resolvePprConfig` in
6161
`src/rsc/shell-serve.ts`). There is NO subtree inheritance in v1 — declaring
6262
`ppr` on a layout is not supported (a possible follow-up). A route without the
6363
option is pure axis 1: no store read, no capture, no logs, zero cost.
6464

65+
The route's NAME is orthogonal to all of this (issue #714): a nameless
66+
`path()` registers its `EntryData` under a synthesized `$path_*` manifest key
67+
with the `ppr` option intact, so it captures and serves exactly like a named
68+
route — pinned by the nameless-ppr e2e in both apps and the
69+
`shell-serve-ppr-config` unit round-trip. (The issue's observed "silent
70+
ignore" was the pre-#705 Accept rule: a document GET without `text/html` in
71+
Accept — curl's default `*/*` — negotiated to the Flight wire format and
72+
bypassed the shell lane for named and nameless routes alike.)
73+
74+
### `captureTimeout`: the capture settle budget (issue #715)
75+
76+
The background capture is bounded by ONE deadline — `captureShellHTML`'s
77+
`maxWaitMs` — hard-coded to 5s until #715. Deferred shell material (a handler
78+
pushing `ctx.use(Meta)(dataPromise.then(...))`, top-level handle pushes
79+
carrying promises) is AWAITED by the capture and its settled values bake into
80+
the stored shell; material that settles slower than the budget made the route
81+
uncapturable forever (eternal MISS + backoff + the no-usable-shell warning).
82+
`ppr.captureTimeout` (ms, default 5000) declares the budget per route:
83+
84+
```ts
85+
path("/pdp/:id", ProductPage, {
86+
name: "product",
87+
ppr: { ttl: 600, swr: 120, captureTimeout: 10_000 },
88+
});
89+
```
90+
91+
Semantics, in dependency order:
92+
93+
- **One knob, one deadline.** The resolved value flows
94+
`resolvePprConfig -> ShellCaptureDescriptor.captureTimeout ->
95+
captureShellHTML({ maxWaitMs })`, so it bounds BOTH the fizz prerender and
96+
the deferred-material settle window — the `holdUntil` gate and the quiesce
97+
race are inputs to the same deadline. There is no second timer to drift.
98+
- **Ordering is the contract, the budget only bounds it.** The capture gate
99+
never freezes while a tracked top-level push is pending
100+
(`gateFlightForCapture`'s `holdUntil`), and `SsrRoot` suspends at the ROOT
101+
until the handles snapshot fully settles (`resolvedHandleStream` yields
102+
once, after EVERY push — including promises chained off other pushes —
103+
resolves). A partial prefix of the settlement sequence is therefore
104+
unrepresentable in a stored shell.
105+
- **Expiry with pushes pending REFUSES.** If the budget elapses first, the
106+
handles row never emitted, the prerender is still root-suspended, the
107+
prelude has no `<body>`, and the sanity gate returns null — no-shell, the
108+
existing retry/backoff/warning path. A shell with missing or unsettled head
109+
material is never stored, at any budget.
110+
- **Cost model.** Capture is background work (`waitUntil`): a longer budget
111+
costs latency-to-HIT only, never a served response. The platform's
112+
`waitUntil` lifetime is the physical ceiling — on workerd, ~30s past
113+
response completion — so a `captureTimeout` near or past that ceiling gets
114+
killed by the platform, not by rango (see Platform notes).
115+
- **Producer B parity.** Build-time captures (Prerender+ppr,
116+
`src/prerender/build-shell-capture.ts`) and the dev `/__rsc_shell` endpoint
117+
honor the same knob (`resolveBuildPprConfig` resolves it; the dev
118+
read-through threads it as a query param and sizes its own fetch bound —
119+
`devShellFetchTimeoutMs` — to the endpoint's full sequential envelope:
120+
pre-flight probe + two attempts + retry margin). Build has no `waitUntil`
121+
bound, so there the option is the only ceiling.
122+
- **Validation.** Non-finite or sub-1ms values normalize to undefined (the
123+
capture default applies); the default's single owner stays
124+
`SHELL_CAPTURE_MAX_WAIT_MS` in `src/rsc/shell-capture.ts`.
125+
126+
Deliberately unchanged: `SHELL_CAPTURE_WRITE_BARRIER_MS` (1.5s pre-render
127+
write barrier), `SHELL_SNAPSHOT_WRITE_SETTLE_MS` (1s deferred-write settle),
128+
the retry-in-place delay, and the refused-capture backoff windows — those
129+
bound store I/O and scheduling, not shell-material settlement.
130+
65131
Serving is INTEGRAL to the router — `createShellCacheMiddleware` and
66132
`ShellCacheOptions` were removed from the public surface entirely (pre-release
67133
rule: removed, not deprecated). The shell store is the app-level
@@ -921,9 +987,14 @@ per-request data in loaders (holes); keep handles on the replay path.
921987
922988
Cloudflare Workers: the in-worker pattern is the endgame — the worker always
923989
runs (~5 ms cold starts); the win is skipping shell-render CPU and its
924-
upstream reads. `waitUntil` (via `runBackground`) covers capture. Chunked
925-
encoding and edge compression of the composite are automatic; never store
926-
compressed bytes.
990+
upstream reads. `waitUntil` (via `runBackground`) covers capture. The
991+
`waitUntil` lifetime — workerd allows roughly 30s of work past response
992+
completion — is the PHYSICAL ceiling on `ppr.captureTimeout`: a budget at or
993+
past it gets the capture killed by the platform mid-flight (nothing stored,
994+
same self-healing MISS as any refused capture; rango cannot warn because the
995+
isolate is gone). Keep per-route budgets comfortably under it; build-time
996+
captures (producer B) have no such bound. Chunked encoding and edge
997+
compression of the composite are automatic; never store compressed bytes.
927998
928999
Vercel: identical in-function pattern on Fluid Compute via the Vercel store.
9291000
The Build Output API `chain` mechanism (platform-appended streaming, shell

‎packages/rangojs-router/docs/internal/feature-file-map.md‎

Lines changed: 42 additions & 42 deletions
Large diffs are not rendered by default.

‎packages/rangojs-router/docs/internal/feature-map.md‎

Lines changed: 22 additions & 22 deletions
Large diffs are not rendered by default.
Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
import { expect, test } from "@playwright/test";
2+
import { useFixture, type Fixture } from "./fixture";
3+
4+
// PPR capture-budget + nameless-route coverage (issues #714 / #715), backed by
5+
// the fixtures in test-app/src/urls/shell-cache.tsx:
6+
//
7+
// - /shell-cache/nameless/:probe — a NAMELESS ppr route (#714). `name` is
8+
// orthogonal to shell caching: the DSL registers the entry under a
9+
// synthesized $path_* manifest key with the ppr option intact, so the route
10+
// must engage (MISS -> HIT) exactly like a named one.
11+
// - /shell-cache/slow-meta — deferred shell material settling IN PARTS
12+
// (immediate push, ~5.5s slow push, Meta title CHAINED off the slow promise
13+
// +1s ≈ 6.5s total) with `ppr.captureTimeout: 10000` (#715). The capture
14+
// awaits the COMPLETE settlement sequence (the gate holds while top-level
15+
// pushes are pending; SsrRoot suspends at the root until the final snapshot)
16+
// and bakes the resolved values into the stored prelude.
17+
// - /shell-cache/slow-meta-default — the SAME material with NO captureTimeout:
18+
// the default 5s budget expires with pushes pending and the capture REFUSES
19+
// (eternal MISS + the once-per-key no-usable-shell warning). A partial-meta
20+
// shell is never stored.
21+
//
22+
// Own file (not shell-cache.test.ts): the slow fixtures cost real wall-clock
23+
// per request (the live render also awaits the pushes), so they get their own
24+
// isolatedServer lifecycle and stay out of the main suite's timing.
25+
26+
const HTML_HEADERS = { Accept: "text/html" };
27+
28+
// Parts settle at ~5.5s (slow) and ~6.5s (chained Meta); the capture then
29+
// needs quiesce + fizz + store. A generous ceiling absorbs CI-runner noise.
30+
const HIT_POLL_TIMEOUT_MS = 45_000;
31+
// Two default-budget capture attempts (5s + 400ms retry + 5s) plus margin —
32+
// the window in which the no-knob route's capture deterministically refuses.
33+
const DEFAULT_BUDGET_REFUSAL_MS = 12_000;
34+
35+
/**
36+
* Fetch a document and split it at the frozen-prelude boundary (the stored
37+
* prelude ends at </html>; everything after is the resumed tail). Returns the
38+
* shell status header alongside so callers assert composition and status off
39+
* ONE request.
40+
*/
41+
async function fetchSplit(url: string): Promise<{
42+
status: string | undefined;
43+
prelude: string;
44+
resumed: string;
45+
html: string;
46+
}> {
47+
const res = await fetch(url, { headers: HTML_HEADERS });
48+
expect(res.status).toBe(200);
49+
const html = await res.text();
50+
const preludeEnd = html.indexOf("</html>");
51+
expect(preludeEnd).toBeGreaterThan(-1);
52+
return {
53+
status: res.headers.get("x-rango-shell") ?? undefined,
54+
prelude: html.slice(0, preludeEnd),
55+
resumed: html.slice(preludeEnd),
56+
html,
57+
};
58+
}
59+
60+
function runSpec(f: Fixture): void {
61+
test("nameless ppr route engages: MISS then HIT (issue #714)", async ({
62+
request,
63+
}) => {
64+
const url = f.url("/shell-cache/nameless/e2e?probe=nameless714");
65+
const first = await request.get(url, { headers: HTML_HEADERS });
66+
expect(first.status()).toBe(200);
67+
expect(first.headers()["x-rango-shell"]).toBe("MISS");
68+
const html = await first.text();
69+
expect(html).toContain("Live price:");
70+
71+
await expect(async () => {
72+
const res = await request.get(url, { headers: HTML_HEADERS });
73+
expect(res.status()).toBe(200);
74+
expect(res.headers()["x-rango-shell"]).toBe("HIT");
75+
}).toPass({ timeout: 15_000 });
76+
77+
// The HIT composes: frozen prelude + live resumed hole.
78+
const hit = await fetchSplit(url);
79+
expect(hit.status).toBe("HIT");
80+
expect(hit.resumed).toContain("Live price:");
81+
});
82+
83+
test("captureTimeout admits staged deferred material: MISS -> HIT with ALL parts baked in the stored prelude (issue #715)", async ({
84+
request,
85+
}) => {
86+
test.setTimeout(120_000);
87+
const url = f.url("/shell-cache/slow-meta?probe=ct715");
88+
// The live render itself awaits the pushes (~6.5s), so raise per-call
89+
// ceilings accordingly.
90+
const first = await request.get(url, {
91+
headers: HTML_HEADERS,
92+
timeout: 30_000,
93+
});
94+
expect(first.status()).toBe(200);
95+
expect(first.headers()["x-rango-shell"]).toBe("MISS");
96+
// The MISS is a plain axis-1 render whose full-render handle barrier
97+
// awaits the staged pushes, so its body already proves the parts settle
98+
// on the LIVE path independent of any capture.
99+
const firstHtml = await first.text();
100+
expect(firstHtml).toMatch(/slow-meta-immediate-\d+/);
101+
expect(firstHtml).toMatch(/slow-meta-slow-\d+-chained/);
102+
103+
await expect(async () => {
104+
const res = await request.get(url, {
105+
headers: HTML_HEADERS,
106+
timeout: 30_000,
107+
});
108+
expect(res.status()).toBe(200);
109+
expect(res.headers()["x-rango-shell"]).toBe("HIT");
110+
}).toPass({ timeout: HIT_POLL_TIMEOUT_MS, intervals: [2_000] });
111+
112+
// STORED-prelude assertion: every part of the settlement sequence — the
113+
// immediate push, the slow push, and the Meta title CHAINED off the slow
114+
// value — is baked RESOLVED into the frozen prelude, all from the SAME
115+
// capture render (one seq). A partial prefix (immediate baked, chained
116+
// missing) must be unrepresentable.
117+
const hit = await fetchSplit(url);
118+
expect(hit.status).toBe("HIT");
119+
const seqMatch = hit.prelude.match(/slow-meta-immediate-(\d+)/);
120+
expect(seqMatch).not.toBeNull();
121+
const seq = seqMatch![1];
122+
expect(hit.prelude).toContain(`slow-meta-immediate-${seq}`);
123+
expect(hit.prelude).toContain(`slow-meta-slow-${seq}`);
124+
expect(hit.prelude).toContain(`slow-meta-slow-${seq}-chained`);
125+
// The chained value is the document TITLE (head material via the Meta
126+
// handle), not just body text.
127+
expect(hit.prelude).toMatch(
128+
new RegExp(`<title[^>]*>[^<]*slow-meta-slow-${seq}-chained`),
129+
);
130+
131+
// Frozen across consecutive HITs: the prelude replays the SAME capture
132+
// seq (handlers re-run for the live tail, but the stored bytes are fixed).
133+
const second = await fetchSplit(url);
134+
expect(second.status).toBe("HIT");
135+
expect(second.prelude).toContain(`slow-meta-immediate-${seq}`);
136+
expect(second.prelude).toContain(`slow-meta-slow-${seq}-chained`);
137+
});
138+
139+
test("same material WITHOUT captureTimeout refuses: stays MISS, no partial bake, once-per-key warning (issue #715 negative)", async ({
140+
request,
141+
}) => {
142+
test.setTimeout(120_000);
143+
const url = f.url("/shell-cache/slow-meta-default?probe=ct715neg");
144+
const first = await request.get(url, {
145+
headers: HTML_HEADERS,
146+
timeout: 30_000,
147+
});
148+
expect(first.status()).toBe(200);
149+
expect(first.headers()["x-rango-shell"]).toBe("MISS");
150+
151+
// Wait past two full default-budget attempts (5s + retry + 5s), then
152+
// re-probe: still MISS — the capture refused rather than storing a shell
153+
// with unsettled meta. Two probes to also cover a backoff-window re-probe.
154+
await new Promise((r) => setTimeout(r, DEFAULT_BUDGET_REFUSAL_MS));
155+
for (let i = 0; i < 2; i++) {
156+
const res = await request.get(url, {
157+
headers: HTML_HEADERS,
158+
timeout: 30_000,
159+
});
160+
expect(res.status()).toBe(200);
161+
expect(res.headers()["x-rango-shell"]).toBe("MISS");
162+
}
163+
164+
// The once-per-key no-usable-shell warning names the refusal in the
165+
// server log (isolatedServer exposes the process streams).
166+
const logs = f.proc().stdout() + f.proc().stderr();
167+
expect(logs).toMatch(
168+
/Shell capture for "[^"]*slow-meta-default[^"]*" produced no usable shell after an in-place retry/,
169+
);
170+
});
171+
}
172+
173+
test.describe("shell-capture-timeout (dev)", () => {
174+
const f = useFixture({
175+
root: "./e2e/test-app",
176+
mode: "dev",
177+
isolatedServer: true,
178+
});
179+
runSpec(f);
180+
});
181+
182+
test.describe("shell-capture-timeout (production)", () => {
183+
const f = useFixture({
184+
root: "./e2e/test-app",
185+
mode: "build",
186+
isolatedServer: true,
187+
});
188+
runSpec(f);
189+
});
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
"use client";
2+
3+
import { useHandle } from "@rangojs/router/client";
4+
import { SlowMetaHandles } from "../urls/shell-cache.defs.js";
5+
6+
/**
7+
* Consumer for the slow deferred-shell-material fixture (issue #715). Every
8+
* push is TOP-LEVEL, so by the time the payload's handles row emits (and the
9+
* capture gate releases) all parts are resolved strings — shell material that
10+
* bakes into the stored prelude. Rendering all values in one span makes the
11+
* prelude assertion a plain substring check per part.
12+
*/
13+
export function SlowMetaView() {
14+
const parts = useHandle(SlowMetaHandles) ?? [];
15+
return (
16+
<div data-testid="slow-meta-view">
17+
{parts.map((p, i) => (
18+
<span key={i} data-testid={`slow-meta-part-${i}`}>
19+
{p}
20+
</span>
21+
))}
22+
</div>
23+
);
24+
}

‎packages/rangojs-router/e2e/test-app/src/router.named-routes.gen.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,8 @@ export const NamedRoutes = {
338338
shellCacheSlotHole: "/shell-cache/slot-hole",
339339
shellCacheSlotUse: "/shell-cache/slot-use",
340340
shellCacheSlotUseOther: "/shell-cache/slot-use/other",
341+
shellCacheSlowMeta: "/shell-cache/slow-meta",
342+
shellCacheSlowMetaDefault: "/shell-cache/slow-meta-default",
341343
shellCacheSnapshotCap: "/shell-cache/snapshot-cap",
342344
shellCacheStream: "/shell-cache/stream",
343345
shellSecure: "/shell-secure",

‎packages/rangojs-router/e2e/test-app/src/urls/shell-cache.defs.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,54 @@ export const ShellExecLoader = createLoader(
310310
},
311311
);
312312

313+
// Slow deferred-shell-material fixture (issue #715, the storefront meta
314+
// pattern): the layout pushes THREE top-level handle values that settle IN
315+
// PARTS — immediate, slow (~5.5s), and a Meta CHAINED off the slow promise
316+
// (+1s, ~6.5s total). All three are TOP-LEVEL pushes, so the capture awaits
317+
// the COMPLETE settlement sequence (resolvedHandleStream converges only after
318+
// every push resolves — a partial prefix is unrepresentable) and bakes the
319+
// final values. Under the DEFAULT 5s budget the sequence outlasts the
320+
// deadline, the handles row never emits, SsrRoot stays suspended at the root,
321+
// and the capture REFUSES (trivial prelude — eternal MISS + once-per-key
322+
// warning). With `ppr.captureTimeout: 10000` the same route captures and the
323+
// stored prelude carries all three resolved parts. A per-capture seq rides in
324+
// each value so consecutive HITs pin frozenness (the prelude keeps the
325+
// capture-time seq while axis-1/misses would advance it).
326+
const SLOW_META_SLOW_DELAY_MS = 5_500;
327+
const SLOW_META_CHAIN_EXTRA_MS = 1_000;
328+
329+
export interface SlowMetaParts {
330+
immediate: Promise<string>;
331+
slow: Promise<string>;
332+
chainedTitle: Promise<string>;
333+
}
334+
335+
let slowMetaSeq = 0;
336+
337+
export function makeSlowMetaParts(): SlowMetaParts {
338+
slowMetaSeq += 1;
339+
const seq = slowMetaSeq;
340+
const immediate = Promise.resolve(`slow-meta-immediate-${seq}`);
341+
const slow = new Promise<string>((resolve) =>
342+
setTimeout(() => resolve(`slow-meta-slow-${seq}`), SLOW_META_SLOW_DELAY_MS),
343+
);
344+
// The Meta value is CHAINED off the slow push's promise with additional
345+
// latency — the staged-resolution shape (data -> derived meta) the capture
346+
// must ride to full convergence, not to the first settle.
347+
const chainedTitle = slow.then(
348+
(v) =>
349+
new Promise<string>((resolve) =>
350+
setTimeout(() => resolve(`${v}-chained`), SLOW_META_CHAIN_EXTRA_MS),
351+
),
352+
);
353+
return { immediate, slow, chainedTitle };
354+
}
355+
356+
/** Handle collecting the slow fixture's non-Meta pushes for shell render. */
357+
export const SlowMetaHandles = createHandle<string, string[]>((values) =>
358+
values.flat(),
359+
);
360+
313361
/**
314362
* Render counter for the /shell-cache/outlined fixture. Fizz OUTLINES any
315363
* Suspense boundary over ~500 bytes (fallback written inline first, content

0 commit comments

Comments
 (0)