@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

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

@@ -12,19 +12,24 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
-  SegmentHandleData,
+  ShellCacheEntry,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import { isPerClientSignalHeader } from "../browser/cookie-name.js";
 import {
   resolveTtl,
   resolveSwrWindow,
   computeExpiration,
   DEFAULT_FUNCTION_TTL,
 } from "./cache-policy.js";
+import { reportCacheError } from "./cache-error.js";
 
 const CACHE_REGISTRY_KEY = "__rsc_router_segment_cache_registry__";
 const RESPONSE_CACHE_REGISTRY_KEY = "__rsc_router_response_cache_registry__";
 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__";
 
 /**
  * Get or create a named Map from a globalThis-backed registry.
@@ -56,9 +61,17 @@ interface CachedResponseEntry {
 
 interface CachedItemEntry {
   value: string;
-  handles?: Record<string, SegmentHandleData>;
+  handles?: string;
   expiresAt: number;
   staleAt: number;
+  tags?: string[];
+}
+
+interface CachedShellEntry {
+  entry: ShellCacheEntry;
+  expiresAt: number;
+  staleAt: number;
+  tags?: string[];
 }
 
 /**
@@ -73,6 +86,11 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
    * When omitted, the store uses a plain instance-level Map with no
    * globalThis sharing, which is the safest default for isolation.
    *
+   * Caveat: two instances constructed with the SAME name share all backing maps
+   * (data + tag index), but each keeps its OWN `defaults` and `keyGenerator` from
+   * its options - those are not shared. Use one instance per name, or keep the
+   * options identical, to avoid surprising divergence.
+   *
    * @example
    * ```typescript
    * // Two named stores are isolated from each other
@@ -112,8 +130,25 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
     ctx: RequestContext<TEnv>,
     defaultKey: string,
   ) => string | Promise<string>;
+
+  /**
+   * Maximum number of entries kept per internal family (segment, response,
+   * item, shell). On insert, once a family reaches the cap its oldest entry is
+   * evicted FIFO (insertion order) and its tag-index entries are cleaned up, so
+   * a long-lived instance can't grow without bound. Lazy TTL expiry still runs
+   * independently. Defaults to DEFAULT_MAX_ENTRIES (1000).
+   *
+   * @example
+   * ```typescript
+   * const store = new MemorySegmentCacheStore({ maxEntries: 500 });
+   * ```
+   */
+  maxEntries?: number;
 }
 
+/** Default per-family entry cap for MemorySegmentCacheStore (FIFO eviction). */
+const DEFAULT_MAX_ENTRIES = 1000;
+
 /**
  * In-memory segment cache store.
  *
@@ -121,6 +156,17 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * For production with multiple instances, use a distributed store
  * like Cloudflare KV or Redis.
  *
+ * Each family is size-capped at `maxEntries` (default 1000) with FIFO eviction
+ * on insert, so a long-lived instance can't grow unbounded; TTL expiry stays
+ * lazy on top of that.
+ *
+ * Tag-index cleanup is lazy, mirroring the data maps: a tagged entry that
+ * expires but is never re-read or invalidated leaves its forward+reverse index
+ * entries resident until the key is reused, invalidated, or FIFO-evicted. This
+ * is bounded by the distinct-tag count and acceptable for a dev/single-instance
+ * store. FIFO eviction unregisters the evicted key's tags, so the tag maps do
+ * not outlive the capped data maps.
+ *
  * @example
  * ```typescript
  * // Basic usage
@@ -143,16 +189,21 @@ export class MemorySegmentCacheStore<
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
   private itemCache: Map<string, CachedItemEntry>;
+  private shellCache: Map<string, CachedShellEntry>;
+  /** tag -> set of prefixed cache keys (seg:key, res:key, item:key, shell:key) */
+  private tagIndex: Map<string, Set<string>>;
+  /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
+  private keyTags: Map<string, Set<string>>;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
     defaultKey: string,
   ) => string | Promise<string>;
