@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/cache/cache-runtime.ts

@@ -17,7 +17,6 @@
 /// <reference types="@vitejs/plugin-rsc/types" />
 
 import {
-  createTemporaryReferenceSet,
   encodeReply,
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
@@ -26,19 +25,17 @@ import {
   isTainted,
   CACHED_FN_SYMBOL,
   isCachedFunction,
-  INSIDE_CACHE_EXEC,
+  stampCacheExec,
+  unstampCacheExec,
 } from "./taint.js";
 
 export { isCachedFunction };
-import { getCacheProfile } from "./profile-registry.js";
 import { serializeResult, deserializeResult } from "./segment-codec.js";
-import type { SegmentHandleData } from "./types.js";
-import type { HandleStore } from "../server/handle-store.js";
+import { createHandleStore } from "../server/handle-store.js";
 import { restoreHandles } from "./handle-snapshot.js";
-
-// ============================================================================
-// Cache Key Generation
-// ============================================================================
+import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
+import { sortedSearchString } from "./cache-key-utils.js";
+import { runBackground } from "./background-task.js";
 
 /**
  * Convert encodeReply result to a stable string key.
@@ -51,47 +48,6 @@ async function replyToCacheKey(encoded: string | FormData): Promise<string> {
   return text;
 }
 
-// ============================================================================
-// Handle Capture
-// ============================================================================
-
-interface HandleCapture {
-  data: Record<string, SegmentHandleData>;
-}
-
-function startHandleCapture(handleStore: HandleStore): HandleCapture {
-  const capture: HandleCapture = { data: {} };
-  const originalPush = handleStore.push.bind(handleStore);
-
-  // Intercept push() calls to record them
-  handleStore.push = (
-    handleName: string,
-    segmentId: string,
-    value: unknown,
-  ) => {
-    if (!capture.data[segmentId]) {
-      capture.data[segmentId] = {};
-    }
-    if (!capture.data[segmentId][handleName]) {
-      capture.data[segmentId][handleName] = [];
-    }
-    capture.data[segmentId][handleName].push(value);
-    // Still call the original so the data flows through normally
-    originalPush(handleName, segmentId, value);
-  };
-
-  return capture;
-}
-
-function stopHandleCapture(
-  handleStore: HandleStore,
-  _capture: HandleCapture,
-): void {
-  // Restore original push by deleting the override
-  // (the original is on the prototype/closure, our override is an own property)
-  delete (handleStore as any).push;
-}
-
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -112,17 +68,30 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
   const wrapped = async function (this: any, ...args: any[]): Promise<any> {
     const requestCtx = getRequestContext();
     const store = requestCtx?._cacheStore;
-    const profile = getCacheProfile(profileName || "default");
+    const resolvedProfileName = profileName || "default";
 
-    // Bypass: no store, no getItem support, or no profile configured
-    if (!store?.getItem || !profile) {
+    // Bypass: no store or no getItem support
+    if (!store?.getItem) {
       return fn.apply(this, args);
     }
 
+    // Resolve profile strictly from request-scoped config (set by the
+    // active router via createRequestContext). No global fallback —
+    // global profile state is only for DSL-time cache("profileName").
+    const profile = requestCtx?._cacheProfiles?.[resolvedProfileName];
+
+    if (!profile) {
+      throw new Error(
+        `[use cache] "${id}" uses unknown cache profile "${resolvedProfileName}". ` +
+          `Define it in createRouter({ cacheProfiles: { "${resolvedProfileName}": { ttl: ... } } }).`,
+      );
+    }
+
     // Separate tainted args (ctx, env, req) from key-generating args.
-    // For tainted objects that carry route context (params, pathname),
-    // extract those serializable values into the key so different routes
-    // and param combinations produce distinct cache entries.
+    // For tainted objects that carry route context (params, pathname,
+    // searchParams), extract serializable values into the key so
+    // different routes, param combinations, and query variants produce
+    // distinct cache entries.
     const keyArgs: unknown[] = [];
     let hasTaintedArgs = false;
     for (const arg of args) {
@@ -130,10 +99,28 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         hasTaintedArgs = true;
         const ctx = arg as any;
         if (ctx.params && typeof ctx.params === "object") {
+          // Include host to prevent cross-host cache collisions (same
+          // pattern as route-level cache-scope.ts key generation).
+          if (ctx.url?.host) {
+            keyArgs.push(ctx.url.host);
+          }
+          // Include route name to prevent collisions when the same cached
+          // function is reused across routes with identical pathname/params
+          // but different local reverse() scope.
+          if (ctx._routeName) {
+            keyArgs.push(ctx._routeName);
+          }
           keyArgs.push(ctx.pathname, ctx.params);
           if (ctx._responseType) {
             keyArgs.push(ctx._responseType);
           }
+          // Include user-facing search params (exclude internal _rsc*/__ params)
+          if (ctx.searchParams instanceof URLSearchParams) {
+            const normalized = sortedSearchString(ctx.searchParams);
+            if (normalized) {
+              keyArgs.push(normalized);
+            }
+          }
         }
       } else {
         keyArgs.push(arg);
@@ -202,24 +189,75 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             restoreHandles(cached.handles, handleStore);
           }
         }
