@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/cache/cache-scope.ts

@@ -16,14 +16,38 @@ import {
   getRequestContext,
   _getRequestContext,
 } from "../server/request-context.js";
-import { serializeSegments, deserializeSegments } from "./segment-codec.js";
-import { captureHandles, restoreHandles } from "./handle-snapshot.js";
-import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
+import { recordRequestTags } from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
+// segment-codec is the only module on cache-scope's import graph that eagerly
+// pulls @vitejs/plugin-rsc (a virtual: module the plain node/vitest runner cannot
+// resolve). It is imported LAZILY at the two call sites below (deserializeSegments
+// in lookupRoute, serializeSegments in cacheRoute) so that requiring cache-scope —
+// e.g. dispatch's lazy `import("../cache/cache-scope.js")` for the response-route
+// cache path — does not crash a consumer test that never mocks plugin-rsc. Behavior
+// is unchanged: both methods are async and already awaited the codec.
+import {
+  captureHandles,
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
+import { cacheKeyBase } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
+  isFiniteNonNegativeSeconds,
   resolveCacheKey,
   resolveCacheStore,
+  resolveTagsOption,
 } from "./cache-policy.js";
+import type { RequestContext } from "../server/request-context.js";
+
+export function resolveCacheTags(
+  config: PartialCacheOptions | false,
+  ctx: RequestContext | undefined,
+): string[] | undefined {
+  if (config === false) return undefined;
+  return resolveTagsOption(config.tags, ctx, "CacheScope");
+}
 
 function debugCacheLog(message: string): void {
   if (INTERNAL_RANGO_DEBUG) {
@@ -31,42 +55,36 @@ function debugCacheLog(message: string): void {
   }
 }
 
-// ============================================================================
-// Key Generation (internal)
-// ============================================================================
-
 /**
- * Generate cache key base from host, pathname, route params, and search params.
- * Host is included to prevent cross-host cache collisions on shared stores.
- * Route params and search params are sorted alphabetically for deterministic keys.
- * Internal _rsc* and __* query params are excluded.
- * @internal
+ * A finite, non-negative seconds value? A NaN/Infinity ttl/swr (from a bad
+ * cache() option or store defaults) flows into computeExpiration ->
+ * staleAt/expiresAt = NaN, where every `now > NaN` is false so the entry never
+ * evicts and is served fresh forever; a negative value makes every read a miss.
+ * Mirror profile-registry.ts's Number.isFinite + >= 0 check, but the callers
+ * degrade to a default (warning in dev) rather than throw — this runs on the
+ * foreground render.
  */
-function getCacheKeyBase(
-  host: string,
-  pathname: string,
-  params?: Record<string, string>,
-  searchParams?: URLSearchParams,
-): string {
-  const paramStr = sortedRouteParams(params);
-  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
+function isValidCacheSeconds(value: number, label: string): boolean {
+  if (isFiniteNonNegativeSeconds(value)) return true;
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[CacheScope] Invalid ${label} ${value}; falling back to default`,
+    );
+  }
+  return false;
+}
 
-  let key = `${host}${pathname}`;
-  if (paramStr) key += `:${paramStr}`;
-  if (searchStr) key += `?${searchStr}`;
-  return key;
+/** Coerce a resolved ttl to a finite, non-negative number (default on invalid). */
+function validatedTtl(value: number): number {
+  return isValidCacheSeconds(value, "ttl") ? value : DEFAULT_ROUTE_TTL;
+}
+
+/** Coerce a resolved swr to a finite, non-negative number, or undefined (no SWR window). */
+function validatedSwr(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  return isValidCacheSeconds(value, "swr") ? value : undefined;
 }
 
-/**
- * Generate default cache key for a route request.
- * Includes pathname, route params, and user-facing search params for
- * correct scoping. Internal _rsc* params are excluded.
- * Includes request type prefix since they produce different segment sets:
- * - doc: document requests (full page load)
- * - partial: navigation requests (client-side navigation)
- * - intercept: intercept navigation (modal/overlay routes)
- * @internal
- */
 function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,
@@ -80,7 +98,7 @@ function getDefaultRouteCacheKey(
   // Intercept navigations get their own cache namespace
   const prefix = isIntercept ? "intercept" : isPartial ? "partial" : "doc";
 
-  return `${prefix}:${getCacheKeyBase(host, pathname, params, searchParams)}`;
+  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params)}`;
 }
 
 // ============================================================================
@@ -128,20 +146,26 @@ export class CacheScope {
   }
 
   /**
-   * Get effective TTL from config or store defaults
+   * Get effective TTL from config or store defaults.
+   *
+   * Unlike profile-registry.ts (which fails fast at config time), the render
+   * path must DEGRADE: a non-finite/negative ttl (NaN/Infinity from a bad
+   * defaults config) would make computeExpiration produce NaN deadlines so the
+   * entry never evicts, or a guaranteed miss for a negative value. Fall back to
+   * DEFAULT_ROUTE_TTL instead of throwing in the foreground render.
    */
   get ttl(): number {
     if (this.config === false) return 0;
 
     // Explicit TTL in cache() options
     if (this.config.ttl !== undefined) {
-      return this.config.ttl;
+      return validatedTtl(this.config.ttl);
     }
 
     // Fall back to store defaults (explicit store first, then app-level)
     const store = this.getStore();
     if (store?.defaults?.ttl !== undefined) {
-      return store.defaults.ttl;
+      return validatedTtl(store.defaults.ttl);
     }
 
     // Hardcoded fallback
@@ -149,19 +173,22 @@ export class CacheScope {
   }
 
   /**
-   * Get SWR window from config or store defaults
+   * Get SWR window from config or store defaults.
+   *
+   * A non-finite/negative swr is degraded to undefined (no SWR window) rather
+   * than fed into expiry math; see the ttl getter for the rationale.
    */
   get swr(): number | undefined {
     if (this.config === false) return undefined;
 
     // Explicit SWR in cache() options
     if (this.config.swr !== undefined) {
-      return this.config.swr;
+      return validatedSwr(this.config.swr);
     }
 
     // Fall back to store defaults
     const store = this.getStore();
-    return store?.defaults?.swr;
+    return validatedSwr(store?.defaults?.swr);
   }
 
   /**
@@ -235,10 +262,16 @@ export class CacheScope {
     const store = this.getStore();
     if (!store) return null;
 
-    // Resolve cache key (may use custom key functions)
-    const key = await this.resolveKey(pathname, params, isIntercept);
-
+    // Resolve cache key INSIDE the try so a throwing consumer key() (or a
+    // store.keyGenerator) degrades to a cache miss (return null -> render
+    // uncached) instead of crashing the foreground render. resolveCacheKey
+    // itself keeps its hard-fail/no-fallback-to-default contract (a throw must
+    // not silently collide onto the default slot); the graceful degradation
+    // happens here, where a miss is a safe outcome.
+    let key: string | undefined;
     try {
+      key = await this.resolveKey(pathname, params, isIntercept);
+
       const result = await store.get(key);
 
       if (!result) {
@@ -248,13 +281,44 @@ export class CacheScope {
 
       const { data: cached, shouldRevalidate } = result;
 
-      // Deserialize segments
-      const segments = await deserializeSegments(cached.segments);
+      // Deserialize segments. A failure means the cached segments are corrupt/
+      // partial: evict the entry (self-heal - the re-render re-caches under the
+      // same key) and report it as corruption, distinct from a transient infra
+      // error (handled by the outer catch).
+      let segments: ResolvedSegment[];
+      try {
+        const { deserializeSegments } = await import("./segment-codec.js");
+        segments = await deserializeSegments(cached.segments);
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[CacheScope] ${key}: corrupt cached segments, evicting`,
+        );
+        await store
+          .delete(key)
+          .catch((e) =>
+            reportCacheError(e, "cache-delete", `[CacheScope] ${key}: evict`),
+          );
+        return null;
+      }
+
+      // A hit serves content that was tagged at write time, so the document
+      // tag union must include this entry's tags for updateTag()/revalidateTag()
+      // to invalidate any full-page entry built on top of it. The write path
+      // records via cacheRoute (resolveCacheTags); the hit path records here.
+      recordRequestTags(cached.tags);
 
-      // Replay handle data
+      // Replay handle data. An empty string means the route pushed no handles —
+      // skip the decode entirely (the common case). Otherwise decode the
+      // Flight-encoded blob; a decode failure skips handle restore but keeps the
+      // valid cached segments.
       const handleStore = _getRequestContext()?._handleStore;
-      if (handleStore) {
-        restoreHandles(cached.handles, handleStore);
+      if (handleStore && cached.handles) {
+        const handlesRecord = await decodeHandles(cached.handles);
+        if (handlesRecord) {
+          restoreHandles(handlesRecord, handleStore);
+        }
       }
 
       if (INTERNAL_RANGO_DEBUG) {
@@ -268,11 +332,37 @@ export class CacheScope {
 
       return { segments, shouldRevalidate };
     } catch (error) {
-      console.error(`[CacheScope] Failed to lookup ${key}:`, error);
+      // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
+      // (resolveKey). Either way degrade to a cache miss so the render proceeds.
+      reportCacheError(
+        error,
+        "cache-read",
+        `[CacheScope] lookup ${key ?? "(key resolution failed)"}`,
+      );
       return null;
     }
   }
 
+  /**
+   * Record this scope's segment-DSL cache({ tags }) into the request tag union
+   * synchronously, under the same gate cacheRoute() uses for a write.
+   *
+   * cacheRoute() already records these tags, but it is invoked inside
+   * requestCtx.waitUntil() by the cache-store middleware (and the proactive path
+   * re-resolves the whole tree before calling it), so its recording is deferred
+   * and RACES the document cache's post-body-drain snapshot of _requestTags. On a
+   * first-write (segment-cache miss) the document tag union could miss these
+   * tags, and updateTag()/revalidateTag() would then fail to invalidate the
+   * cached document until a later write reseeded it. Calling this synchronously
+   * in the request pipeline (before the snapshot) closes that window. Idempotent
+   * (the tag union is a Set), so the duplicate record in cacheRoute is harmless.
+   */
+  recordTags(requestCtx: RequestContext | undefined): void {
+    if (!this.enabled) return;
+    if (!this.conditionAllows("write")) return;
+    recordRequestTags(resolveCacheTags(this.config, requestCtx), requestCtx);
+  }
+
   /**
    * Cache all segments for a route (non-blocking via waitUntil)
    * Single cache entry per route request.
@@ -311,6 +401,10 @@ export class CacheScope {
     // Resolve cache key early (while request context is available)
     const key = await this.resolveKey(pathname, params, isIntercept);
 
+    // Resolve tags early (while request context is available, before waitUntil)
+    const tags = resolveCacheTags(this.config, requestCtx);
+    recordRequestTags(tags, requestCtx);
+
     // Check if this is a partial request (navigation) vs document request
     const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
 
@@ -367,13 +461,20 @@ export class CacheScope {
           );
         }
 
-        // Serialize non-loader segments only
-        const serializedSegments = await serializeSegments(nonLoaderSegments);
+        // Serialize segments and Flight-encode handles in parallel. Handles go
+        // through the codec (not raw into the entry) so Promise/ReactNode handle
+        // values survive a JSON-serializing store — see encodeHandles.
+        const { serializeSegments } = await import("./segment-codec.js");
+        const [serializedSegments, encodedHandles] = await Promise.all([
+          serializeSegments(nonLoaderSegments),
+          encodeHandles(handles),
+        ]);
 
         const data: CachedEntryData = {
           segments: serializedSegments,
-          handles,
+          handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
+          tags,
         };
 
         if (INTERNAL_RANGO_DEBUG) {
@@ -391,7 +492,11 @@ export class CacheScope {
           );
         }
       } catch (error) {
-        console.error(`[CacheScope] Failed to cache ${key}:`, error);
+        reportCacheError(
+          error,
+          "cache-write",
+          `[CacheScope] Failed to cache ${key}`,
+        );
       }
     });
   }

package/src/cache/cache-tag.ts

@@ -0,0 +1,149 @@
+/**
+ * Cache Tag API
+ *
+ * Provides cacheTag() for tagging cached entries at runtime inside "use cache"
+ * functions. Tags are scoped via AsyncLocalStorage; calling cacheTag() outside
+ * a "use cache" execution throws.
+ *
+ * The runtime (cache-runtime.ts) wraps "use cache" execution in
+ * runWithCacheTagScope(), collects the runtime tags, and merges them with the
+ * profile/DSL tags before storing.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+
+const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
+
+export function normalizeTag(tag: string): string | null {
+  // Trim and return the canonical (trimmed) form, not the raw tag. Both the
+  // write path (cacheTag) and the invalidate path (updateTag/revalidateTag)
+  // route through here, and matching is exact-string: returning the untrimmed
+  // tag made cacheTag(" products ") and updateTag("products") two different
+  // logical tags, a silent failure-to-invalidate (stale data served forever).
+  const trimmed = tag?.trim();
+  return trimmed ? trimmed : null;
+}
+
+export function normalizeTags(tags: Iterable<string>): string[] {
+  const out: string[] = [];
+  for (const tag of tags) {
+    const normalized = normalizeTag(tag);
+    if (normalized !== null) out.push(normalized);
+  }
+  return out;
+}
+
+/**
+ * Tag content for later invalidation via updateTag() / revalidateTag().
+ *
+ * cacheTag() serves two forms depending on what is active when it runs:
+ *
+ * 1. Inside a "use cache" function — the DEFAULT. The tags go to the current
+ *    cache entry; `revalidateTag(tag)` drops that entry. Tags are additive
+ *    (multiple calls accumulate), and normalizeTag() is the single chokepoint so
+ *    a padded write matches an unpadded invalidate.
+ *
+ * 2. Render-callable (#648) — no "use cache" scope active, but a request context
+ *    is present. The tags record onto the request's DOCUMENT artifact
+ *    (ctx._requestTags) instead of throwing. The collection layers already exist:
+ *    PPR shell capture unions _requestTags into the shell entry, the document
+ *    cache tags the full-page entry with it, and prerender build contexts seed
+ *    their own set — so a server component that renders into a shell makes
+ *    `revalidateTag("campaign:spring")` evict that shell with ZERO cache()/"use
+ *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
+ *    execution-PRESERVING (everything still runs underneath; only document bytes
+ *    are shortcut), so its tags ride this existing instrument rather than a
+ *    first-class ppr key/tag API. The shell-expiry invariant holds by
+ *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
+ *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
+ *    never execute during capture, so nothing under a hole can tag the shell).
+ *
+ * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
+ * level, not the segment (only the "use cache" runtime enters the tag scope) — a
+ * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ * dropped in both forms (the render-callable form silently, via normalizeTags in
+ * recordRequestTags; the scope form with a dev warning).
+ *
+ * With neither a scope nor a request context, cacheTag() throws.
+ *
+ * @example
+ * ```typescript
+ * // Form 1 — inside "use cache":
+ * async function getProduct(ctx) {
+ *   "use cache";
+ *   cacheTag(`product:${ctx.params.id}`, "products");
+ *   return db.getProduct(ctx.params.id);
+ * }
+ *
+ * // Form 2 — render-callable, tags the shell/document from a server component:
+ * function CampaignBanner() {
+ *   cacheTag("campaign:spring");
+ *   return <aside>Spring sale</aside>;
+ * }
+ * ```
+ */
+export function cacheTag(...tags: string[]): void {
+  const store = cacheTagStorage.getStore();
+  if (store) {
+    // Form 1: "use cache" scope wins — tag the cache entry (unchanged).
+    for (const tag of tags) {
+      const normalized = normalizeTag(tag);
+      if (normalized === null) {
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(`[cacheTag] Ignoring empty or whitespace-only tag.`);
+        }
+        continue;
+      }
+      store.add(normalized);
+    }
+    return;
+  }
+
+  const reqCtx = _getRequestContext();
+  if (reqCtx?._requestTags) {
+    // Form 2: render-callable — tag the request's document artifact. See the
+    // JSDoc above for the composition doctrine and the baked/hole invariant.
+    recordRequestTags(tags, reqCtx);
+    return;
+  }
+
+  throw new Error(
+    'cacheTag() must be called inside a "use cache" function or during a request render.',
+  );
+}
+
+export function recordRequestTags(
+  tags: Iterable<string> | undefined,
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  if (!tags) return;
+  const set = ctx?._requestTags;
+  if (!set) return;
+  for (const tag of tags) {
+    const normalized = normalizeTag(tag);
+    if (normalized !== null) set.add(normalized);
+  }
+}
+
+/**
+ * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
+ * accumulate into the returned Set.
+ *
+ * The returned Set is the LIVE reference - the caller must await `result`
+ * before reading `tags`, because an async cached function may call cacheTag()
+ * after an await boundary.
+ *
+ * @internal Used by cache-runtime.ts to wrap "use cache" execution.
+ */
+export function runWithCacheTagScope<T>(fn: () => T): {
+  result: T;
+  tags: Set<string>;
+} {
+  const tagSet = new Set<string>();
+  const result = cacheTagStorage.run(tagSet, fn);
+  return { result, tags: tagSet };
+}

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

@@ -0,0 +1,33 @@
+// ============================================================================
+// Base64 Helpers (binary-safe response body encoding for KV)
+// ============================================================================
+
+// Chunk size for String.fromCharCode.apply: large enough to amortize the call
+// overhead, small enough to stay well under the JS engine argument-count limit
+// (~65k). 8192 turns a per-byte concat loop into O(n/8192) apply calls.
+const FROM_CHARCODE_CHUNK = 8192;
+
+/** Encode ArrayBuffer to base64 string. */
+export function bufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  // Build the binary (latin1) string in fixed-size chunks instead of one
+  // String.fromCharCode per byte. Identical output to the per-byte loop (each
+  // byte maps to the same code unit); just far fewer string concatenations for
+  // large document payloads.
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += FROM_CHARCODE_CHUNK) {
+    const chunk = bytes.subarray(i, i + FROM_CHARCODE_CHUNK);
+    binary += String.fromCharCode.apply(null, chunk as unknown as number[]);
+  }
+  return btoa(binary);
+}
+
+/** Decode base64 string to ArrayBuffer. */
+export function base64ToBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}

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

