@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/src/cache/cache-scope.ts

@@ -18,7 +18,13 @@ import {
 } from "../server/request-context.js";
 import { recordRequestTags } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
-import { serializeSegments, deserializeSegments } from "./segment-codec.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,
@@ -28,6 +34,7 @@ import {
 import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
+  isFiniteNonNegativeSeconds,
   resolveCacheKey,
   resolveCacheStore,
   resolveTagsOption,
@@ -48,6 +55,36 @@ function debugCacheLog(message: string): void {
   }
 }
 
+/**
+ * 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 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;
+}
+
+/** 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;
+}
+
 function getCacheKeyBase(
   host: string,
   pathname: string,
@@ -124,20 +161,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
@@ -145,19 +188,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);
   }
 
   /**
@@ -231,10 +277,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) {
@@ -250,6 +302,7 @@ export class CacheScope {
       // 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(
@@ -294,7 +347,13 @@ export class CacheScope {
 
       return { segments, shouldRevalidate };
     } catch (error) {
-      reportCacheError(error, "cache-read", `[CacheScope] lookup ${key}`);
+      // 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;
     }
   }
@@ -420,6 +479,7 @@ export class CacheScope {
         // 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),

package/src/cache/cache-tag.ts

@@ -19,8 +19,13 @@ import {
 const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
 
 export function normalizeTag(tag: string): string | null {
-  if (!tag || !tag.trim()) return null;
-  return tag;
+  // 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[] {

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;