@rangojs/router 0.0.0-experimental.31 → 0.0.0-experimental.3232cd17

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

@@ -12,19 +12,22 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
-  SegmentHandleData,
 } 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 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 +59,10 @@ interface CachedResponseEntry {
 
 interface CachedItemEntry {
   value: string;
-  handles?: Record<string, SegmentHandleData>;
+  handles?: string;
   expiresAt: number;
   staleAt: number;
+  tags?: string[];
 }
 
 /**
@@ -73,6 +77,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
@@ -121,6 +130,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
@@ -143,6 +157,10 @@ 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 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>,
@@ -151,8 +169,6 @@ export class MemorySegmentCacheStore<
 
   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,11 +181,20 @@ export class MemorySegmentCacheStore<
         ITEM_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.tagIndex = new Map<string, Set<string>>();
+      this.keyTags = new Map<string, Set<string>>();
     }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
@@ -184,6 +209,7 @@ export class MemorySegmentCacheStore<
 
     // Check expiration
     if (Date.now() > cached.expiresAt) {
+      this.unregisterTags(`seg:${key}`);
       this.cache.delete(key);
       return null;
     }
@@ -198,16 +224,20 @@ 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.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 +245,8 @@ export class MemorySegmentCacheStore<
     this.cache.clear();
     this.responseCache.clear();
     this.itemCache.clear();
+    this.tagIndex.clear();
+    this.keyTags.clear();
   }
 
   async getResponse(
@@ -224,6 +256,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 +277,38 @@ 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.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 +317,7 @@ export class MemorySegmentCacheStore<
 
     const now = Date.now();
     if (now > cached.expiresAt) {
+      this.unregisterTags(`item:${key}`);
       this.itemCache.delete(key);
       return null;
     }
@@ -278,6 +327,7 @@ export class MemorySegmentCacheStore<
       value: cached.value,
       handles: cached.handles,
       shouldRevalidate: isStale,
+      tags: cached.tags,
     };
   }
 
@@ -289,18 +339,77 @@ 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.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 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);
+        }
+
+        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 +417,11 @@ 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)[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 {
@@ -17,10 +19,6 @@ export interface CacheProfile {
 
 const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
 
-let _profiles: Record<string, CacheProfile> = {
-  default: DEFAULT_PROFILE,
-};
-
 const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
 /**
@@ -49,25 +47,3 @@ export function resolveCacheProfiles(
   }
   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 */
@@ -74,11 +79,20 @@ export async function readThroughItem<T>(
     host,
   } = 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) {
@@ -97,16 +111,27 @@ export async function readThroughItem<T>(
             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 +148,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,

package/src/cache/segment-codec.ts

@@ -16,10 +16,6 @@ import {
 } from "@vitejs/plugin-rsc/rsc";
 import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
 
-// ============================================================================
-// Stream Utilities (internal)
-// ============================================================================
-
 /**
  * Convert a ReadableStream to a string.
  */
@@ -55,10 +51,6 @@ export function stringToStream(str: string): ReadableStream<Uint8Array> {
   });
 }
 
-// ============================================================================
-// RSC Serialization Primitives (internal)
-// ============================================================================
-
 /**
  * RSC-serialize a value using React Server Components stream.
  * Used for serializing loaderData, layout, loading components etc.
@@ -90,10 +82,6 @@ export async function rscDeserialize<T>(
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Null-Preserving RSC Serialization (for caching)
-// ============================================================================
-
 /**
  * RSC-serialize any value including null.
  * Unlike rscSerialize(), this does NOT skip null — it serializes it through
@@ -122,10 +110,6 @@ export async function deserializeResult<T>(encoded: string): Promise<T> {
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Public API
-// ============================================================================
-
 /**
  * RSC-deserialize a single encoded component string back to a React element.
  * Used by the static handler runtime to revive pre-rendered components.