@rangojs/router 0.22.1 → 0.23.0

package/src/cache/cf/cf-cache-store.ts

@@ -15,6 +15,9 @@ declare global {
  * L2 (KV): Global, persistent, ~50ms reads. Auto-warms cold colos.
  *
  * Read flow:  L1 hit → serve | L1 miss → L2 hit → serve + promote to L1 | both miss → render
+ *             With `kvFallThrough`, an L1 copy a tag marker rejects reads as
+ *             an L1 miss: L2 is checked against the same markers (see get(),
+ *             "Tag invalidation"). Off by default: the rejected copy is a miss.
  * Write flow: L1 write + L2 write (both via waitUntil)
  *
  * Features:
@@ -388,7 +391,7 @@ type OpenedShellFrame =
   | { status: "corrupt"; error: Error; head?: undefined }
   | { status: "expired"; head: ShellFrameHead }
   | { status: "timeout"; head?: undefined }
-  | { status: "invalidated"; head?: undefined };
+  | { status: "invalidated"; head: ShellFrameHead };
 
 /** The `[CFCacheStore][shell]` trace's timings, from a read's stats. */
 function debugTimings(
@@ -531,6 +534,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly tagPurge?: (cacheTags: string[]) => Promise<void>;
   private readonly tagInvalidationTtl?: number;
   private readonly tagCacheTtl: number;
+  private readonly kvFallThrough: boolean;
 
   constructor(options: CFCacheStoreOptions<TEnv>) {
     if (!options.ctx) {
@@ -605,6 +609,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
+    this.kvFallThrough = options.kvFallThrough === true && !!options.kv;
     // Without KV, isTagsInvalidatedSince has no durable history — it answers
     // from the per-request mask at best. Runtime shells tolerate that (purge
     // eviction + ttl/swr bound the staleness), but an immutable TAGGED
@@ -1210,16 +1215,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetSegment(key, { suppressRevalidate: true });
       }
 
-      // Tag invalidation: an entry whose tags were invalidated after it was
-      // cached is treated as a miss, so the next render re-populates it. We
-      // return null (re-render locally) rather than falling through to KV. In
-      // the common case the L1 entry and its KV twin were written together with
-      // the same taggedAt, so kvGetSegment's own tag check would miss too and a
-      // fall-through is pure cost. The tiers CAN diverge -- another colo may have
-      // already re-rendered and written a fresher KV envelope -- in which case a
-      // fall-through could serve that copy instead of re-rendering here.
-      // Capturing that cross-colo optimization is a deferred follow-up, not a
-      // correctness gap: this colo's next read after its own re-render self-heals.
+      // Tag invalidation: a copy whose tags were invalidated after it was
+      // cached is never served. Without `kvFallThrough` it is a miss and this
+      // colo re-renders. With it, it reads as an L1 miss, because the tiers can
+      // diverge: another colo may have written KV after the marker (its own
+      // re-render, or a router.prerender() warm after updateTag()), and this
+      // colo then serves that entry instead of rendering it again.
+      // kvGetSegment checks the KV entry against the same markers (this
+      // request's memo: no second marker read) and promotes a valid one over
+      // this copy. When KV still holds the twin written with this copy, the
+      // read costs one KV get and misses as before. The request that
+      // invalidated the tag itself keeps the plain miss (declinesKvFallThrough).
       const tagInfo = this.readTagInfo(response.headers);
       // Measure the marker-resolution tail (memo -> L1 marker cache -> KV) only
       // when debug is on, so the hot path pays nothing. It is the serial read
@@ -1241,7 +1247,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             matchMs,
             markerMs,
           });
-        return null;
+        return this.declinesKvFallThrough(tagInfo.tags, tagInfo.taggedAt)
+          ? null
+          : this.kvGetSegment(key);
       }
 
       // Read status headers
@@ -1524,7 +1532,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetResponse(key);
       }
 
-      // Tag invalidation check (treat invalidated entry as a miss).
+      // Tag invalidation check: a rejected copy reads as an L1 miss (see get()).
       const tagInfo = this.readTagInfo(response.headers);
       if (
         await this.isL1Invalidated(
@@ -1533,7 +1541,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           response.headers,
         )
       ) {
-        return null;
+        return this.declinesKvFallThrough(tagInfo.tags, tagInfo.taggedAt)
+          ? null
+          : this.kvGetResponse(key);
       }
 
       // Check staleness
@@ -1801,8 +1811,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetItem(key, { suppressRevalidate: true });
       }
 
