Skip to content

Commit bdc6af1

Browse files
committed
perf(ppr): pin-first resolution for hole-free bake-lane loaders on shell HITs
On a shell HIT a bake-lane loader re-ran and the hydration payload gated on that fresh run's full latency, then discarded its values (the snapshot pin wins wholesale). A slow layout loader added its whole duration to every HIT's stream window; a fresh-run rejection diverged the payload from the frozen prelude (hydration mismatch flash). Each pinned loader record now carries a capture-computed hole bit (ShellSnapshotLoaderValue.holes, from elide's existing walk). Hole-free records resolve the payload promise immediately from the pin; the fresh run still executes ungated (side effects and cache read-through preserved, waitUntil-extended) and its rejection is swallowed — the pin already matches the prelude. Hole-carrying and legacy (pre-bit) records keep the gated path: only the loader body can mint the live nested promises. Also adds a dev-only ppr:tail Server-Timing mirror (consume-on-read buffer, same doctrine as the ppr:capture mirror from #651): the next ppr GET's header carries the previous HIT's per-stage tail offsets (seed/match/handover/first-html/complete + byte counts). E2e: new /shell-cache/bake-slow and /ppr-shell/bake-slow fixtures (600ms hole-free bake-lane layout loader + 30ms live hole) with dev+production tests in both apps; red-proof: 616ms HIT with the branch disabled vs <400ms bound. Unit: pin-first timing/rejection (red-before-green), capture hole bit, seed mapping. Docs: loader-container-bake.md, ppr-shell-resume.md, feature-map.md, feature-file-map.md.
1 parent af35562 commit bdc6af1

25 files changed

Lines changed: 1020 additions & 80 deletions

‎packages/rangojs-router/docs/design/loader-container-bake.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -206,11 +206,42 @@ recorded family.
206206
container-with-promise-paths-elided)` into the same
207207
`ShellCacheEntry.snapshot` array (`shell-snapshot.ts`). Promise-valued paths
208208
are recorded as markers, not values — they are holes, not shell material.
209-
- **Seeding.** On a HIT the loader RUNS FRESH (it must — only the loader body
210-
can mint the nested promises), then the recorded container is OVERLAID: every
211-
recorded (non-promise) path takes the snapshot value; promise-valued paths
212-
keep the fresh run's promises. The prelude's baked bytes and the payload's
213-
container fields agree by construction; the holes stay live.
209+
- **Seeding.** On a HIT the loader RUNS FRESH, and the recorded container is
210+
OVERLAID: every recorded (non-promise) path takes the snapshot value;
211+
promise-valued paths keep the fresh run's promises. The prelude's baked
212+
bytes and the payload's container fields agree by construction; the holes
213+
stay live.
214+
- **Pin-first for hole-free records.** Each loader record carries a
215+
capture-computed hole bit (`ShellSnapshotLoaderValue.holes`, from elide's
216+
walk — no per-HIT rescan). A record WITH holes gates the overlay on the
217+
fresh run, because only the loader body can mint the live nested promises
218+
the markers re-slot. A hole-free record resolves the payload promise
219+
IMMEDIATELY from the pin: the fresh values were discarded either way
220+
(recorded paths win wholesale), so gating on them only stalled the HIT
221+
tail for the loader body's full latency. The fresh run still executes —
222+
side effects and cache read-through writes are preserved — but ungated and
223+
lifetime-extended (`waitUntil`), and its REJECTION is swallowed: the pin
224+
already matches the prelude, which an error value never could (the gated
225+
path's fresh-rejection divergence remains only for hole-carrying records).
226+
A record stored before the bit existed reads as hole-carrying and keeps the
227+
gated path; TTL ages those out.
228+
- **Pin-first drops fresh-only keys — a deliberate contract divergence.** The
229+
gated overlay passes fresh-only object keys through ("they cannot
230+
contradict prelude bytes that never rendered them"). Pin-first does NOT: a
231+
hole-free pin serves the pinned shape wholesale, so a key the fresh run
232+
starts returning mid-TTL is absent from HIT payloads until recapture. Why
233+
this is correct and not a loss: a fresh-only key on a hole-free record had
234+
no postponed hole (nothing suspended there at capture), so the prelude
235+
froze the consumer's without-that-field branch and the resume pass has
236+
nothing to fill — under the old passthrough the field could only surface
237+
as a payload/prelude hydration mismatch the client repaired (the exact
238+
divergence class the snapshot exists to prevent), never as cleanly
239+
streamed content. A field that varies per request belongs on the live
240+
surface: promise-shaped at capture (masked → hole marker → `holes: 1` →
241+
the gated path, where fresh-only passthrough still holds and live promises
242+
re-slot) or behind `loading()`. A sometimes-present plain field on a
243+
bake-lane loader is uncached nondeterminism in shell material — the
244+
documented drift residual.
214245
- **Overlay rules for shape drift** (capture says sync, hit says promise, or
215246
vice versa): a recorded path always wins (pinned — it is what the prelude
216247
froze); a path that is a promise in BOTH runs stays the fresh promise; a NEW

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1185,6 +1185,18 @@ hit/miss metric for the serve-side store read. The capture runs AFTER its
11851185
triggering response commits, which is why its outcome can only ride a later
11861186
response's header.
11871187
1188+
**HIT-tail timing mirror.** The HIT commits its 200 + headers at the prelude
1189+
flush, so Server-Timing on the HIT response structurally cannot carry the
1190+
live tail's numbers — all of match/loaders/Flight/resume happens inside the
1191+
response body. In dev, `serveShellHit` records per-stage offsets from the
1192+
commit (`seed`/`match`/`handover`/`first-html`/`complete`, plus
1193+
prelude/tail byte counts — `ShellTailTiming`, shell-serve.ts) and buffers
1194+
the terminal timing per key; when `debugPerformance` metrics are active it
1195+
rides the NEXT ppr GET's Server-Timing as `ppr-tail;dur=<complete
1196+
ms>;desc="…"` — the same consume-on-read doctrine as the `ppr-capture`
1197+
mirror above. Production folds the collection away (`NODE_ENV` literal);
1198+
`INTERNAL_RANGO_DEBUG` remains the raw console narration of the same window.
1199+
11881200
**Inert shell family.** The shell family is KV-only on `CFCacheStore`; with
11891201
no KV namespace bound, `getShell`/`putShell` no-op and every ppr route is a
11901202
permanent MISS — the correctness-first fail-open of v1, previously with zero

‎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: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ Route-local schema definitions (`search` option), typed route param types (`Rout
215215
- `"use cache"` directive runtime wrappers, response route cache layer
216216
- SWR background revalidation re-establishes the request-context ALS (so a cached body reading `getRequestContext()` resolves off the request's I/O context on workerd); profile opt-in `foregroundOnAction` re-executes a stale entry in the foreground during a server action's revalidation render (fresh action response) instead of serving stale + background-revalidating
217217
- Tag-based invalidation: `cacheTag()` (runtime) + `cache({ tags })` (static/dynamic); `updateTag()` (awaitable, read-your-own-writes) and `revalidateTag()` (background, non-blocking — both hard-purge; the only difference is awaitability) fan out to the store-level `invalidateTags()` (the whole tag batch in one call). `cacheTag()` is render-callable: outside a `"use cache"` scope but during a request render it records onto the request's document artifact (`_requestTags`) instead of throwing, so a plain server component tags the PPR shell / document it renders into — PPR's DERIVATIVE invalidation, no first-class ppr tag API (`cacheTag`/`cache-tag.ts`). Built-in stores index tags; the CF store keeps markers in its own KV (single-store, no companion tag store), and the tag-marker reads inherit the L1/L2 latency budgets and fail open. Explicit `cache({ store })` stores are registered for invalidation via a handler-owned, LRU-bounded registry. Document-cache and PPR shell entries are tagged with the request's tag union so they are tag-invalidatable too.
218-
- PPR shell caching (the `ppr` path option; `PartialPrerenderProps` exported from the root) — an opt-in second render axis, integral to the router (no middleware to mount). It caches the rendered HTML shell (React `prerender`'s prelude bytes plus the `postponed` resume state, one coupled `ShellCacheEntry`) and, on a hit, commits the composed response after the WHOLE middleware chain: prelude bytes flush first, then fizz resumes only the holes; the browser sees one ordinary streamed document. Holes are render-defined — `loading()` subtrees (structural; loaders masked at capture), pending promises in handed-over data under the consumer's Suspense (physics), everything else shell (top-level pushed handle promises are awaited pre-SSR and baked; the capture gate holds for that await, bounded by `ppr.captureTimeout` — default 15s; expiry with pushes pending refuses the capture, so a partial head snapshot is never stored). The background capture is mixed-chain (cached segments replay, uncached handlers execute — the cookies()/headers() capture guard is load-bearing) and never re-runs middleware (the derived context inherits post-middleware state). Backed by the optional `getShell`/`putShell` store family (memory/CF/Vercel), reactVersion+buildVersion-gated (isValidShellHit; a redeploy invalidates like a React upgrade, hasIntactShellPayload rejects corrupt payloads pre-commit, a failed HIT tail schedules a healing recapture) and tag-invalidatable. Shell/payload PARITY on a HIT is guaranteed by the CAPTURE DATA SNAPSHOT (`cache/shell-snapshot.ts`, internal): a pre-render write barrier settles the foreground's deferred cache writes so the capture replays the foreground's cache generation (never clobbers it); the capture render records its cache-store read-hits + writes (`RecordingShellStore`, excluding the shell family; `captureAndStoreShell` fires the capture's isolated `onResponse` so the ring-3 segment write runs and is recorded), stores them on `ShellCacheEntry.snapshot` (carried through the CF/Vercel envelopes), and `serveShellHit`'s tail render replays them AS FRESH (`SeededShellStore`) so a shell-baked cached value that DRIFTED (shorter-ttl `cache()`, tag-invalidated item) still matches the frozen prelude — parity beats freshness inside the shell; freshness comes from holes, the shell ttl/swr, and `ppr.tags`. Actions, progressive enhancement, per-request nonce, and `streamMode: "allReady"` (the SEO/bot story) always take axis 1. On a HIT the tail's hydration payload is FRAGMENT-SPLICED (#700): replayed segments carry their STORED per-segment Flight strings verbatim (`__rangoFragment` envelopes, `src/segment-fragments.ts`) instead of being deserialized and re-serialized per request; the SSR resume pass and browser hydration expand them through their own Flight deserializers, so the browser still can't tell. Operability (issue #651): `PartialPrerenderProps.maxSnapshotBytes` (default 8 MiB) skips an over-cap snapshot (shell still stored; once-per-key report; documented drift on later HITs); the `debugShellCapture` router option (`ShellCaptureDebug`/`ShellCaptureDebugEvent`, exported) emits one structured event per capture attempt/skip — outcome, barrier/write-settle waits, prelude/snapshot bytes, backoff state — and in dev the terminal event mirrors into the NEXT ppr GET's Server-Timing (`ppr-capture;desc="…"`, plus a `ppr:shell-read` metric); a KV-less `CFCacheStore` warns once per isolate that its shell family is inert. See [PPR shell caching design](../design/ppr-shell-resume.md).
218+
- PPR shell caching (the `ppr` path option; `PartialPrerenderProps` exported from the root) — an opt-in second render axis, integral to the router (no middleware to mount). It caches the rendered HTML shell (React `prerender`'s prelude bytes plus the `postponed` resume state, one coupled `ShellCacheEntry`) and, on a hit, commits the composed response after the WHOLE middleware chain: prelude bytes flush first, then fizz resumes only the holes; the browser sees one ordinary streamed document. Holes are render-defined — `loading()` subtrees (structural; loaders masked at capture), pending promises in handed-over data under the consumer's Suspense (physics), everything else shell (top-level pushed handle promises are awaited pre-SSR and baked; the capture gate holds for that await, bounded by `ppr.captureTimeout` — default 15s; expiry with pushes pending refuses the capture, so a partial head snapshot is never stored). The background capture is mixed-chain (cached segments replay, uncached handlers execute — the cookies()/headers() capture guard is load-bearing) and never re-runs middleware (the derived context inherits post-middleware state). Backed by the optional `getShell`/`putShell` store family (memory/CF/Vercel), reactVersion+buildVersion-gated (isValidShellHit; a redeploy invalidates like a React upgrade, hasIntactShellPayload rejects corrupt payloads pre-commit, a failed HIT tail schedules a healing recapture) and tag-invalidatable. Shell/payload PARITY on a HIT is guaranteed by the CAPTURE DATA SNAPSHOT (`cache/shell-snapshot.ts`, internal): a pre-render write barrier settles the foreground's deferred cache writes so the capture replays the foreground's cache generation (never clobbers it); the capture render records its cache-store read-hits + writes (`RecordingShellStore`, excluding the shell family; `captureAndStoreShell` fires the capture's isolated `onResponse` so the ring-3 segment write runs and is recorded), stores them on `ShellCacheEntry.snapshot` (carried through the CF/Vercel envelopes), and `serveShellHit`'s tail render replays them AS FRESH (`SeededShellStore`) so a shell-baked cached value that DRIFTED (shorter-ttl `cache()`, tag-invalidated item) still matches the frozen prelude — parity beats freshness inside the shell; a HOLE-FREE bake-lane loader record (capture-computed `holes` bit) resolves pin-first, so the HIT tail never waits out a slow loader body whose values the overlay discards anyway (the fresh run still executes ungated for side effects); freshness comes from holes, the shell ttl/swr, and `ppr.tags`. Actions, progressive enhancement, per-request nonce, and `streamMode: "allReady"` (the SEO/bot story) always take axis 1. On a HIT the tail's hydration payload is FRAGMENT-SPLICED (#700): replayed segments carry their STORED per-segment Flight strings verbatim (`__rangoFragment` envelopes, `src/segment-fragments.ts`) instead of being deserialized and re-serialized per request; the SSR resume pass and browser hydration expand them through their own Flight deserializers, so the browser still can't tell. Operability (issue #651): `PartialPrerenderProps.maxSnapshotBytes` (default 8 MiB) skips an over-cap snapshot (shell still stored; once-per-key report; documented drift on later HITs); the `debugShellCapture` router option (`ShellCaptureDebug`/`ShellCaptureDebugEvent`, exported) emits one structured event per capture attempt/skip — outcome, barrier/write-settle waits, prelude/snapshot bytes, backoff state — and in dev the terminal event mirrors into the NEXT ppr GET's Server-Timing (`ppr-capture;desc="…"`, plus a `ppr:shell-read` metric and a `ppr:tail` mirror of the previous HIT's per-stage tail timing — seed/match/handover/first-html/complete offsets from the commit); a KV-less `CFCacheStore` warns once per isolate that its shell family is inert. See [PPR shell caching design](../design/ppr-shell-resume.md).
219219
- Cached-scope header doctrine (#713): ppr is a document-scoped `cache()` — in any cached scenario only MIDDLEWARE writes response headers. One unified guard (`assertCachedHeaderWriteAllowed`, `server/context.ts`) refuses handler header/cookie/status/theme writes inside a `cache()` boundary AND on any render of a `ppr` route (latched at the segment funnels: positional for `cache()`, whole-funnel for ppr — leaf-entry check, same `isPprEntry` + input as the serve path's `resolvePprConfig`; the intercept funnels carry a defense-in-depth latch off the target route), plus loader writes on ppr routes (headers flush with the shell before loaders settle). Enforced at ONE choke point: a guarded Headers proxy shadowed onto the request context's stub `Response`, so `ctx.header`/`setCookie`/`deleteCookie`/`setTheme`, the handler `ctx.headers` proxy, and raw `ctx.res.headers` mutations all hit the guard at the mutation itself (`setStatus`/`onResponse` stay enumerated; internal serve writers are exempt via the raw Headers). Deterministic first-render throw, dev and prod, one message family naming route + layer + the fix ("set response headers in route middleware"). Deliberate asymmetry: DSL (registered) loader writes inside plain `cache()` stay allowed (they re-run and merge per request — pinned by the `/loader-cookie-allowed` cache-scope-guard e2e + vite-rsc-demo shop cart); a handler-invoked loader body (`ctx.use` from a handler, never registered with `loader()`) throws under `cache()` because it is skipped with its handler on a HIT and its write would land only on the MISS (#725; discriminator `isInsideLoaderScope()` vs `isInsideAnyLoaderScope()`; pinned by the `/handler-loader-cookie-blocked` e2e). Middleware headers/cookies merge into every response including shell HITs (`createResponseWithMergedHeaders`/`applyStubHeaders`, `rsc/helpers.ts`). See the header doctrine section in [PPR shell caching design](../design/ppr-shell-resume.md).
220220
- Build-time PPR shells (producer B, #699): a `Prerender` route that also declares `ppr` gets its complete `ShellCacheEntry` produced at `vite build` and served from the FIRST request after deploy (`x-rango-shell: HIT`, zero runtime capture) — one entry format, two producers, one consumer. The build's shell prerender phase (buildApp post; the prelude embeds the BUILT client bootstrap URL) reuses the discovery temp server, replays middleware with `ctx.build === true` (`ctx.dynamic()` skips that URL), and runs producer A's capture core over the just-collected prerender payloads; entries stage as `__ps-*.js` assets + a lazy `__shell-manifest.js` (pathname-only keys) read through on a shell-store MISS. `ppr.ttl` is staleness-only (recapture = the SWR upgrade path); the buildVersion gate retires entries per deploy; `updateTag` evicts by tag-marker comparison (`isTagsInvalidatedSince`, new optional store method on all three stores) against the entry's build-time `createdAt` — no tombstones. Dev parity: the read-through fetches the `/__rsc_shell` dev endpoint (on-demand capture, memoized per HMR generation) for trie `pr`-flagged routes. See prerender-api-design.md (Build-time PPR shells).
221221

‎packages/rangojs-router/e2e/shell-cache.test.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -738,6 +738,54 @@ function runShellCacheSpec(f: Fixture): void {
738738
expect(seqOf(second.html)).toBeGreaterThan(seqOf(html)!);
739739
});
740740

741+
// /shell-cache/bake-slow: the PIN-FIRST optimization (loader-cache.ts
742+
// `if (!recorded.holes)`). The layout registers a 600ms bake-lane loader
743+
// (no loading() on the layout) returning a plain HOLE-FREE container. Its
744+
// container bakes into the snapshot's loader family hole-free, so on a HIT the
745+
// payload resolves the loaderData from the PIN immediately instead of gating
746+
// on the fresh 600ms run (which still executes ungated for side effects). The
747+
// child keeps a fast ~30ms price hole behind loading() so a real shell
748+
// captures. Two guarantees in one: the served label is pinned (frozen across
749+
// HITs, not the advancing fresh seq) AND the pin makes the full HIT response
750+
// beat the 600ms fresh run.
751+
test("pin-first bake lane: a HIT serves the pinned 600ms container fast and frozen across HITs", async ({
752+
request,
753+
}) => {
754+
const url = f.url("/shell-cache/bake-slow?probe=bakeslow");
755+
await warmToHit(request, url);
756+
757+
// request.get buffers the WHOLE body, so elapsed covers stream completion.
758+
// Without pin-first the payload gates on the fresh 600ms bake run
759+
// (elapsed >= 600ms); pinned, the recorded container resolves immediately
760+
// and only the ~30ms live hole remains — the 400ms bound leaves a 200ms+
761+
// margin for CI noise either side.
762+
const start = Date.now();
763+
const res = await request.get(url, { headers: HTML_HEADERS });
764+
const elapsed = Date.now() - start;
765+
expect(res.status()).toBe(200);
766+
expect(res.headers()["x-rango-shell"]).toBe("HIT");
767+
const html = await res.text();
768+
769+
// The pinned bake label rides the HIT body beside the live hole's content.
770+
const captured = /bake-\d+/.exec(html)?.[0];
771+
expect(captured, "the pinned bake label rides the HIT body").toBeTruthy();
772+
expect(html).toContain("Live price:");
773+
774+
expect(
775+
elapsed,
776+
`HIT full-response ${elapsed}ms must beat the 600ms fresh bake run`,
777+
).toBeLessThan(400);
778+
779+
// Frozen: a second HIT serves the SAME captured label (the pin, not the
780+
// fresh seq that keeps advancing in the background) while the price hole
781+
// stays live.
782+
const second = await request.get(url, { headers: HTML_HEADERS });
783+
expect(second.headers()["x-rango-shell"]).toBe("HIT");
784+
const secondHtml = await second.text();
785+
expect(/bake-\d+/.exec(secondHtml)?.[0]).toBe(captured);
786+
expect(secondHtml).toContain("Live price:");
787+
});
788+
741789
// /shell-cache/guard: the identity wall. A bake-lane loader (no loading())
742790
// reads cookies() — during capture the guard throws inside the loader, the
743791
// context flag makes the capture REFUSE deterministically, and the route

0 commit comments

Comments
 (0)