@rangojs/router 0.0.0-experimental.2

package/src/cache/document-cache.ts

@@ -0,0 +1,340 @@
+/**
+ * Document-Level Cache Middleware
+ *
+ * Caches full HTTP responses at the edge based on Cache-Control headers.
+ * Routes opt-in to caching by setting s-maxage or stale-while-revalidate headers.
+ *
+ * Flow:
+ * 1. Check cache for existing response
+ * 2. If fresh hit → return cached response
+ * 3. If stale hit (within SWR window) → return cached, revalidate in background
+ * 4. If miss → run handler, cache if response has cache headers
+ */
+
+import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
+import { getRequestContext } from "../server/request-context.js";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Header indicating cache status for debugging */
+const CACHE_STATUS_HEADER = "x-document-cache-status";
+
+/**
+ * Simple hash function for segment IDs.
+ * Creates a short, deterministic hash to differentiate cache keys
+ * based on which segments the client already has.
+ */
+function hashSegmentIds(segmentIds: string): string {
+  if (!segmentIds) return "";
+
+  let hash = 0;
+  for (let i = 0; i < segmentIds.length; i++) {
+    const char = segmentIds.charCodeAt(i);
+    hash = ((hash << 5) - hash + char) | 0;
+  }
+  // Convert to base36 for shorter string, take absolute value
+  return Math.abs(hash).toString(36);
+}
+
+// ============================================================================
+// Cache Control Parsing
+// ============================================================================
+
+interface CacheDirectives {
+  sMaxAge?: number;
+  staleWhileRevalidate?: number;
+}
+
+/**
+ * Parse Cache-Control header for s-maxage and stale-while-revalidate directives
+ */
+function parseCacheControl(header: string | null): CacheDirectives | null {
+  if (!header) return null;
+
+  const directives: CacheDirectives = {};
+
+  // Parse s-maxage
+  const sMaxAgeMatch = header.match(/s-maxage\s*=\s*(\d+)/i);
+  if (sMaxAgeMatch) {
+    directives.sMaxAge = parseInt(sMaxAgeMatch[1], 10);
+  }
+
+  // Parse stale-while-revalidate
+  const swrMatch = header.match(/stale-while-revalidate\s*=\s*(\d+)/i);
+  if (swrMatch) {
+    directives.staleWhileRevalidate = parseInt(swrMatch[1], 10);
+  }
+
+  // Only return if we have at least s-maxage (required for document caching)
+  if (directives.sMaxAge !== undefined) {
+    return directives;
+  }
+
+  return null;
+}
+
+/**
+ * Check if response should be cached based on Cache-Control headers
+ */
+function shouldCacheResponse(response: Response): CacheDirectives | null {
+  // Only cache successful responses
+  if (response.status !== 200) {
+    return null;
+  }
+
+  const cacheControl = response.headers.get("Cache-Control");
+  return parseCacheControl(cacheControl);
+}
+
+// ============================================================================
+// Response Helpers
+// ============================================================================
+
+/**
+ * Add cache status header to response for debugging
+ */
+function addCacheStatusHeader(
+  response: Response,
+  status: "HIT" | "STALE" | "MISS",
+): Response {
+  const headers = new Headers(response.headers);
+  headers.set(CACHE_STATUS_HEADER, status);
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+/**
+ * Run onResponse callbacks registered on the request context
+ */
+function runOnResponseCallbacks(
+  response: Response,
+  callbacks: Array<(response: Response) => Response>,
+): Response {
+  let result = response;
+  for (const callback of callbacks) {
+    result = callback(result);
+  }
+  return result;
+}
+
+// ============================================================================
+// Document Cache Middleware
+// ============================================================================
+
+export interface DocumentCacheOptions<TEnv = any> {
+  /**
+   * Skip caching for specific paths (e.g., API routes)
+   */
+  skipPaths?: string[];
+
+  /**
+   * Custom cache key generator
+   */
+  keyGenerator?: (url: URL) => string;
+
+  /**
+   * Callback to determine if caching should be enabled for this request.
+   * Receives the middleware context and returns true to enable caching.
+   * If not provided, caching is enabled by default.
+   *
+   * @example
+   * ```typescript
+   * createDocumentCacheMiddleware({
+   *   isEnabled: (ctx) => !ctx.request.headers.has('x-skip-cache'),
+   * })
+   * ```
+   */
+  isEnabled?: (ctx: MiddlewareContext<TEnv>) => boolean | Promise<boolean>;
+
+  /**
+   * Enable debug logging for cache operations.
+   * Logs HIT, MISS, STALE, and REVALIDATED events.
+   * Defaults to false.
+   */
+  debug?: boolean;
+}
+
+/**
+ * Create document cache middleware
+ *
+ * Add this middleware to your router to enable document-level caching.
+ * It uses the cache store's getResponse/putResponse methods for caching.
+ * Routes opt-in by setting Cache-Control headers with s-maxage.
+ *
+ * @example
+ * ```typescript
+ * // Add middleware to router
+ * const router = createRouter<AppEnv>()
+ *   .use(createDocumentCacheMiddleware({
+ *     isEnabled: (ctx) => ctx.url.pathname !== '/admin',
+ *   }))
+ *   .route("home", (ctx) => {
+ *     ctx.headers.set("Cache-Control", "s-maxage=60, stale-while-revalidate=300");
+ *     return <HomePage />;
+ *   });
+ * ```
+ */
+export function createDocumentCacheMiddleware<TEnv = any>(
+  options: DocumentCacheOptions<TEnv> = {},
+): MiddlewareFn<TEnv> {
+  const { skipPaths = [], keyGenerator, isEnabled, debug = false } = options;
+
+  const log = debug
+    ? (message: string) => console.log(message)
+    : () => {};
+
+  return async function documentCacheMiddleware(
+    ctx: MiddlewareContext<TEnv>,
+    next: () => Promise<Response>,
+  ): Promise<Response> {
+    const url = ctx.url;
+
+    // Skip RSC action requests (mutations shouldn't be cached)
+    if (url.searchParams.has("_rsc_action")) {
+      return next();
+    }
+
+    // Skip loader requests (have their own caching)
+    if (url.searchParams.has("_rsc_loader")) {
+      return next();
+    }
+
+    // Skip configured paths
+    if (skipPaths.some((path) => url.pathname.startsWith(path))) {
+      return next();
+    }
+
+    // Check if caching is enabled for this request
+    if (isEnabled) {
+      const enabled = await isEnabled(ctx);
+      if (!enabled) {
+        return next();
+      }
+    }
+
+    // Get request context and cache store
+    const requestCtx = getRequestContext();
+    const store = requestCtx?._cacheStore;
+
+    // Skip if no cache store or store doesn't support response caching
+    if (!store?.getResponse || !store?.putResponse) {
+      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}`;
+
+    try {
+      // 1. Check cache
+      const cached = await store.getResponse(cacheKey);
+
+      if (cached && cached.response.status === 200) {
+        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;
+        }
+
+        // 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);
+            }
+          });
+        }
+
+        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;
+      }
+
+      // 2. Cache miss - run handler
+      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})`);
+
+        // Tee the body so we can return one stream and cache the other
+        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);
+            }
+          });
+        }
+
+        return addCacheStatusHeader(
+          new Response(returnStream, originalResponse),
+          "MISS",
+        );
+      }
+
+      // No cache headers - pass through
+      return originalResponse;
+    } catch (error) {
+      console.error(`[DocumentCache] Error:`, error);
+      // On any cache error, fall through to handler
+      return next();
+    }
+  };
+}