+  /** Per-family FIFO entry cap. */
+  readonly maxEntries: number;
 
   constructor(options?: MemorySegmentCacheStoreOptions<TEnv>) {
     if (options?.name != null) {
-      // Named stores use the globalThis registry so data survives HMR.
-      // Each name gets its own isolated Map.
       this.cache = getNamedMap<CachedEntryData>(
         CACHE_REGISTRY_KEY,
         options.name,
@@ -165,14 +216,50 @@ export class MemorySegmentCacheStore<
         ITEM_CACHE_REGISTRY_KEY,
         options.name,
       );
+      this.shellCache = getNamedMap<CachedShellEntry>(
+        SHELL_CACHE_REGISTRY_KEY,
+        options.name,
+      );
+      this.tagIndex = getNamedMap<Set<string>>(
+        TAG_INDEX_REGISTRY_KEY,
+        options.name,
+      );
+      this.keyTags = getNamedMap<Set<string>>(
+        KEY_TAGS_REGISTRY_KEY,
+        options.name,
+      );
     } else {
-      // Unnamed stores get a plain instance-level Map (no globalThis sharing).
       this.cache = new Map<string, CachedEntryData>();
       this.responseCache = new Map<string, CachedResponseEntry>();
       this.itemCache = new Map<string, CachedItemEntry>();
+      this.shellCache = new Map<string, CachedShellEntry>();
+      this.tagIndex = new Map<string, Set<string>>();
+      this.keyTags = new Map<string, Set<string>>();
     }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
+    this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  }
+
+  /**
+   * FIFO cap enforcement, called before inserting `incomingKey` into `map`.
+   * When the key is new and the family is at capacity, the oldest entries are
+   * evicted in insertion order and their tag-index entries unregistered (so the
+   * tag maps don't outlive the capped data map). Overwriting an existing key
+   * grows nothing, so it is a no-op.
+   */
+  private evictIfNeeded<V>(
+    map: Map<string, V>,
+    incomingKey: string,
+    prefix: string,
+  ): void {
+    if (map.has(incomingKey)) return;
+    while (map.size >= this.maxEntries) {
+      const oldest = map.keys().next().value;
+      if (oldest === undefined) break;
+      map.delete(oldest);
+      this.unregisterTags(`${prefix}:${oldest}`);
+    }
   }
 
   async get(key: string): Promise<CacheGetResult | null> {
@@ -184,6 +271,7 @@ export class MemorySegmentCacheStore<
 
     // Check expiration
     if (Date.now() > cached.expiresAt) {
+      this.unregisterTags(`seg:${key}`);
       this.cache.delete(key);
       return null;
     }
@@ -198,16 +286,21 @@ export class MemorySegmentCacheStore<
     ttl: number,
     _swr?: number,
   ): Promise<void> {
-    // Note: Memory store doesn't implement SWR - entries just expire at TTL
-    // For SWR support, use CFCacheStore or similar distributed cache
     const entry: CachedEntryData = {
       ...data,
       expiresAt: Date.now() + ttl * 1000,
     };
+    const prefixedKey = `seg:${key}`;
+    this.unregisterTags(prefixedKey);
+    this.evictIfNeeded(this.cache, key, "seg");
     this.cache.set(key, entry);
+    if (data.tags && data.tags.length > 0) {
+      this.registerTags(data.tags, prefixedKey);
+    }
   }
 
   async delete(key: string): Promise<boolean> {
+    this.unregisterTags(`seg:${key}`);
     return this.cache.delete(key);
   }
 
@@ -215,6 +308,9 @@ export class MemorySegmentCacheStore<
     this.cache.clear();
     this.responseCache.clear();
     this.itemCache.clear();
+    this.shellCache.clear();
+    this.tagIndex.clear();
+    this.keyTags.clear();
   }
 
   async getResponse(
@@ -224,6 +320,7 @@ export class MemorySegmentCacheStore<
     if (!cached) return null;
 
     if (Date.now() > cached.expiresAt) {
+      this.unregisterTags(`res:${key}`);
       this.responseCache.delete(key);
       return null;
     }
@@ -244,23 +341,39 @@ export class MemorySegmentCacheStore<
     response: Response,
     ttl: number,
     swr?: number,
+    tags?: string[],
   ): Promise<void> {
-    const body = await response.clone().arrayBuffer();
-    const headers: [string, string][] = [];
-    response.headers.forEach((value, name) => {
-      headers.push([name, value]);
-    });
+    try {
+      const body = await response.clone().arrayBuffer();
+      const headers: [string, string][] = [];
+      response.headers.forEach((value, name) => {
+        if (isPerClientSignalHeader(name)) return;
+        headers.push([name, value]);
+      });
 
-    const swrWindow = resolveSwrWindow(swr, this.defaults);
-    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+      const swrWindow = resolveSwrWindow(swr, this.defaults);
+      const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
 
-    this.responseCache.set(key, {
-      body,
-      status: response.status,
-      headers,
-      expiresAt,
-      staleAt,
-    });
+      const prefixedKey = `res:${key}`;
+      this.unregisterTags(prefixedKey);
+      this.evictIfNeeded(this.responseCache, key, "res");
+      this.responseCache.set(key, {
+        body,
+        status: response.status,
+        headers,
+        expiresAt,
+        staleAt,
+      });
+      if (tags && tags.length > 0) {
+        this.registerTags(tags, prefixedKey);
+      }
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-write",
+        "[MemorySegmentCacheStore] putResponse",
+      );
+    }
   }
 
   async getItem(key: string): Promise<CacheItemResult | null> {
@@ -269,6 +382,7 @@ export class MemorySegmentCacheStore<
 
     const now = Date.now();
     if (now > cached.expiresAt) {
+      this.unregisterTags(`item:${key}`);
       this.itemCache.delete(key);
       return null;
     }
@@ -278,6 +392,7 @@ export class MemorySegmentCacheStore<
       value: cached.value,
       handles: cached.handles,
       shouldRevalidate: isStale,
+      tags: cached.tags,
     };
   }
 