-        // Background revalidation
-        if (requestCtx?.waitUntil) {
-          requestCtx.waitUntil(async () => {
-            try {
-              const freshResult = await fn.apply(this, args);
-              const serialized = await serializeResult(freshResult);
-              if (serialized !== null) {
-                await store.setItem!(cacheKey, serialized, {
-                  ttl: profile.ttl,
-                  swr: profile.swr,
-                  tags: profile.tags,
-                });
-              }
-            } catch {
-              // Background revalidation failed silently
+        // Background revalidation — must capture handles if tainted args present.
+        // Use an isolated handle store so background pushes don't pollute the
+        // live response or throw LateHandlePushError on the completed store.
+        // Same isolation pattern as route-level background-revalidation.ts.
+        runBackground(requestCtx, async () => {
+          // Reuse closure-captured requestCtx instead of calling
+          // getRequestContext() — ALS context may be gone inside waitUntil.
+          let originalHandleStore:
+            | ReturnType<typeof createHandleStore>
+            | undefined;
+          if (hasTaintedArgs && requestCtx) {
+            originalHandleStore = requestCtx._handleStore;
+            requestCtx._handleStore = createHandleStore();
+          }
+          const bgHandleStore = hasTaintedArgs
+            ? requestCtx?._handleStore
+            : undefined;
+          let bgCapture: HandleCapture | undefined;
+          let bgStopCapture: (() => void) | undefined;
+          if (bgHandleStore) {
+            const c = startHandleCapture(bgHandleStore);
+            bgCapture = c.capture;
+            bgStopCapture = c.stop;
+          }
+
+          // Stamp tainted args and RequestContext so request-scoped
+          // reads (cookies, headers) and side effects (ctx.set, etc.)
+          // throw inside background revalidation, same as the miss path.
+          // Uses ref-counted stamp/unstamp so overlapping executions
+          // sharing the same ctx don't clear each other's guards.
+          const bgTaintedArgs: unknown[] = [];
+          for (const arg of args) {
+            if (isTainted(arg)) {
+              stampCacheExec(arg as object);
+              bgTaintedArgs.push(arg);
             }
-          });
-        }
+          }
+          if (requestCtx) {
+            stampCacheExec(requestCtx as object);
+          }
+
+          try {
+            const freshResult = await fn.apply(this, args);
+            bgStopCapture?.();
+            const serialized = await serializeResult(freshResult);
+            if (serialized !== null) {
+              await store.setItem!(cacheKey, serialized, {
+                handles: bgCapture?.data,
+                ttl: profile.ttl,
+                swr: profile.swr,
+                tags: profile.tags,
+              });
+            }
+          } catch (bgError) {
+            bgStopCapture?.();
+            requestCtx?._reportBackgroundError?.(bgError, "stale-revalidation");
+          } finally {
+            for (const arg of bgTaintedArgs) {
+              unstampCacheExec(arg as object);
+            }
+            if (requestCtx) {
+              unstampCacheExec(requestCtx as object);
+            }
+            // Restore original handle store
+            if (originalHandleStore && requestCtx) {
+              requestCtx._handleStore = originalHandleStore;
+            }
+          }
+        });
         return result;
       } catch {
         // Deserialization of stale value failed, fall through
@@ -229,41 +267,44 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Cache miss: execute, serialize, store
     const handleStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
     let capture: HandleCapture | undefined;
+    let stopCapture: (() => void) | undefined;
     if (handleStore && hasTaintedArgs) {
-      capture = startHandleCapture(handleStore);
+      const c = startHandleCapture(handleStore);
+      capture = c.capture;
+      stopCapture = c.stop;
     }
 
     // Stamp tainted args so ctx.set(), ctx.header(), etc. throw if called
     // inside the cached function body (those side effects are lost on hit).
-    // Also stamp the ALS RequestContext so cookies()/headers() guards fire
-    // (they read from getRequestContext(), which is a different object from
-    // the HandlerContext/ResponseHandlerContext passed as args).
+    // Uses ref-counted stamp/unstamp so overlapping executions
+    // sharing the same ctx don't clear each other's guards.
     const taintedArgs: unknown[] = [];
     for (const arg of args) {
       if (isTainted(arg)) {
-        (arg as any)[INSIDE_CACHE_EXEC] = true;
+        stampCacheExec(arg as object);
         taintedArgs.push(arg);
       }
     }
-    if (hasTaintedArgs && requestCtx) {
-      (requestCtx as any)[INSIDE_CACHE_EXEC] = true;
+    // Always stamp the ALS RequestContext so cookies()/headers() guards fire
+    // even when the cached function receives no tainted args. The guard in
+    // cookie-store.ts checks RequestContext, not function args.
+    if (requestCtx) {
+      stampCacheExec(requestCtx as object);
     }
 
     let result: any;
     try {
       result = await fn.apply(this, args);
     } finally {
-      // Always remove the flag, even if the function throws
+      // Decrement ref count; symbol is deleted when it reaches zero
       for (const arg of taintedArgs) {
-        delete (arg as any)[INSIDE_CACHE_EXEC];
+        unstampCacheExec(arg as object);
       }
-      if (hasTaintedArgs && requestCtx) {
-        delete (requestCtx as any)[INSIDE_CACHE_EXEC];
+      if (requestCtx) {
+        unstampCacheExec(requestCtx as object);
       }
-    }
-
-    if (capture && handleStore) {
-      stopHandleCapture(handleStore, capture);
+      // Remove this capture token (order-independent, safe for concurrent use)
+      stopCapture?.();
     }
 
     // Serialize and store — fully non-blocking when waitUntil is available.
@@ -279,17 +320,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             tags: profile.tags,
           });
         }
