@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.98d9a51b

package/src/cache/cf/index.ts

@@ -10,10 +10,20 @@
  */
 
 // Public API
-export { CFCacheStore, type CFCacheStoreOptions } from "./cf-cache-store.js";
+export {
+  CFCacheStore,
+  type CFCacheStoreOptions,
+  type KVNamespace,
+} from "./cf-cache-store.js";
 
 // Header constants for debugging and inspection
-export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER } from "./cf-cache-store.js";
+export {
+  CACHE_STALE_AT_HEADER,
+  CACHE_STATUS_HEADER,
+} from "./cf-cache-store.js";
 
 // Internal exports (re-exported for backwards compatibility, marked @internal in source)
-export { type CacheStatus, MAX_REVALIDATION_INTERVAL } from "./cf-cache-store.js";
+export {
+  type CacheStatus,
+  MAX_REVALIDATION_INTERVAL,
+} from "./cf-cache-store.js";

package/src/cache/document-cache.ts

@@ -13,6 +13,8 @@
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { getRequestContext } from "../server/request-context.js";
+import { sortedSearchString } from "./cache-key-utils.js";
+import { runBackground } from "./background-task.js";
 
 // ============================================================================
 // Constants
@@ -110,15 +112,24 @@ function addCacheStatusHeader(
 }
 
 /**
- * Run onResponse callbacks registered on the request context
+ * Drain and run onResponse callbacks registered on the request context.
+ * Mirrors the drain semantics of finalizeResponse() in rsc/helpers.ts:
+ * callbacks are spliced out so they fire at most once per request.
  */