package/src/cache/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Cache Store
+ *
+ * Server-side caching for RSC segments and loader data.
+ *
+ * Main exports for users:
+ * - SegmentCacheStore - Interface for implementing custom cache stores
+ * - MemorySegmentCacheStore - In-memory cache for development/testing
+ * - CFCacheStore - Cloudflare edge cache store for production
+ * - 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,
+  SegmentCacheProvider,
+  CachedEntryData,
+  CachedEntryResult,
+  CacheGetResult,
+  SerializedSegmentData,
+  SegmentHandleData,
+  CacheConfig,
+  CacheConfigOrFactory,
+} from "./types.js";
+
+export { MemorySegmentCacheStore } from "./memory-segment-store.js";
+
+// Cloudflare cache store
+export {
+  CFCacheStore,
+  type CFCacheStoreOptions,
+  CACHE_STALE_AT_HEADER,
+  CACHE_STATUS_HEADER,
+} from "./cf/index.js";
+
+// Cache scope
+export { CacheScope, createCacheScope } from "./cache-scope.js";
+
+// Document-level cache middleware
+export {
+  createDocumentCacheMiddleware,
+  type DocumentCacheOptions,
+} from "./document-cache.js";

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

@@ -0,0 +1,150 @@
+/**
+ * In-Memory Segment Cache Store
+ *
+ * Simple in-memory implementation of SegmentCacheStore.
+ * Uses globalThis to survive HMR in development.
+ */
+
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult } from "./types.js";
+import type { RequestContext } from "../server/request-context.js";
+
+const CACHE_GLOBAL_KEY = "__rsc_router_segment_cache_store__";
+
+/**
+ * Options for MemorySegmentCacheStore
+ */
+export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
+  /**
+   * Default cache options for cache() boundaries.
+   * When cache() is called without explicit ttl/swr,
+   * these defaults are used.
+   *
+   * @example
+   * ```typescript
+   * const store = new MemorySegmentCacheStore({
+   *   defaults: { ttl: 60, swr: 300 }
+   * });
+   * ```
+   */
+  defaults?: CacheDefaults;
+
+  /**
+   * Custom key generator applied to all cache operations.
+   * Receives the full RequestContext and the default-generated key.
+   *
+   * @example
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const locale = ctx.cookie('locale') || 'en';
+   *   return `${locale}:${defaultKey}`;
+   * }
+   * ```
+   */
+  keyGenerator?: (
+    ctx: RequestContext<TEnv>,
+    defaultKey: string
+  ) => string | Promise<string>;
+}
+
+/**
+ * In-memory segment cache store.
+ *
+ * Suitable for development and single-instance deployments.
+ * For production with multiple instances, use a distributed store
+ * like Cloudflare KV or Redis.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const store = new MemorySegmentCacheStore();
+ *
+ * // With defaults for cache() boundaries
+ * const store = new MemorySegmentCacheStore({
+ *   defaults: { ttl: 60 }
+ * });
+ *
+ * createRSCHandler({
+ *   router,
+ *   cache: { store }
+ * })
+ * ```
+ */
+export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+  private cache: Map<string, CachedEntryData>;
+  readonly defaults?: CacheDefaults;
+  readonly keyGenerator?: (
+    ctx: RequestContext<TEnv>,
+    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>());
+    this.defaults = options?.defaults;
+    this.keyGenerator = options?.keyGenerator;
+  }
+
+  async get(key: string): Promise<CacheGetResult | null> {
+    const cached = this.cache.get(key);
+
+    if (!cached) {
+      return null;
+    }
+
+    // Check expiration
+    if (Date.now() > cached.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Memory store doesn't support SWR - never triggers revalidation
+    return { data: cached, shouldRevalidate: false };
+  }
+
+  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 = {
+      ...data,
+      expiresAt: Date.now() + ttl * 1000,
+    };
+    this.cache.set(key, entry);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.cache.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics for debugging purposes.
+   * @internal
+   */
+  getStats(): { size: number; keys: string[] } {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys()),
+    };
+  }
+
+  /**
+   * Reset the global cache state.
+   * Useful for test isolation - call this in beforeEach to ensure
+   * tests don't share cache state via globalThis.
+   *
+   * @example
+   * ```typescript
+   * beforeEach(() => {
+   *   MemorySegmentCacheStore.resetGlobalCache();
+   * });
+   * ```
+   */
+  static resetGlobalCache(): void {
+    delete (globalThis as any)[CACHE_GLOBAL_KEY];
+  }
+}