@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

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

@@ -14,6 +14,7 @@
 import type { ExecutionContext } from "../../types/request-scope.js";
 import type { CacheDefaults } from "../types.js";
 import type { RequestContext } from "../../server/request-context.js";
+import type { CloudflareZonePurgeOptions } from "./cf-zone-purge.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.
@@ -197,6 +198,71 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   onRevalidateTag?: (cacheTags: string[]) => Promise<void>;
 
+  /**
+   * Purge-based tag invalidation (purge mode). When configured, the store
+   * delegates L1 (Cache API) tag eviction to Cloudflare's purge-by-tag API
+   * instead of the per-read KV marker lookup.
+   *
+   * Two forms:
+   * - **Credentials object** (the normal wiring): `{ zoneId, apiToken }` — the
+   *   store builds the purge client itself (createCloudflareZonePurge).
+   *   `zoneId` is on the zone's dashboard overview; `apiToken` needs the
+   *   `Zone.Cache Purge` permission for that zone — store it as a Worker
+   *   secret. Validated at store construction (Workers run no code at deploy,
+   *   so with the usual per-request cache factory this means the first request
+   *   throws — loudly and on every request), rather than surfacing only when
+   *   the first invalidation quietly rejects much later.
+   * - **Function** `(cacheTags) => Promise<void>` — an escape hatch for
+   *   proxies, custom transports, or test stubs; receives the exact
+   *   Cache-Tags to purge.
+   *
+   * Semantics:
+   * - Every tagged L1 entry carries a namespaced `Cache-Tag` header
+   *   (`rg:{namespace}:e:{encodedTag}`, plus the broader `rg:{namespace}` /
+   *   `rg:{namespace}:e` tiers for manual resets).
+   * - `updateTag()`/`revalidateTag()` AWAIT the purge with the exact Cache-Tags
+   *   (one batched call per invalidation; entry tags, plus the lookup
+   *   Cache-Tags when `tagCacheTtl > 0`).
+   * - L1 hits then skip the per-read marker lookup entirely: a surviving entry
+   *   is trusted because an invalidated one would have been purged. Only the
+   *   per-request memo is consulted (synchronously, no KV read), so a request
+   *   that ran `updateTag()` still masks its own not-yet-purged entries
+   *   (read-your-own-writes).
+   * - The KV tier and PPR shells still use the KV markers — those are written
+   *   regardless, and purge cannot reach KV — so keep `kv` configured for L2.
+   *   Without `kv`, purge mode is the ONLY tag invalidation and the store is
+   *   L1-only: a supported configuration (previously tag invalidation without
+   *   KV had no read-side effect at all). One KV-less caveat: an entry whose
+   *   tag set overflows Cloudflare's 16 KB Cache-Tag header limit is NOT
+   *   cached (it would be un-invalidatable — no tokens for the purge, no
+   *   marker fallback); with `kv` such an entry caches and falls back to the
+   *   marker check.
+   *
+   * Consistency trade-off vs the default marker mode: invalidation latency for
+   * concurrent requests becomes the purge propagation time (Cloudflare quotes
+   * sub-second "Instant Purge") instead of read-time KV consistency, and a
+   * purge failure leaves L1 stale until TTL — which is why a rejected hook
+   * makes `updateTag()` reject (retry the invalidation; markers and purge are
+   * both idempotent).
+   *
+   * Zone scoping: purge-by-tag clears YOUR zone. workers.dev / pages.dev
+   * previews have an inert Cache API (nothing to purge — the KV tier still
+   * invalidates via markers there); a preview on a SEPARATE zone needs its own
+   * purge credentials.
+   *
+   * @example
+   * ```ts
+   * new CFCacheStore({
+   *   ctx,
+   *   kv: env.CACHE_KV,
+   *   tagPurge: { zoneId: env.CF_ZONE_ID, apiToken: env.CF_PURGE_TOKEN },
+   * })
+   * ```
+   */
+  tagPurge?:
+    | CloudflareZonePurgeOptions
+    | ((cacheTags: string[]) => Promise<void>);
+
   /**
    * Optional expiration (seconds) for tag-invalidation markers in KV. A marker
    * must outlive every entry tagged before the invalidation, so this MUST

package/src/cache/cf/cf-tag-marker-memo.ts

@@ -38,8 +38,11 @@ export const TAG_MARKER_ABSENT = "none";
  * entry A's own KV says is invalidated. Keying by the instance isolates them;
  * two reads through the SAME store still share the memo. A read through one
  * store never populates another's memo, so each store always consults its own KV
- * binding. Markers are read only through isGloballyInvalidated(), which already
- * short-circuits when a store has no KV, so a store without KV never allocates.
+ * binding. Markers are read through isGloballyInvalidated(), which
+ * short-circuits when a store has no KV — and, in purge mode, through
+ * isL1Invalidated(), which consults ONLY this memo on an L1 hit (no KV read),
+ * so a purge-mode store allocates the memo even without KV for same-request
+ * read-your-own-writes after updateTag().
  *
  * Without the memo, isGloballyInvalidated() issues a KV read per tag on every
  * tagged cache read, so a page composed of many segments/items sharing a tag

package/src/cache/cf/cf-zone-purge.ts

@@ -0,0 +1,101 @@
+// ============================================================================
+// Cloudflare zone purge-by-tag helper
+// ============================================================================
+//
+// Ready-made `tagPurge` implementation for CFCacheStoreOptions: POSTs the
+// Cache-Tags handed over by invalidateTags() to the zone purge endpoint.
+// Kept transport-only (no store coupling) so it is unit-testable with an
+// injected fetch and reusable for onRevalidateTag.
+
+/**
+ * Tags per purge_cache API call. Cloudflare's documented purge-by-tag batch
+ * limit has historically been 30 tags per call (the newer all-plans limits
+ * page quotes 100 operations per request); chunking at 30 stays under both.
+ * @internal
+ */
+export const PURGE_TAGS_PER_CALL = 30;
+
+export interface CloudflareZonePurgeOptions {
+  /** Zone to purge (Cloudflare dashboard -> zone overview -> Zone ID). */
+  zoneId: string;
+  /** API token with the `Zone.Cache Purge` permission for that zone. */
+  apiToken: string;
+  /**
+   * API origin override, mainly for tests/proxies.
+   * Defaults to `https://api.cloudflare.com`.
+   */
+  apiBase?: string;
+  /** fetch override, mainly for tests. Defaults to the global fetch. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Create a purge-by-tag function for {@link CFCacheStoreOptions.tagPurge} (or
+ * `onRevalidateTag`). Chunks the tag list under the per-call API limit and
+ * rejects on any non-success response, so a failed purge surfaces through
+ * `updateTag()` instead of silently leaving L1 stale.
+ *
+ * Purge-by-tag is available on ALL Cloudflare plans (since April 2025), but
+ * account-level purge rate limits apply (Free: 5 calls/min) — keep invalidation
+ * tag batches small and low-frequency on lower plans.
+ */
+export function createCloudflareZonePurge(
+  options: CloudflareZonePurgeOptions,
+): (cacheTags: string[]) => Promise<void> {
+  const { zoneId, apiToken } = options;
+  // Fail at construction, not at the first updateTag(): a store wired with an
+  // unset env var would otherwise report the misconfig only when the first
+  // invalidation rejects — long after deploy.
+  if (typeof zoneId !== "string" || zoneId.length === 0) {
+    throw new Error(
+      "[createCloudflareZonePurge] zoneId is required (Cloudflare dashboard " +
+        "-> zone overview -> Zone ID). Check the env var/secret it is read from.",
+    );
+  }
+  if (typeof apiToken !== "string" || apiToken.length === 0) {
+    throw new Error(
+      "[createCloudflareZonePurge] apiToken is required (an API token with " +
+        "the Zone.Cache Purge permission for the zone). Check the secret it " +
+        "is read from.",
+    );
+  }
+  const apiBase = options.apiBase ?? "https://api.cloudflare.com";
+  const fetchImpl = options.fetch ?? fetch;
+  const endpoint = `${apiBase}/client/v4/zones/${zoneId}/purge_cache`;
+
+  return async (cacheTags: string[]): Promise<void> => {
+    for (let i = 0; i < cacheTags.length; i += PURGE_TAGS_PER_CALL) {
+      const chunk = cacheTags.slice(i, i + PURGE_TAGS_PER_CALL);
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ tags: chunk }),
+      });
+      // The API reports failures both via HTTP status and a success flag.
+      // Require an EXPLICIT success: true — an empty body, an HTML error
+      // page, invalid JSON, or `{}` on a 2xx is NOT a confirmed purge, and
+      // purge mode trusts surviving L1 entries on the strength of this call,
+      // so an unconfirmed purge must reject rather than pass silently.
+      const body = (await response.json().catch(() => null)) as {
+        success?: boolean;
+        errors?: { code?: number; message?: string }[];
+      } | null;
+      if (!response.ok || body?.success !== true) {
+        const detail =
+          body?.errors
+            ?.map((e) => `${e.code ?? "?"}: ${e.message ?? "unknown"}`)
+            .join("; ") ??
+          (response.ok
+            ? `HTTP ${response.status} with a missing/invalid success body`
+            : `HTTP ${response.status}`);
+        throw new Error(
+          `[createCloudflareZonePurge] purge_cache failed for ${chunk.length} ` +
+            `tag(s): ${detail}`,
+        );
+      }
+    }
+  };
+}

