@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/cache/cache-key-utils.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared Cache Key Utilities
+ *
+ * Deterministic normalization of search params and route params
+ * for cache key generation. Used by cache-runtime, cache-scope,
+ * document-cache, and loader-cache.
+ */
+
+/**
+ * Build a sorted, deterministic query string from URLSearchParams,
+ * excluding internal _rsc* and __* params.
+ *
+ * Returns empty string when no user-facing params exist.
+ */
+export function sortedSearchString(searchParams: URLSearchParams): string {
+  const pairs: [string, string][] = [];
+  for (const [k, v] of searchParams) {
+    if (!k.startsWith("_rsc") && !k.startsWith("__")) {
+      pairs.push([k, v]);
+    }
+  }
+  if (pairs.length === 0) return "";
+  pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return pairs
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}
+
+/**
+ * Build a sorted, deterministic string from route params.
+ *
+ * Returns empty string when params is empty or undefined.
+ */
+export function sortedRouteParams(
+  params: Record<string, string> | undefined,
+): string {
+  if (!params) return "";
+  const entries = Object.entries(params);
+  if (entries.length === 0) return "";
+  return entries
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}

package/src/cache/cache-policy.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared Cache Policy Utilities
+ *
+ * Resolution cascades for TTL, SWR, cache key, and cache store.
+ * Consolidates the multi-tier resolution pattern:
+ *   explicit option → store defaults → fallback constant
+ */
+
+import type { CacheDefaults, SegmentCacheStore } from "./types.js";
+import { _getRequestContext } from "../server/request-context.js";
+import type { RequestContext } from "../server/request-context.js";
+
+/**
+ * Default TTL for route-level cache() DSL and loader cache.
+ * Applied when neither the cache options nor the store defaults specify a TTL.
+ */
+export const DEFAULT_ROUTE_TTL = 60;
+
+/**
+ * Default TTL for function-level "use cache" (setItem).
+ * Applied when neither the item options nor the store defaults specify a TTL.
+ */
+export const DEFAULT_FUNCTION_TTL = 900;
+
+/**
+ * Resolve effective TTL from the 3-tier cascade:
+ * explicit → store defaults → fallback.
+ */
+export function resolveTtl(
+  explicit: number | undefined,
+  defaults: CacheDefaults | undefined,
+  fallback: number,
+): number {
+  if (explicit !== undefined) return explicit;
+  if (defaults?.ttl !== undefined) return defaults.ttl;
+  return fallback;
+}
+
+/**
+ * Resolve effective SWR window from the 2-tier cascade:
+ * explicit → store defaults.
+ * Returns 0 when unset (no SWR window).
+ */
+export function resolveSwrWindow(
+  explicit: number | undefined,
+  defaults: CacheDefaults | undefined,
+): number {
+  if (explicit !== undefined) return explicit;
+  if (defaults?.swr !== undefined) return defaults.swr;
+  return 0;
+}
+
+/**
+ * Compute staleAt and expiresAt timestamps from TTL and SWR window.
+ *
+ * - staleAt: when the entry becomes stale (TTL boundary)
+ * - expiresAt: when the entry should be evicted (TTL + SWR)
+ *
+ * When swrWindow is 0, staleAt === expiresAt (no SWR).
+ */
+export function computeExpiration(
+  ttlSeconds: number,
+  swrSeconds: number = 0,
+): { staleAt: number; expiresAt: number } {
+  const now = Date.now();
+  const staleAt = now + ttlSeconds * 1000;
+  const expiresAt = staleAt + swrSeconds * 1000;
+  return { staleAt, expiresAt };
+}
+
+// ============================================================================
+// Cache Key Resolution
+// ============================================================================
+
+/**
+ * Resolve cache key using the 3-tier priority:
+ * 1. keyFn (full override from route/loader cache options)
+ * 2. store.keyGenerator (modifies default key)
+ * 3. defaultKey (used when neither keyFn nor keyGenerator is provided)
+ *
+ * Errors from keyFn and store.keyGenerator propagate to the caller.
+ * Cache identity is correctness-critical: if explicit key logic throws,
+ * silently remapping to a different key could cause cache collisions or
+ * serve stale/wrong data. Callers must handle the error or let it surface.
+ *
+ * Uses _getRequestContext (non-throwing) so that calls outside ALS
+ * (e.g. build-time) gracefully fall back to defaultKey.
+ */
+export async function resolveCacheKey(
+  keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
+  store: SegmentCacheStore | null,
+  defaultKey: string,
+  _label: string,
+): Promise<string> {
+  const requestCtx = _getRequestContext();
+
+  // Priority 1: Route/loader-level key function (full override)
+  if (keyFn && requestCtx) {
+    return await keyFn(requestCtx);
+  }
+
+  // Priority 2: Store-level keyGenerator (modifies default key)
+  if (store?.keyGenerator && requestCtx) {
+    return await store.keyGenerator(requestCtx, defaultKey);
+  }
+
+  // Priority 3: Default key (no custom key logic provided)
+  return defaultKey;
+}
+
+// ============================================================================
+// Cache Store Resolution
+// ============================================================================
+
+/**
+ * Resolve cache store from the 2-tier priority:
+ * 1. Explicit store from cache options
+ * 2. App-level store from request context
+ */
+export function resolveCacheStore(
+  explicitStore: SegmentCacheStore | undefined,
+): SegmentCacheStore | null {
+  if (explicitStore) return explicitStore;
+  return _getRequestContext()?._cacheStore ?? null;
+}

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,79 @@ 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 only — not requestCtx. The args stamp guards
+          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
+          // which is sufficient for correctness.
+          //
+          // We intentionally skip stamping requestCtx here because:
+          // 1. runBackground starts the async task synchronously (before the
+          //    first await), so stampCacheExec would pollute the shared
+          //    requestCtx while the foreground pipeline is still running.
+          //    This causes assertNotInsideCacheExec to fire when cache-store
+          //    later calls requestCtx.onResponse().
+          // 2. requestCtx methods are closure-bound to the original ctx, so
+          //    neither Object.create() nor a proxy can isolate the stamp.
+          // 3. The foreground miss path already stamps requestCtx and catches
+          //    cookies()/headers() misuse on first execution. The background
+          //    re-runs the same function with the same request.
+          const bgTaintedArgs: unknown[] = [];
+          for (const arg of args) {
+            if (isTainted(arg)) {
+              stampCacheExec(arg as object);
+              bgTaintedArgs.push(arg);
             }
-          });
-        }
+          }
+
+          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);
+            }
+            // Restore original handle store
+            if (originalHandleStore && requestCtx) {
+              requestCtx._handleStore = originalHandleStore;
+            }
+          }
+        });
         return result;
       } catch {
         // Deserialization of stale value failed, fall through
@@ -229,41 +271,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 +324,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;
   };