-      // Tag invalidation check (treat invalidated entry as a miss). Measure the
-      // marker-resolution tail only under debug (see get()).
+      // Tag invalidation check: a rejected copy reads as an L1 miss (see
+      // get()). Measure the marker-resolution tail only under debug.
       const tagInfo = this.readTagInfo(response.headers);
       const markerStart = this.debug ? Date.now() : 0;
       const invalidated = await this.isL1Invalidated(
@@ -1821,7 +1831,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             matchMs,
             markerMs,
           });
-        return null;
+        return this.declinesKvFallThrough(tagInfo.tags, tagInfo.taggedAt)
+          ? null
+          : this.kvGetItem(key);
       }
 
       const staleAt = Number(
@@ -2233,7 +2245,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           tier: "l1",
           stats,
         });
-        return null;
+        // As get(): KV may hold a capture from after the marker.
+        return this.declinesKvFallThrough(opened.head.t, opened.head.ta)
+          ? null
+          : kvFallback("invalidated");
       }
       const read = this.shellDocumentRead(
         key,
@@ -2325,7 +2340,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * dropped and read from the store (SWR recapture scheduling and each mode's
    * invalidation semantics stay with the store read). That read keeps the
    * caller's `tagHints`: cfTagHints may have evicted the key while the memo
-   * still holds it.
+   * still holds it. A shell a tag marker rejects is dropped and read from
+   * the store too, which may hold a capture from after the marker (see
+   * get(), "Tag invalidation"), unless the request's own mask rejected it
+   * (declinesKvFallThrough).
    */
   private async readMemoizedShell(
     key: string,
@@ -2360,7 +2378,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         tier: "memo",
         stats,
       });
-      return null;
+      return this.declinesKvFallThrough(head.t, head.ta)
+        ? null
+        : this.readShellDocumentWithin(key, options, snapshotBudget);
     }
     if (stats) stats.memo = { hit: true, bytes: cfShellMemo.size };
     this.recordShellHit(key, head.t, stats);
@@ -2472,7 +2492,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
     if (invalidated) {
       reader.cancel();
-      return { status: "invalidated" };
+      return { status: "invalidated", head: value.head };
     }
     return value;
   }
@@ -3341,6 +3361,24 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return false;
   }
 
+  /**
+   * Whether a rejected L1 copy skips the KV read: always unless the
+   * `kvFallThrough` option is on, and with it on when this request's own
+   * updateTag()/revalidateTag() (its mask, request-tag-mask.ts) rejects an
+   * entry tagged at `taggedAt`. KV holds a newer entry only if something
+   * rendered after this request's invalidation, while the request re-renders
+   * every entry it masked, so the read would add one KV get per masked entry
+   * to that re-render.
+   * @internal
+   */
+  private declinesKvFallThrough(
+    tags: string[] | undefined,
+    taggedAt: number | undefined,
+  ): boolean {
+    if (!this.kvFallThrough) return true;
+    return maskedForRequest(_getRequestContext(), this, tags, taggedAt ?? 0);
+  }
+
   /**
    * Synthetic Cache API request for a tag's L1-cached invalidation marker.
    * Unversioned for the same reason as tagMarkerKey; the cache namespace

package/src/cache/cf/cf-cache-types.ts

@@ -66,8 +66,11 @@ export interface CFCacheReadDebugEvent {
    * - kv-timeout: the L2/KV read budget fired (read abandoned, NOT a genuine
    *   absence -- distinct from kv-miss so a degradation signal is separable)
    * - tag-invalidated: a live L1/KV entry whose cache tags were invalidated
-   *   after it was written -- treated as a miss so the next render re-populates
-   *   it (the tag-invalidation read path, distinct from a plain miss)
+   *   after it was written -- never served (the tag-invalidation read path,
+   *   distinct from a plain miss). With `kvFallThrough` on, an L1 copy then
+   *   reads L2/KV, so a kv-* event follows unless the request invalidated the
+   *   tag itself; from L2/KV it is a miss and the next render re-populates
+   *   the entry
    * - error: the read threw
    */
   outcome:
@@ -383,6 +386,25 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   kvReadTimeoutMs?: number;
 
