@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/cache/cache-scope.ts

@@ -12,24 +12,18 @@ import type { PartialCacheOptions } from "../types.js";
 import type { ResolvedSegment } from "../types.js";
 import type { SegmentCacheStore, CachedEntryData } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  getRequestContext,
+  _getRequestContext,
+} from "../server/request-context.js";
 import { serializeSegments, deserializeSegments } from "./segment-codec.js";
 import { captureHandles, restoreHandles } from "./handle-snapshot.js";
-
-// Re-export codec functions for backwards compatibility.
-// Existing call sites import these from cache-scope.ts via dynamic import.
-export {
-  deserializeComponent,
-  serializeSegments,
-  deserializeSegments,
-} from "./segment-codec.js";
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Default TTL when no explicit value or store defaults are configured */
-const DEFAULT_TTL_SECONDS = 60;
+import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
+import {
+  DEFAULT_ROUTE_TTL,
+  resolveCacheKey,
+  resolveCacheStore,
+} from "./cache-policy.js";
 
 function debugCacheLog(message: string): void {
   if (INTERNAL_RANGO_DEBUG) {
@@ -42,27 +36,31 @@ function debugCacheLog(message: string): void {
 // ============================================================================
 
 /**
- * Generate cache key base from pathname and params.
- * Params are sorted alphabetically for consistent key generation.
+ * Generate cache key base from host, pathname, route params, and search params.
+ * Host is included to prevent cross-host cache collisions on shared stores.
+ * Route params and search params are sorted alphabetically for deterministic keys.
+ * Internal _rsc* and __* query params are excluded.
  * @internal
  */
 function getCacheKeyBase(
+  host: string,
   pathname: string,
   params?: Record<string, string>,
+  searchParams?: URLSearchParams,
 ): string {
-  const paramStr = params
-    ? Object.entries(params)
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-        .join("&")
-    : "";
-
-  return paramStr ? `${pathname}:${paramStr}` : pathname;
+  const paramStr = sortedRouteParams(params);
+  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
+
+  let key = `${host}${pathname}`;
+  if (paramStr) key += `:${paramStr}`;
+  if (searchStr) key += `?${searchStr}`;
+  return key;
 }
 
 /**
  * Generate default cache key for a route request.
- * Single cache entry per route - uses pathname as the key.
+ * Includes pathname, route params, and user-facing search params for
+ * correct scoping. Internal _rsc* params are excluded.
  * Includes request type prefix since they produce different segment sets:
  * - doc: document requests (full page load)
  * - partial: navigation requests (client-side navigation)
@@ -76,11 +74,13 @@ function getDefaultRouteCacheKey(
 ): string {
   const ctx = getRequestContext();
   const isPartial = ctx?.url.searchParams.has("_rsc_partial") ?? false;
+  const searchParams = ctx?.url.searchParams;
+  const host = ctx?.url.host ?? "localhost";
 
   // Intercept navigations get their own cache namespace
   const prefix = isIntercept ? "intercept" : isPartial ? "partial" : "doc";
 
-  return `${prefix}:${getCacheKeyBase(pathname, params)}`;
+  return `${prefix}:${getCacheKeyBase(host, pathname, params, searchParams)}`;
 }
 
 // ============================================================================
@@ -145,7 +145,7 @@ export class CacheScope {
     }
 
     // Hardcoded fallback
-    return DEFAULT_TTL_SECONDS;
+    return DEFAULT_ROUTE_TTL;
   }
 
   /**
@@ -170,23 +170,11 @@ export class CacheScope {
    * 2. App-level store from request context
    */
   getStore(): SegmentCacheStore | null {
-    // Explicit store from cache() options takes precedence
-    if (this.explicitStore) {
-      return this.explicitStore;
-    }
-    // Fall back to app-level store from request context
-    const ctx = getRequestContext();
-    return ctx?._cacheStore ?? null;
+    return resolveCacheStore(this.explicitStore);
   }
 
   /**
-   * Resolve the cache key using custom key functions or default generation.
-   *
-   * Resolution priority:
-   * 1. Route-level `key` function (full override)
-   * 2. Store-level `keyGenerator` (modifies default key)
-   * 3. Default key generation (prefix:pathname:params)
-   *
+   * Resolve the cache key using the shared 3-tier priority.
    * @internal
    */
   private async resolveKey(
@@ -194,46 +182,9 @@ export class CacheScope {
     params: Record<string, string>,
     isIntercept?: boolean,
   ): Promise<string> {
-    const requestCtx = getRequestContext();
-    if (!requestCtx) {
-      // Fallback to default key if no request context
-      return getDefaultRouteCacheKey(pathname, params, isIntercept);
-    }
-
-    // Priority 1: Route-level key function (full override)
-    if (this.config !== false && this.config.key) {
-      try {
-        const customKey = await this.config.key(requestCtx);
-        return customKey;
-      } catch (error) {
-        console.error(
-          `[CacheScope] Custom key function failed, using default:`,
-          error,
-        );
-        return getDefaultRouteCacheKey(pathname, params, isIntercept);
-      }
-    }
-
-    // Generate default key
     const defaultKey = getDefaultRouteCacheKey(pathname, params, isIntercept);
-
-    // Priority 2: Store-level keyGenerator (modifies default key)
-    const store = this.getStore();
-    if (store?.keyGenerator) {
-      try {
-        const modifiedKey = await store.keyGenerator(requestCtx, defaultKey);
-        return modifiedKey;
-      } catch (error) {
-        console.error(
-          `[CacheScope] Store keyGenerator failed, using default:`,
-          error,
-        );
-        return defaultKey;
-      }
-    }
-
-    // Priority 3: Default key
-    return defaultKey;
+    const keyFn = this.config !== false ? this.config.key : undefined;
+    return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
 
   /**
@@ -254,6 +205,27 @@ export class CacheScope {
   } | null> {
     if (!this.enabled) return null;
 
+    // Evaluate condition — skip cache read when condition returns false
+    if (this.config !== false && this.config.condition) {
+      const requestCtx = getRequestContext();
+      if (requestCtx) {
+        try {
+          if (!this.config.condition(requestCtx)) {
+            debugCacheLog(
+              `[CacheScope] condition returned false, skipping cache read`,
+            );
+            return null;
+          }
+        } catch (error) {
+          console.error(
+            `[CacheScope] condition function threw, skipping cache read:`,
+            error,
+          );
+          return null;
+        }
+      }
+    }
+
     const store = this.getStore();
     if (!store) return null;
 
@@ -274,7 +246,7 @@ export class CacheScope {
       const segments = await deserializeSegments(cached.segments);
 
       // Replay handle data
-      const handleStore = getRequestContext()?._handleStore;
+      const handleStore = _getRequestContext()?._handleStore;
       if (handleStore) {
         restoreHandles(cached.handles, handleStore);
       }
@@ -313,6 +285,27 @@ export class CacheScope {
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
 
+    // Evaluate condition — skip cache write when condition returns false
+    if (this.config !== false && this.config.condition) {
+      const conditionCtx = getRequestContext();
+      if (conditionCtx) {
+        try {
+          if (!this.config.condition(conditionCtx)) {
+            debugCacheLog(
+              `[CacheScope] condition returned false, skipping cache write`,
+            );
+            return;
+          }
+        } catch (error) {
+          console.error(
+            `[CacheScope] condition function threw, skipping cache write:`,
+            error,
+          );
+          return;
+        }
+      }
+    }
+
     const store = this.getStore();
     if (!store) return;
 

package/src/cache/cf/cf-cache-store.ts

@@ -29,10 +29,15 @@ import type {
   CacheItemOptions,
 } from "../types.js";
 import {
-  getRequestContext,
+  _getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
 import { VERSION } from "@rangojs/router:version";
+import {
+  resolveTtl,
+  resolveSwrWindow,
+  DEFAULT_FUNCTION_TTL,
+} from "../cache-policy.js";
 
 // ============================================================================
 // Constants
@@ -126,7 +131,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * @example Using cookies for locale-aware caching
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
-   *   const locale = ctx.cookie('locale') || 'en';
+   *   const locale = cookies().get('locale')?.value || 'en';
    *   return `${locale}:${defaultKey}`;
    * }
    * ```
@@ -184,7 +189,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private deriveBaseUrl(): string {
     const fallback = "https://rsc-cache.internal.com/";
 
-    const ctx = getRequestContext();
+    const ctx = _getRequestContext();
     if (!ctx?.request) {
       return fallback;
     }
@@ -299,7 +304,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const request = this.keyToRequest(key);
 
       // Extended TTL covers SWR window
-      const swrWindow = swr ?? this.defaults?.swr ?? 0;
+      const swrWindow = resolveSwrWindow(swr, this.defaults);
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
 
@@ -389,7 +394,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const request = this.keyToRequest(`doc:${key}`);
 
       // Extended TTL covers SWR window
-      const swrWindow = swr ?? this.defaults?.swr ?? 0;
+      const swrWindow = resolveSwrWindow(swr, this.defaults);
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
 
@@ -490,8 +495,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const cache = await this.getCache();
       const request = this.keyToRequest(`fn:${key}`);
 
-      const ttl = options?.ttl ?? this.defaults?.ttl ?? 900;
-      const swrWindow = options?.swr ?? this.defaults?.swr ?? 0;
+      const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
+      const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
 

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;
 }
@@ -193,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();
@@ -229,18 +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);
 
@@ -248,15 +277,10 @@ 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
@@ -264,41 +288,33 @@ export function createDocumentCacheMiddleware<TEnv = any>(
           `[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);
+        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
@@ -309,24 +325,27 @@ export function createDocumentCacheMiddleware<TEnv = any>(
           `[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),
@@ -338,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/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,