@@ -289,18 +404,118 @@ export class MemorySegmentCacheStore<
     const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
     const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+    const prefixedKey = `item:${key}`;
+    this.unregisterTags(prefixedKey);
+    this.evictIfNeeded(this.itemCache, key, "item");
     this.itemCache.set(key, {
       value,
       handles: options?.handles,
       expiresAt,
       staleAt,
+      tags: options?.tags,
     });
+    if (options?.tags && options.tags.length > 0) {
+      this.registerTags(options.tags, prefixedKey);
+    }
+  }
+
+  async getShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    const cached = this.shellCache.get(key);
+    if (!cached) return null;
+
+    const now = Date.now();
+    if (now > cached.expiresAt) {
+      this.unregisterTags(`shell:${key}`);
+      this.shellCache.delete(key);
+      return null;
+    }
+
+    // SWR mirrors the item family: stale within the swr window still serves, and
+    // signals shouldRevalidate so the middleware schedules a background recapture.
+    const shouldRevalidate = cached.staleAt > 0 && now > cached.staleAt;
+    return { entry: cached.entry, shouldRevalidate };
+  }
+
+  async putShell(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void> {
+    const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
+    const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
+    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+    const prefixedKey = `shell:${key}`;
+    this.unregisterTags(prefixedKey);
+    this.evictIfNeeded(this.shellCache, key, "shell");
+    this.shellCache.set(key, { entry, expiresAt, staleAt, tags });
+    if (tags && tags.length > 0) {
+      this.registerTags(tags, prefixedKey);
+    }
+  }
+
+  async invalidateTags(tags: string[]): Promise<void> {
+    for (const tag of tags) {
+      const keys = this.tagIndex.get(tag);
+      if (!keys || keys.size === 0) continue;
+
+      const prefixedKeys = [...keys];
+
+      for (const prefixedKey of prefixedKeys) {
+        const colonIdx = prefixedKey.indexOf(":");
+        const prefix = prefixedKey.slice(0, colonIdx);
+        const rawKey = prefixedKey.slice(colonIdx + 1);
+
+        if (prefix === "seg") {
+          this.cache.delete(rawKey);
+        } else if (prefix === "res") {
+          this.responseCache.delete(rawKey);
+        } else if (prefix === "item") {
+          this.itemCache.delete(rawKey);
+        } else if (prefix === "shell") {
+          this.shellCache.delete(rawKey);
+        }
+
+        this.unregisterTags(prefixedKey);
+      }
+    }
+  }
+
+  private registerTags(tags: string[], prefixedKey: string): void {
+    let tagSet = this.keyTags.get(prefixedKey);
+    if (!tagSet) {
+      tagSet = new Set();
+      this.keyTags.set(prefixedKey, tagSet);
+    }
+    for (const tag of tags) {
+      tagSet.add(tag);
+      let keys = this.tagIndex.get(tag);
+      if (!keys) {
+        keys = new Set();
+        this.tagIndex.set(tag, keys);
+      }
+      keys.add(prefixedKey);
+    }
+  }
+
+  private unregisterTags(prefixedKey: string): void {
+    const tagSet = this.keyTags.get(prefixedKey);
+    if (!tagSet) return;
+    for (const tag of tagSet) {
+      const keys = this.tagIndex.get(tag);
+      if (keys) {
+        keys.delete(prefixedKey);
+        if (keys.size === 0) {
+          this.tagIndex.delete(tag);
+        }
+      }
+    }
+    this.keyTags.delete(prefixedKey);
   }
 
-  /**
-   * Get cache statistics for debugging purposes.
-   * @internal
-   */
   getStats(): { size: number; keys: string[] } {
     return {
       size: this.cache.size,
@@ -308,21 +523,12 @@ export class MemorySegmentCacheStore<
     };
   }
 
-  /**
-   * Reset the global cache registry.
-   * Useful for test isolation - call this in beforeEach to ensure
-   * tests don't share cache state via globalThis.
-   *
-   * @example
-   * ```typescript
-   * beforeEach(() => {
-   *   MemorySegmentCacheStore.resetGlobalCache();
-   * });
-   * ```
-   */
   static resetGlobalCache(): void {
     delete (globalThis as any)[CACHE_REGISTRY_KEY];
     delete (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY];
     delete (globalThis as any)[ITEM_CACHE_REGISTRY_KEY];
+    delete (globalThis as any)[SHELL_CACHE_REGISTRY_KEY];
+    delete (globalThis as any)[TAG_INDEX_REGISTRY_KEY];
+    delete (globalThis as any)[KEY_TAGS_REGISTRY_KEY];
   }
 }

