You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f63db7c
Browse filesBrowse the repository at this point in the historyBrowse files
feat(ppr): producer B — emit the shell entry at build time for prerendered routes (#699) (#701)
A Prerender route that also declares the ppr path option now gets its complete ShellCacheEntry (HTML prelude + postponed state + tag union) produced at vite build and served from the very first request after deploy — x-rango-shell: HIT with zero runtime capture. One entry format, two producers, one consumer: the build's shell prerender phase (buildApp post) reuses the discovery temp server and runs producer A's capture core (deriveShellCaptureContext + captureAndStoreShell) over the just-collected prerender payloads; entries stage as __ps-*.js assets behind a lazy __shell-manifest.js read through on a shell-store MISS. ppr.ttl is staleness-only (runtime recapture is the SWR upgrade path), the buildVersion gate retires entries per deploy, and updateTag evicts the immutable baked entries via tag-marker comparison (new optional store method isTagsInvalidatedSince on memory/CF/Vercel — no tombstones). Dev parity via the /__rsc_shell on-demand endpoint (memoized per HMR generation). Also fixes handlerLiveHoles being dropped by the KV/Vercel shell envelopes (pre-existing #695 bug, red-before-green). Closes#699.
- 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
213
213
- 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.
214
214
- PPR shell caching (the `ppr` path option; `PartialPrerenderProps` exported from the root) — an opt-in second render axis, integral to the router (no middleware). 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). 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. See [PPR shell caching design](../design/ppr-shell-resume.md).
215
+
- 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 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).
| deploy (new build) | retired: buildVersion gate + a fresh manifest replace it |
368
+
|`ppr.ttl` elapses | STALENESS only: still serves, but a runtime recapture is scheduled — SWR is the upgrade path from baked entry to fresher runtime entry, never the bootstrap path |
369
+
|`updateTag()` on its tag | evicted WITHOUT tombstones: the manifest is immutable, so `isTagsInvalidatedSince(tags, entry.createdAt)` (new optional store method) compares the store's tag markers |
370
+
| store lacks the method | TAGGED baked entries are not served (warned once — updateTag could never evict them); untagged entries are unaffected |
371
+
372
+
`isTagsInvalidatedSince` implementations: CFCacheStore wraps its existing KV
373
+
tag-marker check; MemorySegmentCacheStore records per-tag invalidation
374
+
instants; VercelCacheStore writes its own `tm`-family markers on
375
+
`invalidateTags` (the platform's `expireTag` deletes entries and keeps no
376
+
queryable history).
377
+
378
+
### Dev mode
379
+
380
+
No build manifest exists in dev, so producer B runs ON DEMAND: the
381
+
read-through's dev branch fetches `/__rsc_shell` (a dev-server endpoint
382
+
mirroring `/__rsc_prerender`), which runs the same capture core in the dev
383
+
realms — main-server environments on the Node preset, the shared temp Node
384
+
server on Cloudflare (whose `virtual:entry-ssr` now resolves to the REAL
385
+
rango SSR entry, lazily) — memoized per router HMR generation and per caller
386
+
version. The endpoint is policy-free: the serve gate sends the resolved
387
+
`ttl`/`swr`/`tags`/version. Only trie `pr`-flagged routes arm the dev branch
388
+
(production's exact candidate set), and a `/__rsc_prerender` pre-flight
389
+
refuses non-prerenderable routes so a live-handler render can never be served
390
+
as a baked shell. First dev request: `x-rango-shell: HIT`, same as production.
391
+
392
+
---
393
+
309
394
## Handler Eviction
310
395
311
396
In production builds, `Prerender` exports are replaced with stubs:
@@ -516,3 +601,5 @@ At runtime, the cache-lookup middleware uses these flags:
516
601
|`src/cache/cache-scope.ts`| RSC serialize/deserialize for segments |
517
602
|`src/vite/router-discovery.ts` (`closeBundle`) + `src/vite/discovery/prerender-collection.ts` (`expandPrerenderRoutes`) + `src/vite/discovery/bundle-postprocess.ts`| Collects prerender data, stages assets, writes manifest + injects `__loadPrerenderManifestModule` (`src/vite/index.ts` is only the public-API barrel) |
0 commit comments