@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

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

@@ -5,15 +5,101 @@
  * Uses globalThis to survive HMR in development.
  */
 
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult } from "./types.js";
+import type {
+  SegmentCacheStore,
+  CachedEntryData,
+  CacheDefaults,
+  CacheGetResult,
+  CacheItemResult,
+  CacheItemOptions,
+  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_GLOBAL_KEY = "__rsc_router_segment_cache_store__";
+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.
+ * The registry survives HMR; individual stores are keyed by name.
+ */
+function getNamedMap<V>(registryKey: string, name: string): Map<string, V> {
+  let registry = (globalThis as any)[registryKey] as
+    | Map<string, Map<string, V>>
+    | undefined;
+  if (!registry) {
+    registry = new Map();
+    (globalThis as any)[registryKey] = registry;
+  }
+  let map = registry.get(name);
+  if (!map) {
+    map = new Map<string, V>();
+    registry.set(name, map);
+  }
+  return map;
+}
+
+interface CachedResponseEntry {
+  body: ArrayBuffer;
+  status: number;
+  headers: [string, string][];
+  expiresAt: number;
+  staleAt: number;
+}
+
+interface CachedItemEntry {
+  value: string;
+  handles?: string;
+  expiresAt: number;
+  staleAt: number;
+  tags?: string[];
+}
+
+interface CachedShellEntry {
+  entry: ShellCacheEntry;
+  expiresAt: number;
+  staleAt: number;
+  tags?: string[];
+}
 
 /**
  * Options for MemorySegmentCacheStore
  */
 export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
+  /**
+   * Optional name for this store instance. Named stores persist their
+   * backing Map on globalThis so data survives Vite HMR module reloads.
+   * Stores with different names get separate Maps.
+   *
+   * 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
+   * const fast = new MemorySegmentCacheStore({ name: "fast", defaults: { ttl: 10 } });
+   * const slow = new MemorySegmentCacheStore({ name: "slow", defaults: { ttl: 300 } });
+   * ```
+   */
+  name?: string;
+
   /**
    * Default cache options for cache() boundaries.
    * When cache() is called without explicit ttl/swr,
@@ -35,14 +121,14 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
    * @example
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
-   *   const locale = ctx.cookie('locale') || 'en';
+   *   const locale = cookies().get('locale')?.value || 'en';
    *   return `${locale}:${defaultKey}`;
    * }
    * ```
    */
   keyGenerator?: (
     ctx: RequestContext<TEnv>,
-    defaultKey: string
+    defaultKey: string,
   ) => string | Promise<string>;
 }
 
@@ -53,6 +139,11 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * For production with multiple instances, use a distributed store
  * like Cloudflare KV or Redis.
  *
+ * 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.
+ *
  * @example
  * ```typescript
  * // Basic usage
@@ -69,19 +160,57 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * })
  * ```
  */
-export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+export class MemorySegmentCacheStore<
+  TEnv = unknown,
+> implements SegmentCacheStore<TEnv> {
   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
+    defaultKey: string,
   ) => string | Promise<string>;
 
   constructor(options?: MemorySegmentCacheStoreOptions<TEnv>) {
-    // Use globalThis to survive HMR in development
-    this.cache =
-      (globalThis as any)[CACHE_GLOBAL_KEY] ??
-      ((globalThis as any)[CACHE_GLOBAL_KEY] = new Map<string, CachedEntryData>());
+    if (options?.name != null) {
+      this.cache = getNamedMap<CachedEntryData>(
+        CACHE_REGISTRY_KEY,
+        options.name,
+      );
+      this.responseCache = getNamedMap<CachedResponseEntry>(
+        RESPONSE_CACHE_REGISTRY_KEY,
+        options.name,
+      );
+      this.itemCache = getNamedMap<CachedItemEntry>(
+        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 {
+      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;
   }
@@ -95,6 +224,7 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
 
     // Check expiration
     if (Date.now() > cached.expiresAt) {
+      this.unregisterTags(`seg:${key}`);
       this.cache.delete(key);
       return null;
     }
@@ -103,28 +233,238 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
     return { data: cached, shouldRevalidate: false };
   }
 
-  async set(key: string, data: CachedEntryData, 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
+  async set(
+    key: string,
+    data: CachedEntryData,
+    ttl: number,
+    _swr?: number,
+  ): Promise<void> {
     const entry: CachedEntryData = {
       ...data,
       expiresAt: Date.now() + ttl * 1000,
     };
+    const prefixedKey = `seg:${key}`;
+    this.unregisterTags(prefixedKey);
     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);
   }
 
   async clear(): Promise<void> {
     this.cache.clear();
+    this.responseCache.clear();
+    this.itemCache.clear();
+    this.shellCache.clear();
+    this.tagIndex.clear();
+    this.keyTags.clear();
+  }
+
+  async getResponse(
+    key: string,
+  ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
+    const cached = this.responseCache.get(key);
+    if (!cached) return null;
+
+    if (Date.now() > cached.expiresAt) {
+      this.unregisterTags(`res:${key}`);
+      this.responseCache.delete(key);
+      return null;
+    }
+
+    const isStale = cached.staleAt > 0 && Date.now() > cached.staleAt;
+    const headers = new Headers(cached.headers);
+    return {
+      response: new Response(cached.body, {
+        status: cached.status,
+        headers,
+      }),
+      shouldRevalidate: isStale,
+    };
+  }
+
+  async putResponse(
+    key: string,
+    response: Response,
+    ttl: number,
+    swr?: number,
+    tags?: string[],
+  ): Promise<void> {
+    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 prefixedKey = `res:${key}`;
+      this.unregisterTags(prefixedKey);
+      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> {
+    const cached = this.itemCache.get(key);
+    if (!cached) return null;
+
+    const now = Date.now();
+    if (now > cached.expiresAt) {
+      this.unregisterTags(`item:${key}`);
+      this.itemCache.delete(key);
+      return null;
+    }
+
+    const isStale = now > cached.staleAt;
+    return {
+      value: cached.value,
+      handles: cached.handles,
+      shouldRevalidate: isStale,
+      tags: cached.tags,
+    };
+  }
+
+  async setItem(
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ): Promise<void> {
+    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.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.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,
@@ -132,19 +472,12 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
     };
   }
 
-  /**
-   * Reset the global cache state.
-   * 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_GLOBAL_KEY];
+    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

@@ -0,0 +1,88 @@
+/**
+ * Cache profile resolution.
+ *
+ * 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 {
+  /** Time-to-live in seconds */
+  ttl: number;
+  /** Stale-while-revalidate window in seconds */
+  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 };
+
+const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Validate and merge user profiles with the default profile.
+ * Returns a new object suitable for both DSL-time and request-scoped use.
+ *
+ * Used by createRouter() to compute the resolved profile map once,
+ * stored on the router instance and passed to every request context.
+ */
+export function resolveCacheProfiles(
+  profiles?: Record<string, CacheProfile>,
+): Record<string, CacheProfile> {
+  const merged: Record<string, CacheProfile> = {
+    default: DEFAULT_PROFILE,
+  };
+  if (profiles) {
+    for (const name of Object.keys(profiles)) {
+      if (!PROFILE_NAME_RE.test(name)) {
+        throw new Error(
+          `Invalid cache profile name "${name}". ` +
+            `Profile names must match [a-zA-Z0-9_-]+.`,
+        );
+      }
+      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;
+}