package/src/cache/profile-registry.ts

@@ -1,9 +1,11 @@
 /**
- * Cache Profile Registry
+ * Cache profile resolution.
  *
- * Named cache profiles for "use cache" directive.
- * Profiles define TTL, SWR, and optional default tags.
- * Set by createRouter() at startup, read by registerCachedFunction() at runtime.
+ * Named cache profiles for the "use cache" directive define TTL, SWR, and
+ * optional default tags. createRouter() resolves the user's profiles once via
+ * resolveCacheProfiles() and threads the resulting map onto each request
+ * context; the "use cache: <profile>" runtime path reads it from there
+ * (request-scoped) — there is no global registry.
  */
 
 export interface CacheProfile {
@@ -13,14 +15,25 @@ export interface CacheProfile {
   swr?: number;
   /** Default cache tags for invalidation */
   tags?: string[];
+  /**
+   * When true, a stale entry encountered during a server action's revalidation
+   * render is re-executed in the FOREGROUND (the action response reflects the
+   * refreshed value) instead of being served stale + revalidated in the
+   * background. Only the store write is deferred. Use this for mutation-related
+   * cached data that an action should refresh immediately; ordinary navigations
+   * always keep SWR. Default false: incidental TTL staleness must not turn an
+   * unrelated action into a synchronous cache-refresh barrier — for strong
+   * read-your-own-writes after a mutation, prefer updateTag() (a hard purge, so
+   * the action's own re-render is a fresh foreground miss).
+   *
+   * Honored only by `"use cache"` functions; route-level `cache()` and cached
+   * loaders ignore it (use updateTag() there).
+   */
+  foregroundOnAction?: boolean;
 }
 
 const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
 
-let _profiles: Record<string, CacheProfile> = {
-  default: DEFAULT_PROFILE,
-};
-
 const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
 /**
@@ -44,30 +57,32 @@ export function resolveCacheProfiles(
             `Profile names must match [a-zA-Z0-9_-]+.`,
         );
       }
-      merged[name] = profiles[name];
+      const profile = profiles[name];
+      // Validate ttl/swr VALUES, not just the name. An unvalidated NaN/Infinity
+      // ttl flows into computeExpiration -> staleAt/expiresAt = NaN, and every
+      // expiry check (`now > NaN`) is false, so the entry never evicts and never
+      // revalidates: it is served fresh forever and accumulates unbounded. A
+      // negative ttl makes every read a guaranteed miss. This guard's policy is
+      // to FAIL FAST at config time on any non-finite/negative ttl — distinct
+      // from prefetch-cache-ttl.ts (falls back to the default) and defer.ts
+      // (treats Infinity as an intentional disable). Do not conflate them.
+      if (!Number.isFinite(profile.ttl) || profile.ttl < 0) {
+        throw new Error(
+          `Invalid cache profile "${name}": ttl must be a finite non-negative ` +
+            `number (got ${profile.ttl}).`,
+        );
+      }
+      if (
+        profile.swr !== undefined &&
+        (!Number.isFinite(profile.swr) || profile.swr < 0)
+      ) {
+        throw new Error(
+          `Invalid cache profile "${name}": swr must be a finite non-negative ` +
+            `number (got ${profile.swr}).`,
+        );
+      }
+      merged[name] = profile;
     }
   }
   return merged;
 }
-
-/**
- * Set all cache profiles in the global registry.
- * Called by createRouter() at startup for DSL-time resolution
- * (cache("profileName") reads from this during route definition).
- *
- * WARNING: This is global mutable state. It exists only for DSL-time
- * reads. Runtime resolution (registerCachedFunction) uses request-scoped
- * profiles and does NOT read from this registry.
- */
-export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
-  _profiles = resolveCacheProfiles(profiles);
-}
-
-/**
- * Get a cache profile by name from the global registry.
- * Used only at DSL-time (cache("profileName") inside urls() evaluation).
- * Runtime code uses request-scoped profiles instead.
- */
-export function getCacheProfile(name: string): CacheProfile | undefined {
-  return _profiles[name];
-}