package/src/cache/cf/index.ts

@@ -17,3 +17,8 @@ export {
   EDGE_READ_TIMEOUT_MS,
   KV_READ_TIMEOUT_MS,
 } from "./cf-cache-store.js";
+
+export {
+  createCloudflareZonePurge,
+  type CloudflareZonePurgeOptions,
+} from "./cf-zone-purge.js";

package/src/cache/handle-snapshot.ts

@@ -83,14 +83,35 @@ export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
 /**
  * Capture handle data for a set of segments from the handle store.
  * Used when caching segments to preserve their handle data.
+ *
+ * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
+ * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
+ * re-run fresh on every HIT, so replaying their captured values would
+ * duplicate the fresh push — and their masked nested promises would stall the
+ * Flight handle encode to its timeout. Threaded as an explicit argument so
+ * every other getDataForSegment consumer (the render-barrier snapshot,
+ * prerender) provably sees every push.
  */
 export function captureHandles(
   segments: ResolvedSegment[],
   handleStore: HandleStore,
+  exclude?: WeakSet<object>,
 ): Record<string, SegmentHandleData> {
   const handles: Record<string, SegmentHandleData> = {};
   for (const seg of segments) {
-    handles[seg.id] = handleStore.getDataForSegment(seg.id);
+    const data = handleStore.getDataForSegment(seg.id);
+    if (!exclude) {
+      handles[seg.id] = data;
+      continue;
+    }
+    const filtered: SegmentHandleData = {};
+    for (const [handleName, values] of Object.entries(data)) {
+      const kept = values.filter(
+        (v) => typeof v !== "object" || v === null || !exclude.has(v),
+      );
+      if (kept.length > 0) filtered[handleName] = kept;
+    }
+    handles[seg.id] = filtered;
   }
   return handles;
 }

