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

package/src/cache/document-cache.ts

@@ -12,23 +12,25 @@
  */
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import { getRequestContext } from "../server/request-context.js";
+import { hasPerClientSignal } from "../browser/cookie-name.js";
+import {
+  getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
 
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Header indicating cache status for debugging */
 const CACHE_STATUS_HEADER = "x-document-cache-status";
 
-/**
- * Simple hash function for segment IDs.
- * Creates a short, deterministic hash to differentiate cache keys
- * based on which segments the client already has.
- */
+function collectRequestTags(
+  requestCtx: RequestContext | undefined,
+): string[] | undefined {
+  const tags = requestCtx?._requestTags;
+  return tags && tags.size > 0 ? [...tags] : undefined;
+}
+
 function hashSegmentIds(segmentIds: string): string {
   if (!segmentIds) return "";
 
@@ -37,12 +39,9 @@ function hashSegmentIds(segmentIds: string): string {
     const char = segmentIds.charCodeAt(i);
     hash = ((hash << 5) - hash + char) | 0;
   }
-  // Convert to base36 for shorter string, take absolute value
   return Math.abs(hash).toString(36);
 }
 
-// ============================================================================
-// Cache Control Parsing
 // ============================================================================
 
 interface CacheDirectives {
@@ -56,6 +55,27 @@ interface CacheDirectives {
 function parseCacheControl(header: string | null): CacheDirectives | null {
   if (!header) return null;
 
+  // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
+  // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
+  // The document cache is a shared edge store, so refuse both regardless of any
+  // s-maxage / stale-while-revalidate also present. Match standalone directive
+  // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
+  // substring, so a value containing "private" cannot false-veto.
+  if (/(^|[\s,;])(private|no-store)(?=$|[\s,;=])/i.test(header)) {
+    return null;
+  }
+
+  // RFC 7234 §5.2.2.2: a shared cache MUST NOT serve a stored `no-cache`
+  // response without successful origin validation. This store's hit path has no
+  // validation step, so serving a stored no-cache response within s-maxage
+  // would hand the client content the origin marked must-revalidate. Refuse to
+  // store it. Only UNqualified `no-cache` (no `=`) vetoes — the field-name-
+  // scoped `no-cache="set-cookie"` form IS storable per the RFC, so the `=`
+  // boundary is excluded from the lookahead (unlike private/no-store above).
+  if (/(^|[\s,;])no-cache(?=$|[\s,;])/i.test(header)) {
+    return null;
+  }
+
   const directives: CacheDirectives = {};
 
   // Parse s-maxage
@@ -87,6 +107,16 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
     return null;
   }
 
+  // Never cache a per-client signal into a SHARED response store. A Set-Cookie
+  // (e.g. a rango state rotation from invalidateClientCache(), or any cookie a
+  // loader set) would be replayed to every client on a hit — pinning them to
+  // one value and even rolling a rotated client back to a prior one. The
+  // x-rango-keep-cache directive header is the mirror image: a replayed "keep"
+  // would suppress invalidation for every replayed client. Refuse both.
+  if (hasPerClientSignal(response.headers)) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }
@@ -303,17 +333,26 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             const fresh = await next();
             const directives = shouldCacheResponse(fresh);
 
-            if (directives) {
+            if (directives && fresh.body) {
+              // Background revalidation: nothing streams to a client, so drain
+              // the fresh render fully before snapshotting tags (same
+              // render-complete barrier as the miss path).
+              const body = await new Response(fresh.body).arrayBuffer();
               await store.putResponse!(
                 cacheKey,
-                fresh,
+                new Response(body, fresh),
                 directives.sMaxAge!,
                 directives.staleWhileRevalidate,
+                collectRequestTags(requestCtx),
               );
               log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
             }
           } catch (error) {
-            console.error(`[DocumentCache] Revalidation failed:`, error);
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] revalidation",
+            );
           }
         });
 
@@ -346,14 +385,27 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         // Clone response for caching (non-blocking)
         runBackground(requestCtx, async () => {
           try {
+            // Drain the cache copy fully BEFORE snapshotting tags. Tags from
+            // Suspense-streamed "use cache"/cacheTag and loaders are recorded as
+            // each value resolves during the RSC/HTML render, which completes
+            // only when the stream ends - the handler-settlement barrier is too
+            // early. Buffering the body (the client streams the other tee branch,
+            // unaffected) is the render-complete barrier that keeps the cached
+            // body and its tag set consistent.
+            const body = await new Response(cacheStream).arrayBuffer();
             await store.putResponse!(
               cacheKey,
-              new Response(cacheStream, originalResponse),
+              new Response(body, originalResponse),
               directives.sMaxAge!,
               directives.staleWhileRevalidate,
+              collectRequestTags(requestCtx),
             );
           } catch (error) {
-            console.error(`[DocumentCache] Cache write failed:`, error);
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] cache write",
+            );
           }
         });
 