package/src/cache/read-through-swr.ts

@@ -13,10 +13,15 @@
 
 import type { CacheItemResult, CacheItemOptions } from "./types.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheErrorReporter } from "./cache-error.js";
 
-interface WaitUntilHost {
+// The host carries both the optional waitUntil (for background scheduling) and
+// the CacheErrorReporter seam (for routing degradation errors through onError).
+// loader-cache.ts passes the request context, which provides both.
+type WaitUntilHost = {
   waitUntil?: (fn: () => Promise<void>) => void;
-}
+} & CacheErrorReporter;
 
 export interface ReadThroughItemConfig<T> {
   /** Retrieve a cached item by key */
@@ -31,6 +36,14 @@ export interface ReadThroughItemConfig<T> {
   key: string;
   /** Execute the underlying function/loader on miss or revalidation */
   execute: () => Promise<T>;
+  /**
+   * Optional wrapper applied to execute() ONLY on the background
+   * stale-revalidation path (not the foreground miss, where the caller's context
+   * is already established). Used to re-establish the request-context ALS, which
+   * a detached waitUntil task loses on workerd. Defaults to calling execute()
+   * directly.
+   */
+  wrapBackground?: (run: () => Promise<T>) => Promise<T>;
   /** Serialize result for storage. Return null to skip caching. */
   serialize: (data: T) => Promise<string | null>;
   /** Deserialize cached value back to the original type */
@@ -72,13 +85,23 @@ export async function readThroughItem<T>(
     onMiss,
     onCached,
     host,
+    wrapBackground,
   } = config;
 
-  // Cache lookup
+  // Cache lookup. An infra read failure (getItem) is reported by the store
+  // itself, so here we just degrade to a miss. A deserialize failure is a
+  // corrupt/truncated stored entry, which this layer owns: report it LOUD as
+  // cache-corrupt, then fall through to a fresh execution (the miss-path write
+  // self-heals the bad entry).
+  let cached: CacheItemResult | null = null;
   try {
-    const cached = await getItem(key);
+    cached = await getItem(key);
+  } catch {
+    cached = null;
+  }
 
-    if (cached) {
+  if (cached) {
+    try {
       const data = await deserialize(cached.value);
 
       if (!cached.shouldRevalidate) {
@@ -92,21 +115,37 @@ export async function readThroughItem<T>(
         host,
         async () => {
           try {
-            const fresh = await execute();
+            // Re-establish the caller's context (request-context ALS) for the
+            // detached background execution; the foreground miss below calls
+            // execute() directly since its context is already established.
+            const fresh = await (wrapBackground
+              ? wrapBackground(execute)
+              : execute());
             const serialized = await serialize(fresh);
             if (serialized !== null) {
               await setItem(key, serialized, storeOptions);
             }
-          } catch {
-            // Background revalidation failed silently
+          } catch (error) {
+            reportCacheError(
+              error,
+              "stale-revalidation",
+              "[read-through] background revalidation",
+              host ?? undefined,
+            );
           }
         },
         true,
       );
       return data;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-corrupt",
+        "[read-through] deserialize stored entry",
+        host ?? undefined,
+      );
+      // fall through to fresh execution
     }
-  } catch {
-    // Cache lookup failed, fall through to fresh execution
   }
 
   // Cache miss
@@ -123,8 +162,13 @@ export async function readThroughItem<T>(
           await setItem(key, serialized, storeOptions);
           onCached?.();
         }
-      } catch {
-        // Cache write failed silently
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[read-through] cache write",
+          host ?? undefined,
+        );
       }
     },
     true,