+  /**
+   * After `updateTag()`/`revalidateTag()`, a location whose own L1 copy a tag
+   * marker rejects reads KV next, and serves the entry another location (or a
+   * `router.prerender()` warm) wrote after the invalidation, instead of
+   * rendering again. Covers `cache()` records, `"use cache"` results, cached
+   * responses and `ppr` shells. The request that invalidated the tag still
+   * re-renders its own entries without the read.
+   *
+   * Cost: one KV get per rejected copy per location after each invalidation
+   * (150 ms added wait, measured in #1069 locally at 50 ms per KV read on a
+   * document with a shell, a record and one `"use cache"` result, every copy
+   * rejected; not measured on a deployed worker), paid even when KV holds only
+   * the old twin. Worth it where re-rendering costs more than a KV read
+   * (several locations, expensive renders). Needs `kv`; ignored without it.
+   *
+   * Defaults to false: a rejected L1 copy is a miss and the location renders.
+   */
+  kvFallThrough?: boolean;
+
   /**
    * Per-isolate memos ({@link StoreMemoOptions}), one set per isolate and
    * shared by every CFCacheStore in it. `shellMs` (default 2000) and

package/src/cache/document-cache.ts

@@ -14,6 +14,7 @@
  */
 
 import { requestHeaders } from "../server/request-headers.js";