-      } catch {
-        // Serialization or store write failed silently
+      } catch (writeError) {
+        requestCtx?._reportBackgroundError?.(writeError, "cache-write");
       }
     };
 
-    if (requestCtx?.waitUntil) {
-      requestCtx.waitUntil(cacheWrite);
-    } else {
-      // No waitUntil (e.g. Node.js dev server): run inline as best-effort
-      await cacheWrite();
-    }
+    await runBackground(requestCtx, cacheWrite, true);
 
     return result;
   };

package/src/cache/cache-scope.ts

@@ -18,13 +18,12 @@ import {
 } from "../server/request-context.js";
 import { serializeSegments, deserializeSegments } from "./segment-codec.js";
 import { captureHandles, restoreHandles } from "./handle-snapshot.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) {
@@ -37,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)
@@ -71,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)}`;
 }
 
 // ============================================================================
@@ -140,7 +145,7 @@ export class CacheScope {
     }
 
     // Hardcoded fallback
-    return DEFAULT_TTL_SECONDS;
+    return DEFAULT_ROUTE_TTL;
   }
 
   /**
@@ -165,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(
@@ -189,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");
   }
 
   /**
@@ -249,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;
 
@@ -308,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

@@ -33,6 +33,11 @@ import {
   type RequestContext,
 } from "../../server/request-context.js";
 import { VERSION } from "@rangojs/router:version";
+import {
+  resolveTtl,
+  resolveSwrWindow,
+  DEFAULT_FUNCTION_TTL,
+} from "../cache-policy.js";
 
 // ============================================================================
 // Constants
@@ -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;