@@ -0,0 +1,127 @@
+// ============================================================================
+// Constants
+// ============================================================================
+//
+// Header names, KV prefixes, and timeout/interval defaults for the CF cache
+// store. Extracted from cf-cache-store.ts so the constants can be shared by the
+// store and its sibling collaborator modules without a circular import back to
+// the class. The public ones (CACHE_*_HEADER, TAG_MARKER_PREFIX,
+// MAX_REVALIDATION_INTERVAL, EDGE_*_TIMEOUT_MS, KV_READ_TIMEOUT_MS) are
+// re-exported from cf-cache-store.ts so existing import paths still resolve.
+
+/** Header storing timestamp when entry becomes stale */
+export const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
+
+/** Header storing cache status: HIT | REVALIDATING */
+export const CACHE_STATUS_HEADER = "x-edge-cache-status";
+
+/**
+ * Header storing this entry's cache tags as a JSON array. JSON-encoded (not the
+ * comma-delimited CF `Cache-Tag` format) so tags containing commas round-trip
+ * safely; the read paths parse this to run the tag-invalidation check.
+ */
+export const CACHE_TAGS_HEADER = "x-edge-cache-tags";
+
+/** Header storing the ms-epoch timestamp when this entry's tags were attached. */
+export const CACHE_TAGGED_AT_HEADER = "x-edge-cache-tagged-at";
+
+/**
+ * KV key prefix for tag-invalidation markers. A marker stores the ms-epoch
+ * timestamp of the most recent invalidation of a tag; reads treat any entry
+ * whose taggedAt is older than its tags' latest marker as invalidated. Markers
+ * live in the SAME KV namespace as the cached entries - there is no separate
+ * tag-invalidation store.
+ */
+export const TAG_MARKER_PREFIX = "__tag__/";
+
+/**
+ * Header storing the epoch-ms timestamp when an entry was marked REVALIDATING.
+ * The SWR thundering-herd guard reads this to decide whether the in-flight
+ * revalidation is still recent. It replaces a prior reliance on the HTTP `Age`
+ * header: CF's Cache API does not populate `Age` reliably per-colo (and our own
+ * unit MockCache never set it), so an absent `Age` defaulted to 0 and made every
+ * REVALIDATING entry look "just revalidated" forever -- a dropped/never-finished
+ * background revalidation could then pin an entry stale until hard expiry. An
+ * explicit timestamp we write ourselves (same pattern as CACHE_STALE_AT_HEADER)
+ * is reliable and lets the MAX_REVALIDATION_INTERVAL re-arm actually fire.
+ */
+export const CACHE_REVALIDATING_AT_HEADER = "x-edge-cache-revalidating-at";
+
+/**
+ * Header storing the absolute epoch-ms hard-expiry deadline (staleAt +
+ * swrWindow*1000) of an L1 entry. The stale-path REVALIDATING re-put reads this
+ * to recompute a SHRINKING Cache-Control max-age instead of copying set()'s
+ * original full-window max-age. Without it, every MAX_REVALIDATION_INTERVAL
+ * re-arm re-puts the full window and restarts CF's retention clock, pinning a
+ * perpetually-stale entry (one whose background revalidation keeps failing) past
+ * its intended hard-expiry indefinitely. Mirrors the KVSegmentEnvelope `e`
+ * field and the remaining-ttl math in promoteSegmentToL1/promoteItemToL1.
+ * @internal
+ */
+export const CACHE_EXPIRES_AT_HEADER = "x-edge-cache-expires-at";
+
+/**
+ * Header stashing the route author's original Cache-Control on L1 document
+ * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
+ * `max-age` so the CF Cache API retains the entry across the whole SWR window;
+ * getResponse restores this original value before serving so the client and any
+ * upstream CDN see the author's intended directive, not the internal edge TTL.
+ */
+export const CACHE_ORIG_CC_HEADER = "x-edge-cache-orig-cc";
+
+/**
+ * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
+ * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
+ * @internal
+ */
+export const MAX_REVALIDATION_INTERVAL = 30;
+
+/**
+ * Maximum time (ms) to wait for an L1 edge cache (CF Cache API) read before
+ * giving up and treating it as a miss. The Cache API is normally sub-millisecond
+ * per-colo, so a slow `match` signals a degraded colo; we don't want it adding
+ * latency to the request. On timeout the lookup is abandoned, a warning is
+ * logged, and the read falls through to its normal miss path (L2/KV or render).
+ *
+ * This is the default; override per store via
+ * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ */
+export const EDGE_LOOKUP_TIMEOUT_MS = 10;
+
+/**
+ * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read
+ * (response.json()) before treating the read as a miss.
+ *
+ * This is separate from {@link EDGE_LOOKUP_TIMEOUT_MS} on purpose. CF's Cache
+ * API resolves `match()` with a lazily-streamed body, so a fast `match` can be
+ * followed by a multi-second stall while the body bytes are fetched -- the
+ * latency tail lives here, after the match budget has already passed. The
+ * default bounds that tail aggressively: a healthy per-colo body read (fetch +
+ * JSON parse) settles in low single-digit milliseconds, so 20ms clears a
+ * healthy read while still failing fast to L2/KV (or render) on a degraded colo
+ * instead of pinning the request behind a seconds-long read. Raise it per store
+ * if large Flight payloads legitimately need longer.
+ *
+ * Override per store via `CFCacheStoreOptions.edgeReadTimeoutMs` (<= 0 disables).
+ */
+export const EDGE_READ_TIMEOUT_MS = 20;
+
+/**
+ * Maximum time (ms) to wait for an L2 (KV) read (`kv.get(key, {type:"json"})`)
+ * before treating it as a miss. Unlike the L1 budgets, KV is a GLOBAL store: the
+ * file header documents ~50ms healthy reads, and a degraded namespace can tail
+ * to seconds. KV is the LAST cache tier before a full render, so an unbounded
+ * read here pins the whole request behind a degraded global lookup.
+ *
+ * The default (170ms) sits a few multiples above the documented ~50ms healthy
+ * read, leaving headroom for legitimate latency tails (larger payloads,
+ * far-from-colo regions) so a healthy-but-slow read does not false-miss into a
+ * render, while still abandoning a genuinely degraded namespace well before its
+ * multi-second tail can pin the request. A deployment with a tighter SLA can
+ * lower it, and one whose healthy p99 runs higher should raise it: measure the
+ * KV read p99 (Workers Analytics) and add margin. It is a degradation
+ * guard-rail, not a tuning lever for "slow KV is normal here".
+ *
+ * Override per store via `CFCacheStoreOptions.kvReadTimeoutMs` (<= 0 disables).
+ */
+export const KV_READ_TIMEOUT_MS = 170;