@rangojs/router 0.31.0 → 0.33.0

package/src/browser/prefetch/cache.ts

@@ -7,11 +7,14 @@
  * stream resolves the route's client references, so the route's JS chunks are
  * imported during prefetch rather than on click. The decoded payload is reused
  * verbatim by navigation, so a prefetched click loads no new code. Two key
- * scopes are in play:
+ * scopes are in play. Wherever a key below says `rangoState`, callers pass the
+ * state's `{version}:{timestamp}` part (cookie-name.ts stateEpoch), not the
+ * whole value: a server action's write bump leaves the keys as they were.
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
  *   source segment trees; `_rsc_segments` is omitted from this key. Invalidated
- *   automatically when Rango state bumps (deploy or server-action invalidation).
+ *   automatically when Rango state bumps (deploy or invalidateClientCache()).
+ *   A server action marks entries stale instead (the stale epoch, below).
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
  *   (so rotation invalidates source-scoped entries too), the source href, and
@@ -20,6 +23,14 @@
  *   targets, matched or not), OR when a Link opts in with
  *   `prefetchKey=":source"` — in both cases so source-sensitive responses
  *   cannot bleed into navigations from other pages.
+ * - Params-scoped: built by `buildParamsKey(rangoState, label, target)` —
+ *   shape `rangoState\0p:<label>\0/target?...`. Populated when the server
+ *   tags a response with `X-RSC-Prefetch-Scope: params; <label>`: a
+ *   revalidate() rule read the source's params or route name and kept a
+ *   segment, so the answer is right for every page with equal values of
+ *   what it read (prefetch-source-scope.ts). `paramsShapes` remembers, per
+ *   target, what the stored labels read, so a lookup rebuilds the label of
+ *   the page on screen (paramsCandidateKeys).
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
  * decoded prefetch entry (or null), letting navigation adopt a
@@ -44,6 +55,13 @@ import { notifyPrefetchCacheInvalidated } from "./invalidation.js";
 import { invalidateRangoState } from "../rango-state.js";
 import type { RscPayload } from "../types.js";
 import { WIRE } from "../../wire-params.js";
+import {
+  formatSourceLabel,
+  parseSourceShape,
+  sourceShapeId,
+  type SourcePage,
+  type SourceShape,
+} from "../../prefetch-source-scope.js";
 
 /**
  * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
@@ -64,9 +82,23 @@ export interface DecodedPrefetch {
    * Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
    * `"source"` means the response is source-page-sensitive and must not be
    * reused by a navigation from a different page — navigation enforces this
-   * when it adopted an inflight entry through the wildcard key.
+   * when it adopted an inflight entry through the wildcard key. `"params"`
+   * means it serves the pages whose label equals `paramsLabel`.
    */
-  scope: "source" | "wildcard";
+  scope: PrefetchScope;
+  /** The label of a `"params"` entry (prefetch-source-scope.ts). */
+  paramsLabel?: string;
+  /**
+   * The stale epoch (`currentPrefetchEpoch()`) the prefetch's fetch started
+   * under. A server action without a directive marks every prefetch stale
+   * (`markPrefetchesStale()` bumps the epoch) instead of flushing it: an entry
+   * from an older epoch is still served, and the navigation that adopts it
+   * revalidates its page once it settled (`isPrefetchStale`). A stale entry
+   * is served at most once, and only to a click (`consumePrefetch`'s
+   * `acceptStale`). A respawn keeps the original fetch's epoch, as it keeps
+   * its timestamp.
+   */
+  epoch: number;
   /**
    * Synchronously-readable flag, flipped to true when `streamComplete` resolves
    * (the entire RSC stream has drained). Navigation reads this at click time to
@@ -108,6 +140,9 @@ export interface DecodedPrefetch {
   dispose?: () => void;
 }
 
+/** Where a prefetch is stored: see the module comment. */
+export type PrefetchScope = "source" | "params" | "wildcard";
+
 let cacheTTL = 300_000;
 let fragmentPassthroughEnabled = true;
 
@@ -163,8 +198,25 @@ const inflightAliases = new Map<string, string[]>();
 
 const adoptedKeys = new Set<string>();
 
+/**
+ * What the stored params-scoped labels of a target read, by
+ * `buildPrefetchKey("", target)`: the shapes paramsCandidateKeys rebuilds
+ * labels from. Bounded like the cache; cleared with it.
+ */
+const paramsShapes = new Map<string, Map<string, SourceShape>>();
+
 let generation = 0;
 
