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

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

@@ -12,6 +12,7 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
+  ShellCacheEntry,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 import { isPerClientSignalHeader } from "../browser/cookie-name.js";
@@ -26,6 +27,7 @@ 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__";
 
@@ -65,6 +67,13 @@ interface CachedItemEntry {
   tags?: string[];
 }
 
+interface CachedShellEntry {
+  entry: ShellCacheEntry;
+  expiresAt: number;
+  staleAt: number;
+  tags?: string[];
+}
+
 /**
  * Options for MemorySegmentCacheStore
  */
@@ -121,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.
  *
@@ -130,10 +156,16 @@ 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 or invalidated. This is bounded by
- * the distinct-tag count and acceptable for a dev/single-instance store.
+ * 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
@@ -157,7 +189,8 @@ export class MemorySegmentCacheStore<
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
   private itemCache: Map<string, CachedItemEntry>;
-  /** tag -> set of prefixed cache keys (seg:key, res:key, item:key) */
+  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>>;
@@ -166,6 +199,8 @@ export class MemorySegmentCacheStore<
     ctx: RequestContext<TEnv>,
     defaultKey: string,
   ) => string | Promise<string>;
+  /** Per-family FIFO entry cap. */
+  readonly maxEntries: number;
 
   constructor(options?: MemorySegmentCacheStoreOptions<TEnv>) {
     if (options?.name != null) {
@@ -181,6 +216,10 @@ 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,
@@ -193,11 +232,34 @@ export class MemorySegmentCacheStore<
       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> {
@@ -230,6 +292,7 @@ export class MemorySegmentCacheStore<
     };
     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);
@@ -245,6 +308,7 @@ export class MemorySegmentCacheStore<
     this.cache.clear();
     this.responseCache.clear();
     this.itemCache.clear();
+    this.shellCache.clear();
     this.tagIndex.clear();
     this.keyTags.clear();
   }
@@ -292,6 +356,7 @@ export class MemorySegmentCacheStore<
 
       const prefixedKey = `res:${key}`;
       this.unregisterTags(prefixedKey);
+      this.evictIfNeeded(this.responseCache, key, "res");
       this.responseCache.set(key, {
         body,
         status: response.status,
@@ -341,6 +406,7 @@ export class MemorySegmentCacheStore<
     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,
@@ -353,6 +419,44 @@ export class MemorySegmentCacheStore<
     }
   }
 
+  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);
@@ -371,6 +475,8 @@ export class MemorySegmentCacheStore<
           this.responseCache.delete(rawKey);
         } else if (prefix === "item") {
           this.itemCache.delete(rawKey);
+        } else if (prefix === "shell") {
+          this.shellCache.delete(rawKey);
         }
 
         this.unregisterTags(prefixedKey);
@@ -421,6 +527,7 @@ export class MemorySegmentCacheStore<
     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

@@ -15,6 +15,21 @@ 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 };

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

@@ -36,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 */
@@ -77,6 +85,7 @@ export async function readThroughItem<T>(
     onMiss,
     onCached,
     host,
+    wrapBackground,
   } = config;
 
   // Cache lookup. An infra read failure (getItem) is reported by the store
@@ -106,7 +115,12 @@ 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);

package/src/cache/segment-codec.ts

@@ -25,16 +25,16 @@ export async function streamToString(
 ): Promise<string> {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
-  let result = "";
+  const chunks: string[] = [];
 
   while (true) {
     const { done, value } = await reader.read();
     if (done) break;
-    result += decoder.decode(value, { stream: true });
+    chunks.push(decoder.decode(value, { stream: true }));
   }
 
-  result += decoder.decode(); // flush
-  return result;
+  chunks.push(decoder.decode()); // flush
+  return chunks.join("");
 }
 
 /**