package/src/cache/index.ts

@@ -23,6 +23,8 @@ export {
   EDGE_LOOKUP_TIMEOUT_MS,
   EDGE_READ_TIMEOUT_MS,
   KV_READ_TIMEOUT_MS,
+  createCloudflareZonePurge,
+  type CloudflareZonePurgeOptions,
 } from "./cf/index.js";
 
 export {

package/src/cache/memory-segment-store.ts

@@ -30,6 +30,8 @@ const ITEM_CACHE_REGISTRY_KEY = "__rsc_router_item_cache_registry__";
 const SHELL_CACHE_REGISTRY_KEY = "__rsc_router_shell_cache_registry__";
 const TAG_INDEX_REGISTRY_KEY = "__rsc_router_tag_index_registry__";
 const KEY_TAGS_REGISTRY_KEY = "__rsc_router_key_tags_registry__";
+const TAG_INVALIDATED_AT_REGISTRY_KEY =
+  "__rsc_router_tag_invalidated_at_registry__";
 
 /**
  * Get or create a named Map from a globalThis-backed registry.
@@ -186,6 +188,7 @@ const DEFAULT_MAX_ENTRIES = 1000;
 export class MemorySegmentCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  readonly supportsPassiveShellReads: true = true;
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
   private itemCache: Map<string, CachedItemEntry>;
@@ -194,6 +197,12 @@ export class MemorySegmentCacheStore<
   private tagIndex: Map<string, Set<string>>;
   /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
   private keyTags: Map<string, Set<string>>;
+  /**
+   * tag -> epoch ms of its latest invalidateTags() call. Runtime capture races
+   * and immutable build shells are gated by comparing these markers with the
+   * shell generation start. Per-isolate, like every other map here.
+   */
+  private tagInvalidatedAt: Map<string, number>;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -228,6 +237,10 @@ export class MemorySegmentCacheStore<
         KEY_TAGS_REGISTRY_KEY,
         options.name,
       );