+import { FILL_PARAM } from "../prefetch-markers.js";
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { hasPerClientSignal } from "../browser/cookie-name.js";
 import {
@@ -122,7 +123,10 @@ function parseCacheControl(header: string | null): CacheDirectives | null {
  */
 function shouldCacheResponse(
   response: Response,
-  requestCtx?: Pick<RequestContext, "_payloadVisitorTheme">,
+  requestCtx?: Pick<
+    RequestContext,
+    "_payloadVisitorTheme" | "_payloadDeferred"
+  >,
 ): CacheDirectives | null {
   // Only cache successful responses
   if (response.status !== 200) {
@@ -146,6 +150,15 @@ function shouldCacheResponse(
     return null;
   }
 
+  // prefetch: false. The payload carries deferred units: it answers one
+  // page's prefetch and nothing else. parseCacheControl refuses the
+  // Cache-Control it is sent with (rsc-rendering.ts NOT_REUSED), but a
+  // middleware can replace that after next(), and a navigation answered
+  // with this body would show a fallback no fill ever replaces.
+  if (requestCtx?._payloadDeferred) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }
@@ -337,6 +350,14 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
+    // Skip fill requests (prefetch: false): a fill is the second half of one
+    // adoption, rendered against what that client holds. Never served from a
+    // stored body and never stored. Asked of the raw URL like the two skips
+    // above: the request context is not read yet.
+    if (rawUrl.searchParams.has(FILL_PARAM)) {
+      return next();
+    }
+
     // Skip configured paths
     if (skipPaths.some((path) => url.pathname.startsWith(path))) {
       return next();

package/src/client-urls/client-urls.ts

@@ -3,9 +3,9 @@ import { validateUserRouteName } from "../route-name.js";
 import { buildRouteTrie } from "../router/route-trie-builder.js";
 import { tryTrieMatch } from "../router/trie-matching.js";
 import type { LoaderDefinition } from "../types.js";
+import { isHoistedRevalidateRef } from "./hoisted-revalidate.js";
 import type {
   ClientPathOptions,
-  ClientRevalidateFn,
   ClientTransitionConfig,
   ClientUrlBuilder,
   ClientUrlHelpers,
@@ -137,13 +137,14 @@ interface TransitionItem extends ItemBase {
 interface LoaderItem extends ItemBase {
   readonly type: "loader";
   readonly definition: LoaderDefinition<any, any>;
-  readonly revalidate: readonly ClientRevalidateFn[];
+  readonly revalidate: ClientUrlLoaderRecord["revalidate"];
   readonly ssr?: false;
+  readonly prefetch?: false;
 }
 
 interface RevalidateItem extends ItemBase {
   readonly type: "revalidate";
-  readonly fn: ClientRevalidateFn;
+  readonly fn: ClientUrlLoaderRecord["revalidate"][number];
 }
 
 interface LoadingItem extends ItemBase {
@@ -386,11 +387,22 @@ function createHelpers(): ClientUrlHelpers {
         "clientUrls() loader() stream was replaced: use loader(Def, { ssr: false }) — the same knob as loading(fallback, { ssr: false }) — to await the loader before first flush on document requests.",
       );
     }
+    // Inline, not errors.ts assertBooleanOption: this module is in the
+    // client router chunk, where the helper costs 20 B gzip.
     if (options?.ssr !== undefined && typeof options.ssr !== "boolean") {
       throw new Error(
         `clientUrls() loader() ssr must be a boolean (got ${JSON.stringify(options.ssr)}). Omit it (or pass true) to stream on every render.`,
       );
     }
+    if (
+      process.env.NODE_ENV !== "production" &&
+      options?.prefetch !== undefined &&
+      typeof options.prefetch !== "boolean"
+    ) {
+      throw new Error(
+        `clientUrls() loader() prefetch must be a boolean (got ${JSON.stringify(options.prefetch)}). Omit it (or pass true) to run the loader in prefetches.`,
+      );
+    }
     const items = use ? runUse(use, "loader use") : [];
     rejectItems(items, new Set(["revalidate"]), "loader");
     return toPublicItem({
@@ -404,11 +416,14 @@ function createHelpers(): ClientUrlHelpers {
         )
         .map((item) => item.fn),
       ...(options?.ssr === false ? { ssr: false as const } : {}),
+      ...(options?.prefetch === false ? { prefetch: false as const } : {}),
     });
   };
 
   const revalidate: ClientUrlHelpers["revalidate"] = (fn) => {
-    if (typeof fn !== "function") {
+    // The build leaves a marker in place of the predicate it moved to the
+    // server (vite/plugins/client-urls-revalidate-hoist.ts).
+    if (typeof fn !== "function" && !isHoistedRevalidateRef(fn)) {
       throw new Error("clientUrls() revalidate() expects a predicate function");
     }
     return toPublicItem({
@@ -563,6 +578,7 @@ function applyConfig(
           loader: item.definition,
           revalidate: Object.freeze([...item.revalidate]),
           ...(item.ssr === false ? { ssr: false as const } : {}),
+          ...(item.prefetch === false ? { prefetch: false as const } : {}),
         }),
       );
     } else if (item.type === "loading") {
@@ -675,6 +691,8 @@ function collectIntercepts(
       let loading: ReactNode | undefined;
       for (const useItem of item.use) {
         if (useItem.type === "loader") {
+          // `prefetch` is not carried: an intercept prefetch defers nothing,
+          // so the flag is accepted and ignored, as on a urls() intercept().
           loaders.push(
             Object.freeze({
               loader: useItem.definition,
@@ -762,8 +780,6 @@ export function clientUrls<const TItems extends ClientUrlItems>(
 }
 
 export type {
-  ClientRevalidateArgs,
-  ClientRevalidateFn,
   ClientTransitionConfig,
   ClientUrlBuilder,
   ClientUrlHelpers,

package/src/client-urls/hoisted-revalidate.ts

@@ -0,0 +1,25 @@
+/**
+ * The value the build leaves in place of a clientUrls() `revalidate()`
+ * predicate in the browser and SSR copies of a "use client" module
+ * (vite/plugins/client-urls-revalidate-hoist.ts): the predicate itself moves
+ * to a server module, registered under the same content key
+ * (revalidate-registry.ts). The projection carries the key; the materialized
+ * loader stub calls the registered predicate.
+ */
+
+export const HOISTED_REVALIDATE_KEY = "$$rangoRevalidate";
+
+export interface HoistedRevalidateRef {
+  readonly $$rangoRevalidate: string;
+}
+
+export function isHoistedRevalidateRef(
+  value: unknown,
+): value is HoistedRevalidateRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Partial<HoistedRevalidateRef>)[HOISTED_REVALIDATE_KEY] ===
+      "string"
+  );
+}

package/src/client-urls/navigation.ts

@@ -1,12 +1,6 @@
 "use client";
 
 import { startTransition } from "react";
-import { makeIsAction } from "../router/is-action.js";
-import {
-  lockedClientDefault,
-  runClientRevalidateChain,
-} from "./revalidate-chain.js";
-import { encodeClientRevalidationDecisions } from "./revalidation-protocol.js";
 import type { ClientUrlPatterns } from "./types.js";
 import type { TransitionWhenFn } from "../types/segments.js";
 
@@ -210,96 +204,6 @@ export function beginClientUrlNavigation(
   };
 }
 
-/**
- * Run the held clientUrls route's per-loader revalidate() predicates and
- * encode their decisions for the request header. Predicates are CLIENT code
- * (declared in the "use client" definition module); only decisions cross the
- * wire — the synthesized per-loader revalidate() on every materialized stub
- * (server-projection.ts) reads them back by loader $$id.
- *
- * Decisions exist only for the loaders the client currently HOLDS: the local
- * match of currentUrl. They matter when the server would re-evaluate those
- * held loader segments — same-route param/search navs, actions, and stale
- * restores. Cross-route targets render new segments unconditionally, so a
- * decision would be ignored; we still compute against the current route since
- * only its held segments are addressable.
- *
- * Returns null when no group is active, the current location is not a client
- * route, or no predicate produced a decision that differs from the locked
- * default — the server then applies defaults, which is also the behavior for
- * requests that cannot carry decisions (no-JS, PE, prefetch, document loads).
- */
-export function collectClientRevalidationDecisions(options: {
-  currentUrl: URL;
-  nextUrl: URL;
-  /**
-   * True only when the decisions ride the action POST itself — the one
-   * request the server evaluates with actionContext (locked default true).
-   * Action-triggered refetch GETs (partial-update terminals) pass false:
-   * the server gives those navigation defaults, and the delta gate below
-   * must diff against the default the SERVER will use, or a force decision
-   * on the refetch would be silently swallowed as "equals default".
-   */
-  actionRequest: boolean;
-  /** Action TRUTH for the predicates' isAction() matcher; may be true on
-   * refetch GETs where actionRequest is false. */
-  isAction: boolean;
-  actionId?: string;
-  stale: boolean;
-}): string | null {
-  const group = activeGroup;
-  if (!group) return null;
-
-  const { currentUrl, nextUrl, actionRequest, isAction, actionId, stale } =
-    options;
-  const currentLocal = stripMountPrefix(currentUrl.pathname, group.mount);
-  if (currentLocal === null) return null;
-  const currentMatch = group.definition.match(currentLocal);
-  if (!currentMatch || currentMatch.redirectTo) return null;
-  const record = group.definition.routes.find(
-    (candidate) => candidate.id === currentMatch.routeKey,
-  );
-  if (!record) return null;
-
-  const nextLocal = stripMountPrefix(nextUrl.pathname, group.mount);
-  const nextMatch =
-    nextLocal === null ? null : group.definition.match(nextLocal);
-  const nextParams = nextMatch?.params ?? {};
-
-  const defaultShouldRevalidate = lockedClientDefault({
-    actionRequest,
-    currentParams: currentMatch.params,
-    nextParams,
-    currentUrl,
-    nextUrl,
-  });
-
-  const baseArgs = {
-    currentUrl,
-    nextUrl,
-    currentParams: currentMatch.params,
-    nextParams,
-    stale,
-    isAction: makeIsAction(actionId, isAction),
-    ...(actionId !== undefined ? { actionId } : {}),
-  };
-  const skip: string[] = [];
-  const force: string[] = [];
-  for (const { loader, revalidate } of record.loaders) {
-    if (revalidate.length === 0) continue;
-    const decision = runClientRevalidateChain(
-      revalidate,
-      baseArgs,
-      defaultShouldRevalidate,
-      `loader "${loader.$$id}"`,
-    );
-    if (decision === defaultShouldRevalidate) continue;
-    (decision ? force : skip).push(loader.$$id);
-  }
-
-  return encodeClientRevalidationDecisions({ skip, force });
-}
-
 export function clearClientUrlNavigationRegistry(): void {
   activeGroup = null;
   activeInterceptTargets = new Set();

package/src/client-urls/revalidate-registry.ts

@@ -0,0 +1,30 @@
+import type { ShouldRevalidateFn } from "../types.js";
+
+/**
+ * Hoisted clientUrls() `revalidate()` predicates by content key. The
+ * generated `<file>?rango-revalidate` module of a group fills it when the
+ * group's module loads in the RSC realm
+ * (vite/plugins/client-urls-revalidate-hoist.ts); materialized loader stubs
+ * read it (server-projection.ts). A key hashes the file and the predicate's
+ * syntax, so a re-registration under one key is the same predicate.
+ *
+ * Server-only build output, not router state: no router hook reads it
+ * (AGENTS.md Hard rule 8).
+ */
+const revalidators = new Map<string, ShouldRevalidateFn<any, any>>();
+
+export function registerClientUrlRevalidators(
+  fns: Readonly<Record<string, ShouldRevalidateFn<any, any>>>,
+): void {
+  for (const [key, fn] of Object.entries(fns)) revalidators.set(key, fn);
+}
+
+export function getClientUrlRevalidator(
+  key: string,
+): ShouldRevalidateFn<any, any> | undefined {
+  return revalidators.get(key);
+}
+
+export function clearClientUrlRevalidators(): void {
+  revalidators.clear();
+}