+/**
+ * The stale epoch. `markPrefetchesStale()` bumps it; an entry whose fetch
+ * started under an older one is stale (`isPrefetchStale`). Separate from
+ * `generation`: a stale mark keeps every entry and every in-flight fetch,
+ * where a generation bump drops them. So a Flight response that has already
+ * arrived is never aborted by an action (aborting it mid-stream errors
+ * the stream): an in-flight prefetch finishes and lands stale.
+ */
+let staleEpoch = 0;
+
 /**
  * Build a cache key by combining a scope prefix with the target URL.
  *
@@ -172,7 +224,7 @@ let generation = 0;
  * one of:
  * - Wildcard (source-agnostic): prefix is the Rango state value from
  *   `getRangoState()`. Shared across all source pages. Invalidated
- *   automatically when Rango state bumps (deploy or server-action).
+ *   automatically when Rango state bumps (deploy or invalidateClientCache()).
  *   `_rsc_segments` is omitted so sibling payloads prefetched from one page
  *   remain reusable after another prefetched navigation commits. Key shape:
  *   `rangoState\0/target?...`.
@@ -218,6 +270,76 @@ export function buildSourceKey(
   );
 }
 
+/**
+ * Build a params-scoped cache key. Key shape:
+ * `rangoState\0p:<label>\0/target?...`, the target normalized like the
+ * wildcard key's: the answer serves every page with this label, whatever
+ * segments it holds, as a wildcard answer serves every page.
+ */
+export function buildParamsKey(
+  rangoState: string,
+  label: string,
+  targetUrl: URL,
+): string {
+  return buildPrefetchKey(rangoState + "\0p:" + label, targetUrl);
+}
+
+/**
+ * Remember that a params-scoped answer for `targetUrl` is stored under a
+ * label of this shape. Called where the response header is read, with the
+ * store (fetch.ts executePrefetchFetch).
+ */
+export function rememberParamsShape(targetUrl: URL, label: string): void {
+  const target = buildPrefetchKey("", targetUrl);
+  const shape = parseSourceShape(label);
+  let shapes = paramsShapes.get(target);
+  if (!shapes) {
+    if (paramsShapes.size >= maxPrefetchCacheSize) {
+      const oldest = paramsShapes.keys().next().value;
+      if (oldest !== undefined) paramsShapes.delete(oldest);
+    }
+    shapes = new Map();
+    paramsShapes.set(target, shapes);
+  }
+  shapes.set(sourceShapeId(shape), shape);
+}
+
+/**
+ * The params-scoped keys a request for `targetUrl` from `page` may adopt:
+ * the page's label under each shape stored for the target, the shapes that
+ * read the most first. Empty without a page (before boot).
+ */
+export function paramsCandidateKeys(
+  rangoState: string,
+  targetUrl: URL,
+  page: SourcePage | null,
+): string[] {
+  if (!page) return [];
+  const shapes = paramsShapes.get(buildPrefetchKey("", targetUrl));
+  if (!shapes) return [];
+  return [...shapes.values()]
+    .sort((a, b) => weightOf(b) - weightOf(a))
+    .map((shape) =>
+      buildParamsKey(rangoState, formatSourceLabel(shape, page), targetUrl),
+    );
+}
+
+const weightOf = (shape: SourceShape): number =>
+  shape.names.length + (shape.route ? 1 : 0) + (shape.keys ? 1 : 0);
+
+/**
+ * Whether `page` is in the group a params-scoped entry serves: its label
+ * under the entry's shape equals the entry's.
+ */
+export function pageMatchesParamsLabel(
+  label: string,
+  page: SourcePage | null,
+): boolean {
+  return (
+    page !== null && formatSourceLabel(parseSourceShape(label), page) === label
+  );
+}
+
 /**
  * Walk an inflight key plus any sibling aliases registered via
  * `setInflightPromiseWithAliases`, invoking `fn` for each.
@@ -233,13 +355,19 @@ function forEachAlias(key: string, fn: (k: string) => void): void {
 
 /**
  * Check if a prefetch is already cached, in-flight, or queued for the given key.
+ *
+ * A stale stored entry (`isPrefetchStale`) counts as absent and is dropped, so
+ * a new hover or viewport trigger replaces it with a fresh prefetch, and a
+ * click made while that one is in flight adopts it rather than the stale one.
+ * An in-flight fetch counts whatever its epoch: it is never aborted, and a
+ * duplicate request for its key would race it for the slot.
  */
 export function hasPrefetch(key: string): boolean {
   if (inflight.has(key)) return true;
   if (cacheTTL <= 0) return false;
   const entry = cache.get(key);
   if (!entry) return false;
-  if (Date.now() - entry.timestamp > cacheTTL) {
+  if (Date.now() - entry.timestamp > cacheTTL || isPrefetchStale(entry.entry)) {
     entry.entry.dispose?.();
     cache.delete(key);
     return false;
@@ -258,10 +386,20 @@ export function hasPrefetch(key: string): boolean {
  * TTL bounds the age of the data, not of the latest adoption. Without
  * `respawn` the entry is deleted (legacy one-shot behavior).
  *
+ * A stale entry (`isPrefetchStale`) is served only to a caller that passes
+ * `acceptStale` (a click, which revalidates its page once it settled,
+ * navigation-bridge.ts): for any other caller it is a miss and stays in its
+ * slot. It is served at most once: its slot is not re-armed, so a second
+ * click on the same link fetches fresh rather than showing pre-write data
+ * older than what the first click's revalidation showed.
+ *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
  * for that (returns a Promise instead of a resolved entry).
  */
-export function consumePrefetch(key: string): DecodedPrefetch | null {
+export function consumePrefetch(
+  key: string,
+  options?: { acceptStale?: boolean },
+): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
   const cached = cache.get(key);
   if (!cached) return null;
@@ -271,10 +409,15 @@ export function consumePrefetch(key: string): DecodedPrefetch | null {
     return null;
   }
   const entry = cached.entry;
-  if (entry.respawn) {
+  const stale = isPrefetchStale(entry);
+  if (stale && !options?.acceptStale) return null;
+  if (entry.respawn && !stale) {
     cached.entry = entry.respawn();
   } else {
     cache.delete(key);
+    // The buffered reserve (fetch.ts) is never replayed: release it. It is a
+    // separate tee branch, so the payload the caller adopts keeps streaming.
+    if (stale) entry.dispose?.();
   }
   return entry;
 }
@@ -318,12 +461,18 @@ export function consumeInflightPrefetch(
  * Store an eagerly-decoded prefetch in the in-memory cache.
  *
  * Skips storage if the generation has changed since the fetch started
- * (a server action invalidated the cache mid-flight).
+ * (the cache was flushed mid-flight). An entry from an older stale epoch (an
+ * action marked prefetches stale mid-flight) is stored, and stays stale.
+ *
+ * `inflightKey` is the key the prefetch was in flight under, when the
+ * storage key is not one of its aliases (a params-scoped answer): a
+ * navigation that adopted it marked the aliases.
  */
 export function storePrefetch(
   key: string,
   entry: DecodedPrefetch,
   fetchGeneration: number,
+  inflightKey: string = key,
 ): void {
   if (cacheTTL <= 0) return;
   if (fetchGeneration !== generation) return;
@@ -333,8 +482,8 @@ export function storePrefetch(
   // publish it to the cache map, or a later navigation would be served the
   // exhausted entry and lose that route's handles. Clear the marker (under all
   // aliases) now that the decision is made.
-  if (adoptedKeys.has(key)) {
-    forEachAlias(key, (k) => adoptedKeys.delete(k));
+  if (adoptedKeys.has(inflightKey)) {
+    forEachAlias(inflightKey, (k) => adoptedKeys.delete(k));
     return;
   }
 
@@ -398,6 +547,33 @@ export function currentGeneration(): number {
   return generation;
 }
 
+/**
+ * Capture the current stale epoch. A prefetch fetch stamps its entry with the
+ * value read when it started (`DecodedPrefetch.epoch`).
+ */
+export function currentPrefetchEpoch(): number {
+  return staleEpoch;
+}
+
+/** Whether an action marked prefetches stale after this entry's fetch began. */
+export function isPrefetchStale(
+  entry: Pick<DecodedPrefetch, "epoch">,
+): boolean {
+  return entry.epoch < staleEpoch;
+}
+
+/**
+ * Mark every stored and in-flight prefetch stale: what a server action
+ * without a directive does (navigation-store.ts markCacheAsStaleAndBroadcast).
+ * Only bumps the epoch. Nothing is dropped, aborted or rotated, and visible
+ * links are not told (no `notifyPrefetchCacheInvalidated()`), so they do not
+ * prefetch again. A click on a stale entry commits it at once; the navigation
+ * then revalidates its page (navigation-bridge.ts navigate).
+ */
+export function markPrefetchesStale(): void {
+  staleEpoch++;
+}
+
 export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
@@ -457,6 +633,7 @@ export function clearPrefetchCache(rotateRangoState = true): void {
   inflightPromises.clear();
   inflightAliases.clear();
   adoptedKeys.clear();
+  paramsShapes.clear();
   for (const cached of cache.values()) cached.entry.dispose?.();
   cache.clear();
   earliestTimestamp = Infinity;