+      this.tagInvalidatedAt = getNamedMap<number>(
+        TAG_INVALIDATED_AT_REGISTRY_KEY,
+        options.name,
+      );
     } else {
       this.cache = new Map<string, CachedEntryData>();
       this.responseCache = new Map<string, CachedResponseEntry>();
@@ -235,6 +248,7 @@ export class MemorySegmentCacheStore<
       this.shellCache = new Map<string, CachedShellEntry>();
       this.tagIndex = new Map<string, Set<string>>();
       this.keyTags = new Map<string, Set<string>>();
+      this.tagInvalidatedAt = new Map<string, number>();
     }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
@@ -444,7 +458,14 @@ export class MemorySegmentCacheStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
+  ): Promise<"stored" | "invalidated"> {
+    if (
+      tags &&
+      tags.length > 0 &&
+      this.tagsInvalidatedSince(tags, entry.createdAt)
+    ) {
+      return "invalidated";
+    }
     const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
     const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
@@ -455,10 +476,32 @@ export class MemorySegmentCacheStore<
     if (tags && tags.length > 0) {
       this.registerTags(tags, prefixedKey);
     }
+    return "stored";
+  }
+
+  async isTagsInvalidatedSince(
+    tags: string[],
+    sinceMs: number,
+  ): Promise<boolean> {
+    return this.tagsInvalidatedSince(tags, sinceMs);
+  }
+
+  private tagsInvalidatedSince(tags: string[], sinceMs: number): boolean {
+    for (const tag of tags) {
+      const at = this.tagInvalidatedAt.get(tag);
+      // >= so a same-millisecond invalidation wins (freshness over staleness),
+      // matching the CF marker comparison.
+      if (at !== undefined && at >= sinceMs) return true;
+    }
+    return false;
   }
 
   async invalidateTags(tags: string[]): Promise<void> {
+    const invalidatedAt = Date.now();
     for (const tag of tags) {
+      // Marker first: build-shell entries evict by marker comparison even when
+      // no runtime entry currently carries the tag (tagIndex miss below).
+      this.tagInvalidatedAt.set(tag, invalidatedAt);
       const keys = this.tagIndex.get(tag);
       if (!keys || keys.size === 0) continue;
 

package/src/cache/segment-codec.ts

@@ -11,6 +11,7 @@
 import type { ResolvedSegment } from "../types.js";
 import type { SerializedSegmentData } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+import { segmentFragment } from "../segment-fragments.js";
 import {
   renderToReadableStream,
   createTemporaryReferenceSet,
@@ -206,6 +207,52 @@ export async function serializeSegments(
   );
 }
 
+/**
+ * Build ResolvedSegments that carry the STORED fragment strings verbatim
+ * instead of decoding them (PPR fast-path payload splice, issue #700; see
+ * segment-fragments.ts). The ReactNode fields (component/layout/loading)
+ * become {@link segmentFragment} envelopes the outer Flight render serializes
+ * as a string copy; the CONSUMER (SSR resume + browser hydration) expands them
+ * through its own deserializer. Loader data fields are NOT enveloped — they
+ * are consumer data of any shape (a marker there could collide) and decode
+ * server-side exactly as deserializeSegments does; on the doc/prerender
+ * records this path serves they are absent in practice (loaders are never
+ * cached with the route record).
+ *
+ * The loading "null" sentinel decodes here (not on the consumer): loading:null
+ * must survive as null, and shipping the raw sentinel would change the
+ * deduplicateLoaderSegments loading-presence check.
+ */
+export async function fragmentSegments(
+  data: SerializedSegmentData[],
+): Promise<ResolvedSegment[]> {
+  return Promise.all(
+    data.map(async (item): Promise<ResolvedSegment> => {
+      const loadingIsNullSentinel = item.encodedLoading === "null";
+      const [loaderData, loaderDataPromise] = await Promise.all([
+        rscDeserialize(item.encodedLoaderData),
+        rscDeserialize(item.encodedLoaderDataPromise),
+      ]);
+      return {
+        ...item.metadata,
+        // Envelopes ride ReactNode-typed fields; the consumer expansion pass
+        // (segment-fragments.ts) replaces them before any render reads them.
+        component: segmentFragment(item.encoded) as unknown,
+        layout: item.encodedLayout
+          ? (segmentFragment(item.encodedLayout) as unknown)
+          : undefined,
+        loading: loadingIsNullSentinel
+          ? null
+          : item.encodedLoading !== undefined
+            ? (segmentFragment(item.encodedLoading) as unknown)
+            : undefined,
+        loaderData,
+        loaderDataPromise,
+      } as ResolvedSegment;
+    }),
+  );
+}
+
 /**
  * Deserialize segments from storage.
  * Reconstructs ResolvedSegment objects from RSC-serialized data.