@@ -366,7 +418,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // No cache headers - pass through
       return originalResponse;
     } catch (error) {
-      console.error(`[DocumentCache] Error:`, error);
+      reportCacheError(error, "cache-read", "[DocumentCache] middleware");
       if (handlerCalled) {
         // Post-handler failure (e.g. body.tee()): do not call next() again
         // as that would re-run handler side effects.

package/src/cache/handle-snapshot.ts

@@ -9,6 +9,76 @@
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
+// segment-codec eagerly pulls @vitejs/plugin-rsc (a virtual: module unresolvable
+// in plain node/vitest). It is imported LAZILY inside the two async encode/decode
+// helpers below so that modules which import handle-snapshot only for the
+// plugin-rsc-free captureHandles/restoreHandles (e.g. cache-scope, on dispatch's
+// lazy response-route cache path) do not pull plugin-rsc at module load. Behavior
+// is unchanged: both helpers are async and already awaited the codec.
+
+const HANDLE_ENCODE_TIMEOUT_MS = 5000;
+
+type HandleRecord = Record<string, SegmentHandleData>;
+
+function hasHandleData(handles: HandleRecord): boolean {
+  for (const segId in handles) {
+    for (const _ in handles[segId]) return true;
+  }
+  return false;
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(onTimeout), ms);
+  });
+  return Promise.race([
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        return v;
+      },
+      (e) => {
+        clearTimeout(timer);
+        throw e;
+      },
+    ),
+    timeout,
+  ]);
+}
+
+export async function encodeHandles(handles: HandleRecord): Promise<string> {
+  if (!hasHandleData(handles)) return "";
+  return encodeHandleValue(handles);
+}
+
+export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
+  return decodeHandleValue<HandleRecord>(encoded);
+}
+
+export async function encodeHandleValue(value: unknown): Promise<string> {
+  const { serializeResult } = await import("./segment-codec.js");
+  const encoded = await withTimeout(
+    serializeResult(value),
+    HANDLE_ENCODE_TIMEOUT_MS,
+    null,
+  );
+  return encoded ?? "";
+}
+
+/**
+ * Decode a Flight-encoded handle-data string. Returns null on any decode
+ * failure so the caller can skip handle restore without discarding valid
+ * cached/prerendered segments.
+ */
+export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
+  try {
+    const { deserializeResult } = await import("./segment-codec.js");
+    return await deserializeResult<T>(encoded);
+  } catch {
+    return null;
+  }
+}
 
 /**
  * Capture handle data for a set of segments from the handle store.

package/src/cache/index.ts

@@ -1,44 +1,46 @@
-/**
- * Cache Store
- *
- * Server-side caching for RSC segments and loader data.
- *
- * Main exports for users:
- * - SegmentCacheStore - Interface for implementing custom cache stores
- * - MemorySegmentCacheStore - In-memory cache for development/testing
- * - CFCacheStore - Cloudflare edge cache store for production
- * - CacheScope / createCacheScope - Request-scoped cache provider
- */
-
-// Segment cache store types and implementations
 export type {
   SegmentCacheStore,
-  SegmentCacheProvider,
   CachedEntryData,
-  CachedEntryResult,
   CacheGetResult,
+  CacheItemResult,
+  CacheItemOptions,
   SerializedSegmentData,
   SegmentHandleData,
-  CacheConfig,
-  CacheConfigOrFactory,
 } from "./types.js";
 
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 
-// Cloudflare cache store
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
+  type CFCacheDebug,
+  type CFCacheReadDebugEvent,
   type KVNamespace,
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
+  CACHE_REVALIDATING_AT_HEADER,
+  EDGE_LOOKUP_TIMEOUT_MS,
+  EDGE_READ_TIMEOUT_MS,
+  KV_READ_TIMEOUT_MS,
 } from "./cf/index.js";
 
-// Cache scope
+export {
+  VercelCacheStore,
+  type VercelCacheStoreOptions,
+  type VercelRuntimeCache,
+  type VercelCacheDebug,
+  type VercelCacheReadDebugEvent,
+  type VercelCacheReadOutcome,
+  VERCEL_MAX_ITEM_BYTES,
+  VERCEL_MAX_TAGS_PER_ITEM,
+  VERCEL_MAX_TAG_BYTES,
+} from "./vercel/index.js";
+
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 
-// Document-level cache middleware
 export {
   createDocumentCacheMiddleware,
   type DocumentCacheOptions,
 } from "./document-cache.js";
+
+export type { CacheErrorCategory } from "./cache-error.js";

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];
   }
 }