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

package/src/cache/document-cache.ts

@@ -13,6 +13,9 @@
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { getRequestContext } 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";
 
 // ============================================================================
 // Constants
@@ -202,13 +205,24 @@ export function createDocumentCacheMiddleware<TEnv = any>(
   ): Promise<Response> {
     const url = ctx.url;
 
+    // Use the original request URL for _rsc* param detection and cache key
+    // differentiation. ctx.url is stripped of _rsc* params by the middleware
+    // pipeline (stripInternalParams), so _rsc_partial, _rsc_segments, etc.
+    // are not visible on ctx.url in production.
+    const rawUrl = new URL(ctx.request.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")) {
+    if (rawUrl.searchParams.has("_rsc_action")) {
       return next();
     }
 
     // Skip loader requests (have their own caching)
-    if (url.searchParams.has("_rsc_loader")) {
+    if (rawUrl.searchParams.has("_rsc_loader")) {
       return next();
     }
 
@@ -234,22 +248,38 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
-    // Determine request type for cache key differentiation
-    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}`;
+    // Determine request type for cache key differentiation.
+    // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
+    // detection. Full-document RSC fetches must not share the HTML cache slot.
+    const isPartial = rawUrl.searchParams.has("_rsc_partial");
+    const isRscRequest = !mayNeedSSR(ctx.request, rawUrl);
+    const typeLabel = isRscRequest ? "RSC" : "HTML";
+
+    // 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 = rawUrl.searchParams.get("_rsc_segments") || "";
+      const segmentHash =
+        isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
+      const typeSuffix = isRscRequest ? ":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);
 
@@ -268,28 +298,24 @@ 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);
+          }
+        });
 
         return drainOnResponseCallbacks(
           addCacheStatusHeader(cached.response, "STALE"),
@@ -298,6 +324,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       }
 
       // 2. Cache miss - run handler
+      handlerCalled = true;
       const originalResponse = await next();
 
       // 3. Cache if response has appropriate headers
@@ -308,24 +335,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),
@@ -337,7 +367,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

@@ -29,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

@@ -15,6 +15,12 @@ import type {
   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_REGISTRY_KEY = "__rsc_router_segment_cache_registry__";
 const RESPONSE_CACHE_REGISTRY_KEY = "__rsc_router_response_cache_registry__";
@@ -52,6 +58,7 @@ interface CachedItemEntry {
   value: string;
   handles?: Record<string, SegmentHandleData>;
   expiresAt: number;
+  staleAt: number;
 }
 
 /**
@@ -244,9 +251,8 @@ export class MemorySegmentCacheStore<
       headers.push([name, value]);
     });
 
-    const swrWindow = swr ?? this.defaults?.swr ?? 0;
-    const staleAt = Date.now() + ttl * 1000;
-    const expiresAt = staleAt + swrWindow * 1000;
+    const swrWindow = resolveSwrWindow(swr, this.defaults);
+    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
 
     this.responseCache.set(key, {
       body,
@@ -261,15 +267,17 @@ export class MemorySegmentCacheStore<
     const cached = this.itemCache.get(key);
     if (!cached) return null;
 
-    if (Date.now() > cached.expiresAt) {
+    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: false,
+      shouldRevalidate: isStale,
     };
   }
 
@@ -278,11 +286,14 @@ export class MemorySegmentCacheStore<
     value: string,
     options?: CacheItemOptions,
   ): Promise<void> {
-    const ttl = options?.ttl ?? this.defaults?.ttl ?? 900;
+    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: Date.now() + ttl * 1000,
+      expiresAt,
+      staleAt,
     });
   }
 

package/src/cache/profile-registry.ts

@@ -15,23 +15,58 @@ export interface CacheProfile {
   tags?: string[];
 }
 
+const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
+
 let _profiles: Record<string, CacheProfile> = {
-  default: { ttl: 900, swr: 1800 },
+  default: DEFAULT_PROFILE,
 };
 
+const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
 /**
- * Set all cache profiles. Called by createRouter() at startup.
+ * Validate and merge user profiles with the default profile.
+ * Returns a new object suitable for both DSL-time and request-scoped use.
+ *
+ * Used by createRouter() to compute the resolved profile map once,
+ * stored on the router instance and passed to every request context.
  */
-export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
-  _profiles = { ...profiles };
-  // Ensure a default profile always exists
-  if (!_profiles.default) {
-    _profiles.default = { ttl: 900, swr: 1800 };
+export function resolveCacheProfiles(
+  profiles?: Record<string, CacheProfile>,
+): Record<string, CacheProfile> {
+  const merged: Record<string, CacheProfile> = {
+    default: DEFAULT_PROFILE,
+  };
+  if (profiles) {
+    for (const name of Object.keys(profiles)) {
+      if (!PROFILE_NAME_RE.test(name)) {
+        throw new Error(
+          `Invalid cache profile name "${name}". ` +
+            `Profile names must match [a-zA-Z0-9_-]+.`,
+        );
+      }
+      merged[name] = profiles[name];
+    }
   }
+  return merged;
+}
+
+/**
+ * Set all cache profiles in the global registry.
+ * Called by createRouter() at startup for DSL-time resolution
+ * (cache("profileName") reads from this during route definition).
+ *
+ * WARNING: This is global mutable state. It exists only for DSL-time
+ * reads. Runtime resolution (registerCachedFunction) uses request-scoped
+ * profiles and does NOT read from this registry.
+ */
+export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
+  _profiles = resolveCacheProfiles(profiles);
 }
 
 /**
- * Get a cache profile by name. Returns undefined for unknown profiles.
+ * Get a cache profile by name from the global registry.
+ * Used only at DSL-time (cache("profileName") inside urls() evaluation).
+ * Runtime code uses request-scoped profiles instead.
  */
 export function getCacheProfile(name: string): CacheProfile | undefined {
   return _profiles[name];

package/src/cache/read-through-swr.ts

@@ -0,0 +1,134 @@
+/**
+ * SWR Read-Through Engine
+ *
+ * Generic read-through cache with stale-while-revalidate support
+ * for item-level caching (getItem/setItem).
+ *
+ * Flow:
+ * 1. Lookup cached item by key
+ * 2. Fresh hit → deserialize, return
+ * 3. Stale hit → deserialize, return, revalidate in background
+ * 4. Miss → execute, cache write (blocking when no waitUntil), return
+ */
+
+import type { CacheItemResult, CacheItemOptions } from "./types.js";
+import { runBackground } from "./background-task.js";
+
+interface WaitUntilHost {
+  waitUntil?: (fn: () => Promise<void>) => void;
+}
+
+export interface ReadThroughItemConfig<T> {
+  /** Retrieve a cached item by key */
+  getItem: (key: string) => Promise<CacheItemResult | null>;
+  /** Store a serialized item by key */
+  setItem: (
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ) => Promise<void>;
+  /** Cache key */
+  key: string;
+  /** Execute the underlying function/loader on miss or revalidation */
+  execute: () => Promise<T>;
+  /** Serialize result for storage. Return null to skip caching. */
+  serialize: (data: T) => Promise<string | null>;
+  /** Deserialize cached value back to the original type */
+  deserialize: (value: string) => Promise<T>;
+  /** Options passed to setItem on cache write */
+  storeOptions: CacheItemOptions;
+  /** Called on fresh cache hit (before returning data) */
+  onHit?: (cached: CacheItemResult) => void;
+  /** Called on stale cache hit (before scheduling background revalidation) */
+  onStale?: (cached: CacheItemResult) => void;
+  /** Called on cache miss (before executing) */
+  onMiss?: () => void;
+  /** Called after successful cache write */
+  onCached?: () => void;
+  /** Host with optional waitUntil for background tasks */
+  host?: WaitUntilHost | null;
+}
+
+/**
+ * Read-through cache with SWR support for item-level caching.
+ *
+ * On fresh hit: returns deserialized cached data.
+ * On stale hit: returns stale data, schedules background revalidation.
+ * On miss: executes, writes to cache (blocking when no waitUntil), returns.
+ */
+export async function readThroughItem<T>(
+  config: ReadThroughItemConfig<T>,
+): Promise<T> {
+  const {
+    getItem,
+    setItem,
+    key,
+    execute,
+    serialize,
+    deserialize,
+    storeOptions,
+    onHit,
+    onStale,
+    onMiss,
+    onCached,
+    host,
+  } = config;
+
+  // Cache lookup
+  try {
+    const cached = await getItem(key);
+
+    if (cached) {
+      const data = await deserialize(cached.value);
+
+      if (!cached.shouldRevalidate) {
+        onHit?.(cached);
+        return data;
+      }
+
+      // Stale hit — return stale data, revalidate in background
+      onStale?.(cached);
+      runBackground(
+        host,
+        async () => {
+          try {
+            const fresh = await execute();
+            const serialized = await serialize(fresh);
+            if (serialized !== null) {
+              await setItem(key, serialized, storeOptions);
+            }
+          } catch {
+            // Background revalidation failed silently
+          }
+        },
+        true,
+      );
+      return data;
+    }
+  } catch {
+    // Cache lookup failed, fall through to fresh execution
+  }
+
+  // Cache miss
+  onMiss?.();
+  const data = await execute();
+
+  // Non-blocking cache write (blocks when no waitUntil)
+  await runBackground(
+    host,
+    async () => {
+      try {
+        const serialized = await serialize(data);
+        if (serialized !== null) {
+          await setItem(key, serialized, storeOptions);
+          onCached?.();
+        }
+      } catch {
+        // Cache write failed silently
+      }
+    },
+    true,
+  );
+
+  return data;
+}