Skip to content

Commit a1cae54

Browse files
authored
fix(ppr): shell serve-gate hardening — buildVersion gate, payload integrity check, tail-failure recapture (#684 SSR-03/04) (#687)
* fix(ppr): shell serve-gate hardening — buildVersion validity gate, pre-commit payload integrity check, tail-failure recapture (#684 SSR-03/SSR-04) A persistent shell store (KV/runtime-cache) survives deploys, but isValidShellHit gated only on reactVersion — an app redeploy with the same React left a stale build's prelude+postponed live under the same key, and resuming it against the new build's Flight tree-mismatches AFTER the 200 + full static prelude flushed: a visually complete page that never hydrates, re-served on every request until TTL (no eviction path, no recapture on failure). Corrupt stored payloads hit the same post-commit failure mode. Three coordinated guards, all degrading to a working axis-1 MISS whose background recapture overwrites the bad entry (self-healing): - ShellCacheEntry.buildVersion, stamped at capture from the new required ShellCaptureDescriptor.buildVersion (= HandlerContext.version, the @rangojs/router:version build stamp); isValidShellHit(entry, buildVersion) now gates on reactVersion AND buildVersion; pre-field entries miss. Carried through the CF (bv) and Vercel (bv) shell envelopes — dropping it in either direction would make every persisted HIT an infinite MISS. - hasIntactShellPayload: pre-commit base64/JSON integrity check; a corrupt entry reports via reportCacheError and serves MISS instead of a dead page. - serveShellHit's stream catch schedules a healing recapture: a parseable-but-mismatched postponed blob or hard render error above the holes throws post-commit; without this the same entry re-fails every request until it ages out. Red-before-green: 8 tests fail on main (5 serve-gate + 1 capture stamp + 2 KV envelope round-trips), all green with the fix. Dev + production e2e via the new /shell-cache/__corrupt fault injector in test-app. * ci: trigger full run post-ready
1 parent 518a9e7 commit a1cae54

19 files changed

Lines changed: 578 additions & 109 deletions

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

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -548,6 +548,7 @@ export interface ShellCacheEntry {
548548
prelude: string; // base64-encoded prelude bytes
549549
postponed: string | null; // JSON.stringify of React postponed state
550550
reactVersion: string; // React.version at capture time
551+
buildVersion?: string; // build stamp at capture time (second validity gate)
551552
createdAt: number; // epoch ms
552553
}
553554

@@ -572,7 +573,12 @@ once-per-key warning, since the declared intent cannot be honored).
572573
commit point: `resolvePprConfig` (normalizes the route's `ppr` option;
573574
`DEFAULT_PPR_TTL_SECONDS` = 300), `buildShellKey`
574575
(`${host}${pathname}${sortedSearch}:shell` — host-scoped so multi-tenant shells
575-
never collide), `isValidShellHit` (reactVersion gate), `hasShellFamily`, the
576+
never collide), `isValidShellHit` (reactVersion + buildVersion gates — the
577+
postponed blob encodes hole positions against one exact tree, so neither a
578+
React upgrade nor an app redeploy may resume a stored blob),
579+
`hasIntactShellPayload` (pre-commit integrity check: an undecodable prelude or
580+
unparseable postponed degrades to a MISS instead of throwing after the 200 +
581+
prelude committed), `hasShellFamily`, the
576582
once-per-key missing-store-family warning, and `warnPprNonceActiveOnce` (the
577583
once-per-key active-per-request-nonce warning; see the nonce-gate scar tissue
578584
above). The route's ppr config is read
@@ -899,16 +905,17 @@ per-request data in loaders (holes); keep handles on the replay path.
899905
900906
## Constraints (the contract with consumers)
901907
902-
| Case | Behavior |
903-
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
904-
| Shell content | shared per host+URL key — personalization must live in loaders/holes (the shell-manifest pattern). ENFORCED: `cookies()`/`headers()` reads throw during a capture render (`assertNotInsideShellCapture`, cookie-store.ts), making cookie-reading shells PPR-ineligible by construction |
905-
| Multi-tenant / host-router | the default key incorporates `url.host` so one tenant's shell can never compose into another tenant's page on a shared worker + store; custom `keyGenerator`s own host scoping themselves |
906-
| Status/headers/cookies | committed with the live response's headers before the first shell byte; a failing hole cannot become a 500/redirect — error UI renders inline via Suspense/error boundaries |
907-
| Actions / PE / formState | always axis 1 |
908-
| Per-request nonce | always axis 1 |
909-
| React/router upgrade | shells invalidated via `reactVersion` check (treated as a miss on mismatch; recapture overwrites and TTL ages the entry out — v1 has no `deleteShell`) |
910-
| Dev server | works; shells are memory-store-scoped and cheap to recapture; HMR edits produce stale shells until TTL/recapture — documented, acceptable |
911-
| Composite response | per-request; only the shell entry is cacheable. Note ordering with the document cache: if the document-cache middleware wraps a ppr route, it may cache the composite — correct output, but it makes shell caching redundant for that route. Pick one per route. |
908+
| Case | Behavior |
909+
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
910+
| Shell content | shared per host+URL key — personalization must live in loaders/holes (the shell-manifest pattern). ENFORCED: `cookies()`/`headers()` reads throw during a capture render (`assertNotInsideShellCapture`, cookie-store.ts), making cookie-reading shells PPR-ineligible by construction |
911+
| Multi-tenant / host-router | the default key incorporates `url.host` so one tenant's shell can never compose into another tenant's page on a shared worker + store; custom `keyGenerator`s own host scoping themselves |
912+
| Status/headers/cookies | committed with the live response's headers before the first shell byte; a failing hole cannot become a 500/redirect — error UI renders inline via Suspense/error boundaries |
913+
| Actions / PE / formState | always axis 1 |
914+
| Per-request nonce | always axis 1 |
915+
| React/router upgrade | shells invalidated via `reactVersion` check (treated as a miss on mismatch; recapture overwrites and TTL ages the entry out — v1 has no `deleteShell`) |
916+
| App redeploy (same React) | shells invalidated via the `buildVersion` check — a persistent shared store (KV/runtime-cache) survives deploys, and resuming an old build's postponed blob against the new build's tree would tree-mismatch AFTER the 200 + prelude committed. Pre-field entries miss the same way. Corrupt entries fail `hasIntactShellPayload` pre-commit and degrade identically; a tail failure on a served HIT schedules a healing recapture |
917+
| Dev server | works; shells are memory-store-scoped and cheap to recapture; HMR edits produce stale shells until TTL/recapture — documented, acceptable |
918+
| Composite response | per-request; only the shell entry is cacheable. Note ordering with the document cache: if the document-cache middleware wraps a ppr route, it may cache the composite — correct output, but it makes shell caching redundant for that route. Pick one per route. |
912919
913920
## Platform notes
914921

0 commit comments

Comments
 (0)