@rangojs/router 0.16.0 → 0.18.0

package/src/cache/types.ts

@@ -112,7 +112,11 @@ export interface SegmentCacheStore<TEnv = unknown> {
   get(key: string): Promise<CacheGetResult | null | CacheReadError>;
 
   /**
-   * Store entry data with TTL
+   * Store entry data with TTL. Resolve once a later `get(key)` from the same
+   * location observes the entry: the route cache() write runs in a background
+   * task, and a PPR shell capture awaits that task before it reads the entry
+   * back (#957). A store that resolves earlier makes the capture re-render
+   * the page instead of replaying the entry.
    * @param key - Cache key
    * @param data - Serialized entry data
    * @param ttl - Time-to-live in seconds
@@ -183,8 +187,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * upgrade — the reactVersion field on the entry gates that at read time).
    * @param key - Cache key
    * @param entry - The shell prelude/postponed/version/createdAt bundle
-   * @param ttlSeconds - Time-to-live in seconds
-   * @param swrSeconds - Optional stale-while-revalidate window in seconds
+   * @param ttlSeconds - Time-to-live in seconds: the route's `ppr.ttl`
+   *   (undefined: the store's default), capped to the route cache() entry
+   *   the capture replayed or wrote. A capped window arrives in whole
+   *   seconds, rounded up, with ttl + swr at least 1; its ttl can be 0 (a
+   *   shell stale from the start, captured from a record inside its swr
+   *   window).
+   * @param swrSeconds - Optional stale-while-revalidate window in seconds,
+   *   under the same cap
    * @param tags - Optional cache tags for invalidation (participates in
    *   invalidateTags via the same tag machinery as the item family)
    * @returns `invalidated` when a generation marker rejected the write,
@@ -203,6 +213,47 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<"stored" | "invalidated" | "uncacheable" | void>;
 
+  /**
+   * @internal The document serve path's shell read, for built-in stores. The
+   * serve path prefers it over getShell: it resolves with the entry and the
+   * raw (decoded) prelude, the snapshot on its own promise, and the read's
+   * `debugPerformance` stats. CFCacheStore's layout keeps the snapshot behind
+   * the prelude, so its HIT can commit before the snapshot is read;
+   * VercelCacheStore reads the whole entry and decodes the prelude once per
+   * memoized shell (issue #941, docs/design/shell-entry-layout.md). Not part
+   * of the custom-store contract.
+   */
+  readShellDocument?(
+    key: string,
+    options?: ShellDocumentReadOptions,
+  ): Promise<ShellDocumentRead | null>;
+
+  /**
+   * @internal How long (ms) this store's isolate memos (shell, tag markers)
+   * can serve a read that predates a tag invalidation made elsewhere. After
+   * updateTag()/revalidateTag(), the response's fresh-reads cookie lasts the
+   * longest of these, and the same user's requests skip the memos meanwhile.
+   * Absent or 0: nothing to cover.
+   */
+  readonly freshReadsWindowMs?: number;
+
+  /**
+   * @internal Drop this isolate's memoized copy of a shell (shell-memo.ts) so
+   * the next read goes to the store. A HIT whose doc record failed to decode
+   * calls it after replacing the entry with a tombstone: the memoized copy
+   * holds the same record. Built-in stores only; not part of the custom-store
+   * contract.
+   */
+  dropShellMemo?(key: string): void;
+
+  /**
+   * @internal The largest shell entry (prelude, postponed state, and snapshot
+   * bytes) this store can hold in one value. The capture refuses a bigger
+   * entry instead of letting the write fail inside waitUntil. Absent: the
+   * capture applies DEFAULT_SHELL_ENTRY_MAX_BYTES (Cloudflare KV's 25 MiB).
+   */
+  readonly maxShellEntryBytes?: number;
+
   /**
    * Declares the shell family present-but-inert: getShell/putShell exist but
    * no-op (a custom store whose backing tier is conditionally unavailable).
@@ -252,6 +303,20 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * APIs delegate to. Receives ALL of one invalidation call's tags at once so
    * stores can batch their work (e.g. a single CDN purge request rather than
    * one per tag). Stores that do not support tags simply omit this method.
+   *
+   * Both verbs call it synchronously, inside the request that invalidates
+   * (#973); revalidateTag() then hands the returned promise to waitUntil
+   * without awaiting it. Read-your-own-writes for that request comes from
+   * what the store does before its first await: record the tags as
+   * invalidated in state its reads consult for the rest of the request (the
+   * built-in stores key a map by the request's root context and the store,
+   * so contexts derived from the request share it, and compare each hit's
+   * tags and write time against it), then start the
+   * durable write. Such a mask must only ever turn hits into misses, and only
+   * in that request: a durable write that later fails then costs extra
+   * misses, never a stale read. A store that records nothing before its
+   * first await still works; the request that ran revalidateTag() can read
+   * entries the invalidation covers until the durable write lands.
    * @param tags - The cache tags to invalidate
    */
   invalidateTags?(tags: string[]): Promise<void>;
@@ -340,12 +405,13 @@ export interface ShellCacheEntry {
    */
   buildVersion?: string;
   /**
-   * The initialTheme the CAPTURE render was built with (the derived context's
-   * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
+   * The initialTheme the CAPTURE render was built with: the no-cookie default
+   * (payloadInitialTheme, rsc/full-payload.ts), never the capturing visitor's
+   * theme (#971). The resume tail must render ThemeProvider with the SAME
    * initialTheme the frozen prelude was rendered with: React resume requires the
    * tree above the holes to match the prerendered tree, and initialTheme is
    * per-request METADATA, not part of the cached segments — a visitor whose
-   * theme differs from the capturer's would otherwise produce a divergent resume
+   * theme differs from the capture's would otherwise produce a divergent resume
    * tree (broken stitching/hydration). The visitor's real theme is applied
    * pre-paint by the FOUC script and re-synced from the cookie post-mount by
    * ThemeProvider.
@@ -366,17 +432,21 @@ export interface ShellCacheEntry {
    */
   snapshot?: ShellSnapshotRecord[];
   /**
-   * The key of the CANONICAL document segment record inside `snapshot` — the
-   * one navigation replay can actually consume (resolved under the implicit
-   * doc namespace at capture; see CacheScope.cacheRoute). Replay eligibility
-   * requires this exact record: the snapshot also carries incidentally
-   * recorded explicit-tier records (RecordingShellStore passthroughs) whose
-   * keys a partial lookup can never resolve, and counting those declared
-   * entries "replayable" that always missed (`snapshot-miss` flip-flop).
-   * Absent on entries captured before the field existed OR when the capture
-   * recorded no doc record (cache(false)/condition-false routes, prerender
-   * short-circuit) — both read as `no-segment-snapshot`; recapture heals the
-   * former.
+   * Records the capture dropped from `snapshot` because no reader of this
+   * entry consumes them, by family (`item:4/response:1`). Diagnostic only: the
+   * HIT tail timing reports it next to the kept records. See
+   * docs/design/shell-entry-layout.md ("Record only what a HIT reads").
+   */
+  prunedRecords?: string;
+  /**
+   * The key of the document segment record inside `snapshot`: the handler
+   * layer every HIT replays (a document HIT tail looks the record up by this
+   * key, so a store keyGenerator or a build-time capture host cannot send it
+   * elsewhere) and the record navigation replay consumes (resolved under the
+   * implicit doc namespace at capture; see CacheScope.cacheRoute). A capture
+   * that ran handlers always stores it; only a prerender-served entry (the
+   * prerender store supplies the handler layer) has none. A document entry
+   * without it is served as a MISS.
    */
   docKey?: string;
   /**
@@ -385,26 +455,6 @@ export interface ShellCacheEntry {
    * the partial request's headers and middleware state are not document state.
    */
   navigationOnly?: true;
-  /**
-   * True when the capture's HANDLER layer declared per-request liveness: a
-   * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
-   * capture mask turns it into a never-filling hole), such a push was still
-   * pending when the entry was written, or a handler-invoked loader
-   * (ctx.use(loader) from a handler body — the consumption lane, #672)
-   * executed during the capture. The serve tail then must NOT take the
-   * handler-free fast path (the implicit doc-cache hit): only a handler
-   * re-run can mint that hole's live promise or refresh that consumed value.
-   * DSL-loader pushes never set this — loaders re-run fresh on every HIT, so
-   * their holes always fill.
-   */
-  handlerLiveHoles?: boolean;
-  /**
-   * Legacy/fallback marker for a transition({ when }) predicate that was not
-   * evaluated by the PPR pre-handler gate. Such an entry stays conservatively
-   * ineligible for handler-free replay. New PPR matches evaluate known segment
-   * predicates before the pipeline and do not set this marker.
-   */
-  transitionWhen?: true;
   /** Capture-generation start time; tag invalidations at or after it win. */
   createdAt: number;
 }
@@ -421,12 +471,119 @@ export type DocumentShellCacheEntry = ShellCacheEntry & {
   postponed: string | null;
 };
 
+/** @internal Options of {@link SegmentCacheStore.readShellDocument}. */
+export interface ShellDocumentReadOptions {
+  /**
+   * Tag names the route declares for its shell (`ppr.tags`), known before the
+   * entry is read: their marker reads can start alongside the entry read.
+   */
+  tagHints?: readonly string[];
+}
+
+/**
+ * @internal Why a prelude-first read's snapshot is missing although the entry
+ * stored one: `unavailable` (the read timed out or failed; the entry may be
+ * sound) or `corrupt` (the bytes arrived and do not parse; the store evicted
+ * the entry).
+ */
+export type ShellSnapshotFailure = "unavailable" | "corrupt";
+
+/**
+ * @internal Result of {@link SegmentCacheStore.readShellDocument}.
+ */
+export interface ShellDocumentRead {
+  /** The entry without its prelude and snapshot (delivered separately). */
+  entry: ShellCacheEntry;
+  /** Raw prelude bytes (empty for a navigationOnly entry). */
+  prelude: Uint8Array;
+  shouldRevalidate?: boolean;
+  /**
+   * The capture snapshot, read after the prelude. Resolves undefined when the
+   * entry has none or it could not be read (`snapshotFailure` says which); a
+   * document HIT then cannot replay its doc record and degrades
+   * (rsc-rendering.ts serveShellHit).
+   * Never rejects.
+   */
+  snapshot: Promise<ShellSnapshotRecord[] | undefined>;
+  /**
+   * Why `snapshot` resolved undefined although the entry stored one, or
+   * undefined when it did not fail. A document HIT that cannot replay its
+   * doc record replaces the entry only when it is broken, not when its read
+   * was merely slow (rsc-rendering.ts serveShellHit). Never rejects.
+   */
+  snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
+  /**
+   * Where the read's time and bytes went, for the `debugPerformance` metrics
+   * (rsc-rendering.ts) and the store's own debug trace. Present only when one
+   * of them is on for the request.
+   */
+  stats?: ShellReadStats;
+}
+
+/**
+ * @internal Sub-steps of a prelude-first shell read. Times are ms. workerd
+ * advances its clock only on I/O, so a CPU-only field
+ * (`snapshot.parseMs`) reads 0 on a deployed worker: the byte counts are the
+ * cost signal there.
+ */
+export interface ShellReadStats {
+  /**
+   * The tier that answered: `memo` (the store's shell memo), `l1`/`kv`
+   * (CFCacheStore), or `store` (a single-tier store, VercelCacheStore).
+   */
+  tier: "memo" | "l1" | "kv" | "store";
+  /** The per-isolate memo's outcome for this read and its size after it. */
+  memo?: { hit: boolean; bytes: number };
+  /**
+   * A KV read after an L1 attempt: how long the L1 attempt took and why it
+   * missed. The KV fields below then restart from the KV read.
+   */
+  l1MissMs?: number;
+  l1MissReason?: string;
+  /** Cache API match (L1) or KV get (KV) until the body was available. */
+  matchMs?: number;
+  /** Frame head read (I/O) and parse. */
+  headMs?: number;
+  /** Prelude bytes read. */
+  preludeMs?: number;
+  /** Tag-marker read, start to resolve (runs alongside the prelude read). */
+  markerMs?: number;
+  /** How long the read waited for the marker after the prelude was read. */
+  markerWaitMs?: number;
+  /**
+   * The marker check was awaited after the entry read (VercelCacheStore), not
+   * alongside the prelude read; hinted reads still start with the entry read.
+   */
+  markerSerial?: true;
+  /**
+   * How the isolate marker memo answered the shell's tags (the most
+   * store-bound outcome across them): `fresh`, `stale` (served, refreshing in
+   * the background), `read` (from the store), `bypass` (fresh-reads cookie).
+   */
+  markerMemo?: "fresh" | "stale" | "read" | "bypass";
+  /** Tags whose marker reads were started before the entry's head (hints). */
+  markerHinted?: readonly string[];
+  /** When the hinted marker reads started (performance.now()). */
+  markerHintStartedAt?: number;
+  /** How many of the shell's tags were hinted. */
+  markerHintHits?: number;
+  /** How long the hinted marker reads ran before the entry named its tags. */
+  markerLeadMs?: number;
+  /** The request carried the fresh-reads cookie: no isolate memo was used. */
+  freshReads?: true;
+  headBytes?: number;
+  preludeBytes?: number;
+  /** Number of the shell's tags the marker read covered. */
+  tags?: number;
+  /** Filled after the commit, once the snapshot has been read. */
+  snapshot?: { readMs: number; parseMs: number; bytes: number };
+}
+
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family
- * pins the settled CONTAINER of a bake-lane loader (a loader on an entry with
- * no renderable loading(), executed during capture — see
- * docs/design/loader-container-bake.md). Excludes the shell family itself
+ * pins the settled CONTAINER of a bake-lane loader (lane rule: see
+ * resolveLoaderData, loader-cache.ts). Excludes the shell family itself
  * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
  * it would be self-referential.
  */
@@ -447,12 +604,20 @@ export interface ShellSnapshotLoaderValue {
    * container carries hole markers, so a HIT must gate the overlay on the
    * fresh run (only the loader body can mint the live nested promises);
    * 0 = fully pinned, so a HIT resolves the payload promise immediately from
-   * the pin while the fresh run proceeds ungated (side effects and cache
-   * read-through writes preserved; its values were discarded either way —
-   * recorded paths win wholesale). Absent on pre-bit snapshots, which keep
-   * the gated path.
+   * the pin and does not run the loader body (unless `runs`). Absent on
+   * pre-bit snapshots, which keep the gated path.
    */
   holes?: 0 | 1;
+  /**
+   * 1 when the capture saw a loader push it could not record (a deferred
+   * push, one with masked nested promises, or one made outside any loader
+   * body): a HIT then still runs the loader body in the background
+   * (pin-first) so those pushes reach the page. 0: a hole-free record is
+   * served from the pin alone and its body does not run on a HIT. Absent (a
+   * snapshot written before the bit, which lacks the loader-owned pushes)
+   * reads as 1, so the body supplies them.
+   */
+  runs?: 0 | 1;
 }
 
 /** A serialized cached Response for the response family of a shell snapshot. */
@@ -542,6 +707,11 @@ export interface CachedEntryData {
    *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
    *  round-trip through JSON-serializing stores instead of being flattened. */
   handles: string;
+  /**
+   * Owning loader ids index-aligned with the decoded `handles` values
+   * (HandleOwners). Absent: every value restores as a plain replay.
+   */
+  handleOwners?: HandleOwners;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
   /** Cache tags for invalidation */
@@ -583,3 +753,14 @@ export interface CacheDefaults {
  * Structure: { handleName: [values...] }
  */
 export type SegmentHandleData = Record<string, unknown[]>;
+
+/**
+ * segmentId -> handleName -> the owning loader id of each recorded value, by
+ * index (null: not owned). Only a PPR shell capture writes owners: the
+ * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
+ * the loaders it awaits, and its own cache() replays), which the record keeps
+ * because the prelude rendered them. restoreHandles replays an owned value
+ * through HandleStore.pushReplayed, so a loader that does run on the HIT
+ * replaces it with its live push.
+ */
+export type HandleOwners = Record<string, Record<string, (string | null)[]>>;