@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/server/response-cache.ts

@@ -1,277 +0,0 @@
-/**
- * Render-level response deduplication and short-TTL LRU cache.
- *
- * Two layers of optimization:
- *
- * 1. **Singleflight** — concurrent requests to the same URL share a single
- *    render. Uses createSingleflight() from cache/singleflight.ts.
- *
- * 2. **LRU cache** — recently rendered responses are reused without
- *    re-executing the RSC-to-SSR pipeline. Entries have a short TTL
- *    (default 5s) and the cache has a bounded size (default 150 entries).
- *
- * Cache keys are compound: method + pathname + isRscPayload. Responses
- * with Set-Cookie headers are never cached (they contain user-specific
- * state). When `publicOnly` is true (default), requests with Cookie or
- * Authorization headers bypass the cache entirely.
- *
- * See design/02-rendering-pipeline.md, design/31-benchmarking.md.
- */
-
-import { createSingleflight } from '#/cache/singleflight.js';
-
-// ─── Configuration ─────────────────────────────────────────────────────────
-
-export interface ResponseCacheConfig {
-  /** Maximum number of entries in the LRU cache. Default: 150. */
-  maxSize?: number;
-  /** TTL for cached entries in milliseconds. Default: 5000 (5s). */
-  ttlMs?: number;
-  /**
-   * When true (default), requests with Cookie or Authorization headers
-   * bypass the cache entirely. This prevents sharing user-specific
-   * responses across requests.
-   */
-  publicOnly?: boolean;
-}
-
-export interface ResolvedResponseCacheConfig {
-  maxSize: number;
-  ttlMs: number;
-  publicOnly: boolean;
-}
-
-export function resolveResponseCacheConfig(
-  config?: ResponseCacheConfig | false
-): ResolvedResponseCacheConfig | null {
-  // Explicitly disabled
-  if (config === false) return null;
-
-  return {
-    maxSize: config?.maxSize ?? 150,
-    ttlMs: config?.ttlMs ?? 5000,
-    publicOnly: config?.publicOnly ?? true,
-  };
-}
-
-// ─── Cache Entry ───────────────────────────────────────────────────────────
-
-interface CacheEntry {
-  /** The cached response body as an ArrayBuffer (already consumed). */
-  body: ArrayBuffer;
-  /** Response status code. */
-  status: number;
-  /** Response headers (serialized). */
-  headers: [string, string][];
-  /** Timestamp when this entry was created. */
-  createdAt: number;
-}
-
-// ─── Singleflight Result ───────────────────────────────────────────────────
-
-/** Internal type: singleflight returns either a raw response or a cache entry. */
-interface SingleflightResult {
-  /** Non-null when the response wasn't cacheable — only the first caller gets it. */
-  response: Response | null;
-  /** Non-null when the response was cached — all callers construct from this. */
-  entry: CacheEntry | null;
-}
-
-// ─── LRU Cache ─────────────────────────────────────────────────────────────
-
-/**
- * Simple LRU cache backed by a Map (insertion order = access order).
- * On get, we delete and re-insert to move the entry to the end (most recent).
- * On eviction, we delete from the beginning (least recent).
- */
-class LruCache {
-  private readonly map = new Map<string, CacheEntry>();
-  private readonly maxSize: number;
-  private readonly ttlMs: number;
-
-  constructor(maxSize: number, ttlMs: number) {
-    this.maxSize = maxSize;
-    this.ttlMs = ttlMs;
-  }
-
-  get(key: string): CacheEntry | undefined {
-    const entry = this.map.get(key);
-    if (!entry) return undefined;
-
-    // Check TTL
-    if (Date.now() - entry.createdAt > this.ttlMs) {
-      this.map.delete(key);
-      return undefined;
-    }
-
-    // Move to end (most recently used)
-    this.map.delete(key);
-    this.map.set(key, entry);
-    return entry;
-  }
-
-  set(key: string, entry: CacheEntry): void {
-    // If key exists, remove to re-insert at end
-    this.map.delete(key);
-
-    // Evict oldest if at capacity
-    if (this.map.size >= this.maxSize) {
-      const oldest = this.map.keys().next().value;
-      if (oldest !== undefined) {
-        this.map.delete(oldest);
-      }
-    }
-
-    this.map.set(key, entry);
-  }
-
-  get size(): number {
-    return this.map.size;
-  }
-
-  clear(): void {
-    this.map.clear();
-  }
-}
-
-// ─── Response Cache ────────────────────────────────────────────────────────
-
-export interface ResponseCache {
-  /**
-   * Wrap a render function with singleflight dedup + LRU caching.
-   * Returns the cached Response or executes the render function.
-   */
-  getOrRender(
-    req: Request,
-    isRscPayload: boolean,
-    renderFn: () => Promise<Response>
-  ): Promise<Response>;
-
-  /** Number of entries currently in the LRU cache. */
-  readonly size: number;
-
-  /** Clear all cached entries. */
-  clear(): void;
-}
-
-/**
- * Create a response cache with singleflight deduplication and LRU caching.
- */
-export function createResponseCache(config: ResolvedResponseCacheConfig): ResponseCache {
-  const lru = new LruCache(config.maxSize, config.ttlMs);
-  const singleflight = createSingleflight();
-
-  function buildCacheKey(req: Request, isRscPayload: boolean): string | null {
-    // When publicOnly is true, skip caching for authenticated requests
-    if (config.publicOnly) {
-      if (req.headers.has('Cookie') || req.headers.has('Authorization')) {
-        return null;
-      }
-    }
-
-    const url = new URL(req.url);
-    return `${req.method}:${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
-  }
-
-  /**
-   * Check if a response is cacheable.
-   * Responses with Set-Cookie headers are never cached — they contain
-   * user-specific state that must not be shared across requests.
-   */
-  function isCacheable(response: Response): boolean {
-    // Don't cache error responses
-    if (response.status >= 400) return false;
-
-    // Don't cache redirects
-    if (response.status >= 300 && response.status < 400) return false;
-
-    // Don't cache responses with Set-Cookie (user-specific state)
-    if (response.headers.has('Set-Cookie')) return false;
-
-    // Only cache responses with a body
-    if (!response.body) return false;
-
-    return true;
-  }
-
-  /** Construct a fresh Response from a cache entry (each caller gets their own). */
-  function responseFromEntry(entry: CacheEntry): Response {
-    // slice(0) creates a copy so each caller owns their buffer
-    return new Response(entry.body.slice(0), {
-      status: entry.status,
-      headers: entry.headers,
-    });
-  }
-
-  return {
-    async getOrRender(
-      req: Request,
-      isRscPayload: boolean,
-      renderFn: () => Promise<Response>
-    ): Promise<Response> {
-      const cacheKey = buildCacheKey(req, isRscPayload);
-
-      // No cache key = skip caching entirely
-      if (cacheKey === null) {
-        return renderFn();
-      }
-
-      // Check LRU cache first
-      const cached = lru.get(cacheKey);
-      if (cached) {
-        return responseFromEntry(cached);
-      }
-
-      // Singleflight: concurrent requests to the same key share one render.
-      // The singleflight returns a SingleflightResult so all waiters
-      // can construct their own Response from the same cached data.
-      const result: SingleflightResult = await singleflight.do(cacheKey, async () => {
-        const response = await renderFn();
-
-        if (!isCacheable(response)) {
-          return { response, entry: null };
-        }
-
-        // Buffer the response body for caching.
-        // The original Response body is consumed here — callers get copies
-        // from the cached ArrayBuffer.
-        const body = await response.arrayBuffer();
-        const headers: [string, string][] = [];
-        response.headers.forEach((value, key) => {
-          headers.push([key, value]);
-        });
-
-        const entry: CacheEntry = {
-          body,
-          status: response.status,
-          headers,
-          createdAt: Date.now(),
-        };
-
-        lru.set(cacheKey, entry);
-
-        return { response: null, entry };
-      });
-
-      // Non-cacheable response — only the first caller gets the original.
-      // For singleflight, this means concurrent waiters get the same promise
-      // result. The first caller already consumed the body, so subsequent
-      // callers would get an empty body. This is acceptable: non-cacheable
-      // responses (errors, redirects, Set-Cookie) are rare under concurrent
-      // identical requests, and the status + headers are still correct.
-      if (result.response) {
-        return result.response;
-      }
-
-      return responseFromEntry(result.entry!);
-    },
-
-    get size() {
-      return lru.size;
-    },
-
-    clear() {
-      lru.clear();
-    },
-  };
-}