-function runOnResponseCallbacks(
+function drainOnResponseCallbacks(
   response: Response,
-  callbacks: Array<(response: Response) => Response>,
+  requestCtx:
+    | { _onResponseCallbacks: Array<(r: Response) => Response> }
+    | undefined,
 ): Response {
+  if (!requestCtx || requestCtx._onResponseCallbacks.length === 0) {
+    return response;
+  }
+  const callbacks = requestCtx._onResponseCallbacks;
+  requestCtx._onResponseCallbacks = [];
   let result = response;
   for (const callback of callbacks) {
-    result = callback(result);
+    result = callback(result) ?? result;
   }
   return result;
 }
@@ -185,9 +196,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
 ): MiddlewareFn<TEnv> {
   const { skipPaths = [], keyGenerator, isEnabled, debug = false } = options;
 
-  const log = debug
-    ? (message: string) => console.log(message)
-    : () => {};
+  const log = debug ? (message: string) => console.log(message) : () => {};
 
   return async function documentCacheMiddleware(
     ctx: MiddlewareContext<TEnv>,
@@ -195,6 +204,11 @@ export function createDocumentCacheMiddleware<TEnv = any>(
   ): Promise<Response> {
     const url = ctx.url;
 
+    // Only cache GET requests — mutations and other methods must not be cached
+    if (ctx.request.method !== "GET") {
+      return next();
+    }
+
     // Skip RSC action requests (mutations shouldn't be cached)
     if (url.searchParams.has("_rsc_action")) {
       return next();
@@ -231,17 +245,31 @@ export function createDocumentCacheMiddleware<TEnv = any>(
     const isPartial = url.searchParams.has("_rsc_partial");
     const typeLabel = isPartial ? "RSC" : "HTML";
 
-    // Generate cache key
-    // For partial requests, include hash of client segments to prevent serving
-    // wrong cached response when navigating from different pages with different layouts
-    const clientSegments = url.searchParams.get("_rsc_segments") || "";
-    const segmentHash = isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
-    const typeSuffix = isPartial ? ":rsc" : ":html";
-    const cacheKey = keyGenerator
-      ? keyGenerator(url) + segmentHash + typeSuffix
-      : `${url.pathname}${segmentHash}${typeSuffix}`;
+    // Track whether next() has been called so the catch block knows
+    // whether it is safe to fall through to the handler.
+    let handlerCalled = false;
 
     try {
+      // Generate cache key inside try so a throwing keyGenerator degrades
+      // gracefully to the origin handler instead of rejecting the request.
+      // This is a deliberate fail-open-to-origin policy: the fallback is
+      // "serve uncached from origin", not "use a different cache key".
+      const clientSegments = url.searchParams.get("_rsc_segments") || "";
+      const segmentHash =
+        isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
+      const typeSuffix = isPartial ? ":rsc" : ":html";
+
+      let searchSuffix = "";
+      if (!keyGenerator) {
+        const sorted = sortedSearchString(url.searchParams);
+        if (sorted) {
+          searchSuffix = `?${sorted}`;
+        }
+      }
+
+      const cacheKey = keyGenerator
+        ? keyGenerator(url) + segmentHash + typeSuffix
+        : `${url.pathname}${searchSuffix}${segmentHash}${typeSuffix}`;
       // 1. Check cache
       const cached = await store.getResponse(cacheKey);
 
@@ -249,79 +277,75 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         if (!cached.shouldRevalidate) {
           // Fresh hit - return immediately
           log(`[DocumentCache] HIT ${typeLabel}: ${url.pathname}`);
-          let response = addCacheStatusHeader(cached.response, "HIT");
-          // Run onResponse callbacks even for cache hits
-          if (requestCtx && requestCtx._onResponseCallbacks.length > 0) {
-            response = runOnResponseCallbacks(
-              response,
-              requestCtx._onResponseCallbacks,
-            );
-          }
-          return response;
+          return drainOnResponseCallbacks(
+            addCacheStatusHeader(cached.response, "HIT"),
+            requestCtx,
+          );
         }
 
         // Stale hit - return cached response, revalidate in background
-        log(`[DocumentCache] STALE ${typeLabel}: ${url.pathname} (revalidating)`);
-
-        if (requestCtx) {
-          requestCtx.waitUntil(async () => {
-            try {
-              const fresh = await next();
-              const directives = shouldCacheResponse(fresh);
-
-              if (directives) {
-                await store.putResponse!(
-                  cacheKey,
-                  fresh,
-                  directives.sMaxAge!,
-                  directives.staleWhileRevalidate,
-                );
-                log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
-              }
-            } catch (error) {
-              console.error(`[DocumentCache] Revalidation failed:`, error);
+        log(
+          `[DocumentCache] STALE ${typeLabel}: ${url.pathname} (revalidating)`,
+        );
+
+        runBackground(requestCtx, async () => {
+          try {
+            const fresh = await next();
+            const directives = shouldCacheResponse(fresh);
+
+            if (directives) {
+              await store.putResponse!(
+                cacheKey,
+                fresh,
+                directives.sMaxAge!,
+                directives.staleWhileRevalidate,
+              );
+              log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
             }
-          });
-        }
+          } catch (error) {
+            console.error(`[DocumentCache] Revalidation failed:`, error);
+          }
+        });
 
-        let response = addCacheStatusHeader(cached.response, "STALE");
-        // Run onResponse callbacks even for stale cache hits
-        if (requestCtx && requestCtx._onResponseCallbacks.length > 0) {
-          response = runOnResponseCallbacks(
-            response,
-            requestCtx._onResponseCallbacks,
-          );
-        }
-        return response;
+        return drainOnResponseCallbacks(
+          addCacheStatusHeader(cached.response, "STALE"),
+          requestCtx,
+        );
       }
 
       // 2. Cache miss - run handler
+      handlerCalled = true;
       const originalResponse = await next();
 
       // 3. Cache if response has appropriate headers
       const directives = shouldCacheResponse(originalResponse);
 
       if (directives) {
-        log(`[DocumentCache] MISS ${typeLabel}: ${url.pathname} (caching with s-maxage=${directives.sMaxAge})`);
+        log(
+          `[DocumentCache] MISS ${typeLabel}: ${url.pathname} (caching with s-maxage=${directives.sMaxAge})`,
+        );
+
+        // If the response has no body (e.g., 200 with empty body), skip caching
+        if (!originalResponse.body) {
+          return originalResponse;
+        }
 
         // Tee the body so we can return one stream and cache the other
-        const [returnStream, cacheStream] = originalResponse.body!.tee();
+        const [returnStream, cacheStream] = originalResponse.body.tee();
 
         // Clone response for caching (non-blocking)
-        if (requestCtx) {
-          requestCtx.waitUntil(async () => {
-            try {
-              await store.putResponse!(
-                cacheKey,
-                new Response(cacheStream, originalResponse),
-                directives.sMaxAge!,
-                directives.staleWhileRevalidate,
-              );
-            } catch (error) {
-              console.error(`[DocumentCache] Cache write failed:`, error);
-            }
-          });
-        }
+        runBackground(requestCtx, async () => {
+          try {
+            await store.putResponse!(
+              cacheKey,
+              new Response(cacheStream, originalResponse),
+              directives.sMaxAge!,
+              directives.staleWhileRevalidate,
+            );
+          } catch (error) {
+            console.error(`[DocumentCache] Cache write failed:`, error);
+          }
+        });
 
         return addCacheStatusHeader(
           new Response(returnStream, originalResponse),
@@ -333,7 +357,12 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return originalResponse;
     } catch (error) {
       console.error(`[DocumentCache] Error:`, error);
-      // On any cache error, fall through to handler
+      if (handlerCalled) {
+        // Post-handler failure (e.g. body.tee()): do not call next() again
+        // as that would re-run handler side effects.
+        throw error;
+      }
+      // Pre-handler failure (cache lookup): degrade gracefully to origin
       return next();
     }
   };

package/src/cache/handle-capture.ts

@@ -0,0 +1,81 @@
+/**
+ * Handle Capture
+ *
+ * Captures handle pushes during cached function execution.
+ * Extracted from cache-runtime.ts so tests can import without
+ * pulling in @vitejs/plugin-rsc/rsc dependencies.
+ */
+
+import type { HandleStore } from "../server/handle-store.js";
+import type { SegmentHandleData } from "./types.js";
+
+export interface HandleCapture {
+  data: Record<string, SegmentHandleData>;
+}
+
+/**
+ * Active capture tokens per HandleStore.
+ *
+ * Instead of mutating handleStore.push (which breaks when overlapping
+ * captures finish out of order), we install a single interceptor on
+ * first use and manage a set of active capture tokens. Each push fans
+ * out to every active token. Stopping a capture simply removes the
+ * token — order does not matter.
+ */
+const activeCapturesMap = new WeakMap<HandleStore, Set<HandleCapture>>();
+
+/**
+ * One-time interceptor installation. Wraps the original push so every
+ * call fans out to all active capture tokens. Installed once per
+ * HandleStore instance; subsequent startHandleCapture calls on the
+ * same store just add tokens to the Set.
+ */
+function ensureInterceptorInstalled(handleStore: HandleStore): void {
+  if (activeCapturesMap.has(handleStore)) return;
+
+  const captures = new Set<HandleCapture>();
+  activeCapturesMap.set(handleStore, captures);
+
+  const originalPush = handleStore.push.bind(handleStore);
+  handleStore.push = (
+    handleName: string,
+    segmentId: string,
+    value: unknown,
+  ) => {
+    for (const capture of captures) {
+      if (!capture.data[segmentId]) {
+        capture.data[segmentId] = {};
+      }
+      if (!capture.data[segmentId][handleName]) {
+        capture.data[segmentId][handleName] = [];
+      }
+      capture.data[segmentId][handleName].push(value);
+    }
+    originalPush(handleName, segmentId, value);
+  };
+}
+
+/**
+ * Start capturing handle pushes for a cached function execution.
+ *
+ * Concurrency-safe: multiple overlapping captures on the same
+ * HandleStore are independent. Each capture registers a token in a
+ * Set; stopping removes it. No ordering requirement (LIFO not needed).
+ */
+export function startHandleCapture(handleStore: HandleStore): {
+  capture: HandleCapture;
+  stop: () => void;
+} {
+  ensureInterceptorInstalled(handleStore);
+
+  const capture: HandleCapture = { data: {} };
+  const captures = activeCapturesMap.get(handleStore)!;
+  captures.add(capture);
+
+  return {
+    capture,
+    stop() {
+      captures.delete(capture);
+    },
+  };
+}

package/src/cache/handle-snapshot.ts

@@ -0,0 +1,41 @@
+/**
+ * Handle Snapshot
+ *
+ * Capture and restore handle data for cached segments.
+ * Handle data (breadcrumbs, metadata from ctx.use(Handle)) is collected
+ * during segment resolution and stored alongside cached segments.
+ */
+
+import type { ResolvedSegment } from "../types.js";
+import type { HandleStore } from "../server/handle-store.js";
+import type { SegmentHandleData } from "./types.js";
+
+/**
+ * Capture handle data for a set of segments from the handle store.
+ * Used when caching segments to preserve their handle data.
+ */
+export function captureHandles(
+  segments: ResolvedSegment[],
+  handleStore: HandleStore,
+): Record<string, SegmentHandleData> {
+  const handles: Record<string, SegmentHandleData> = {};
+  for (const seg of segments) {
+    handles[seg.id] = handleStore.getDataForSegment(seg.id);
+  }
+  return handles;
+}
+
+/**
+ * Restore handle data from a cached snapshot into the handle store.
+ * Used when serving cached segments to replay their handle data.
+ */
+export function restoreHandles(
+  handles: Record<string, SegmentHandleData>,
+  handleStore: HandleStore,
+): void {
+  for (const [segId, segHandles] of Object.entries(handles)) {
+    if (Object.keys(segHandles).length > 0) {
+      handleStore.replaySegmentData(segId, segHandles);
+    }
+  }
+}

package/src/cache/index.ts

@@ -10,21 +10,6 @@
  * - CacheScope / createCacheScope - Request-scoped cache provider
  */
 
-// Generic cache store types (reserved for future extensibility)
-// These types support caching arbitrary values like Response, Stream, etc.
-// Currently unused - segment caching uses SegmentCacheStore directly.
-export type {
-  CacheStore,
-  CacheEntry,
-  CacheValue,
-  CacheValueType,
-  CachePutOptions,
-  CacheMetadata,
-} from "./types.js";
-
-// Generic memory cache (reserved for future extensibility)
-export { MemoryCacheStore } from "./memory-store.js";
-
 // Segment cache store types and implementations
 export type {
   SegmentCacheStore,
@@ -44,6 +29,7 @@ export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
+  type KVNamespace,
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
 } from "./cf/index.js";

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

@@ -5,15 +5,83 @@
  * Uses globalThis to survive HMR in development.
  */
 
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult } from "./types.js";
+import type {
+  SegmentCacheStore,
+  CachedEntryData,
+  CacheDefaults,
+  CacheGetResult,
+  CacheItemResult,
+  CacheItemOptions,
+  SegmentHandleData,
+} from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import {
+  resolveTtl,
+  resolveSwrWindow,
+  computeExpiration,
+  DEFAULT_FUNCTION_TTL,
+} from "./cache-policy.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__";
+
+/**
+ * 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?: Record<string, SegmentHandleData>;
+  expiresAt: number;
+  staleAt: number;
+}
 
 /**
  * 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.
+   *
+   * @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 +103,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>;
 }
 
@@ -69,19 +137,40 @@ 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>;
   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) {
+      // 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,
+      );
+      this.responseCache = getNamedMap<CachedResponseEntry>(
+        RESPONSE_CACHE_REGISTRY_KEY,
+        options.name,
+      );
+      this.itemCache = getNamedMap<CachedItemEntry>(
+        ITEM_CACHE_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.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
   }
@@ -103,7 +192,12 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
     return { data: cached, shouldRevalidate: false };
   }
 
-  async set(key: string, data: CachedEntryData, ttl: number, _swr?: number): Promise<void> {
+  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
     const entry: CachedEntryData = {
@@ -119,6 +213,88 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
 
   async clear(): Promise<void> {
     this.cache.clear();
+    this.responseCache.clear();
+    this.itemCache.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.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,
+  ): Promise<void> {
+    const body = await response.clone().arrayBuffer();
+    const headers: [string, string][] = [];
+    response.headers.forEach((value, name) => {
+      headers.push([name, value]);
+    });
+
+    const swrWindow = resolveSwrWindow(swr, this.defaults);
+    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+
+    this.responseCache.set(key, {
+      body,
+      status: response.status,
+      headers,
+      expiresAt,
+      staleAt,
+    });
+  }
+
+  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.itemCache.delete(key);
+      return null;
+    }
+
+    const isStale = now > cached.staleAt;
+    return {
+      value: cached.value,
+      handles: cached.handles,
+      shouldRevalidate: isStale,
+    };
+  }
+
+  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);
+    this.itemCache.set(key, {
+      value,
+      handles: options?.handles,
+      expiresAt,
+      staleAt,
+    });
   }
 
   /**
@@ -133,7 +309,7 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
   }
 
   /**
-   * Reset the global cache state.
+   * Reset the global cache registry.
    * Useful for test isolation - call this in beforeEach to ensure
    * tests don't share cache state via globalThis.
    *
@@ -145,6 +321,8 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
    * ```
    */
   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];
   }
 }