@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/src/server/response-cache.ts

@@ -1,410 +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: pathname + search + isRscPayload + Vary'd headers.
- * Only GET requests are cached. Responses with Set-Cookie, Cache-Control:
- * no-store/private, or error/redirect status codes are never cached.
- * 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;
-  /**
-   * The Vary header value from the original response, if any.
-   * Used to build variant-aware cache keys for subsequent requests.
-   */
-  vary: string | 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;
-}
-
-// ─── Cache-Control parsing ─────────────────────────────────────────────────
-
-/**
- * Check if a Cache-Control header value contains directives that forbid
- * storing the response in a shared cache. We check for `no-store` and
- * `private` — both indicate the response must not be reused.
- *
- * This is intentionally simple: we don't parse `max-age`, `s-maxage`,
- * `must-revalidate`, etc. This is a short-TTL render cache, not an HTTP
- * cache — we just need to respect explicit "don't cache this" signals.
- */
-function hasCacheControlNoStore(headerValue: string | null): boolean {
-  if (!headerValue) return false;
-  // Split on comma, trim whitespace, check for no-store or private directives.
-  // Case-insensitive per HTTP spec.
-  const lower = headerValue.toLowerCase();
-  return lower.includes('no-store') || lower.includes('private');
-}
-
-// ─── Vary header handling ──────────────────────────────────────────────────
-
-/**
- * Parse a Vary header value into a sorted list of header names.
- * Returns null if there is no Vary header or it's empty.
- * Returns ['*'] if Vary: * (meaning the response varies on everything —
- * effectively uncacheable).
- */
-function parseVaryHeader(headerValue: string | null): string[] | null {
-  if (!headerValue) return null;
-  const trimmed = headerValue.trim();
-  if (trimmed === '') return null;
-  if (trimmed === '*') return ['*'];
-
-  // Split on comma, normalize to lowercase, sort for deterministic keys
-  return trimmed
-    .split(',')
-    .map((h) => h.trim().toLowerCase())
-    .filter((h) => h.length > 0)
-    .sort();
-}
-
-/**
- * Build a Vary-aware suffix for the cache key. For each header name in the
- * Vary list, append the request's value for that header. This ensures that
- * requests with different Accept-Language (for example) get different cache
- * entries.
- */
-function buildVarySuffix(req: Request, varyHeaders: string[]): string {
-  return varyHeaders.map((h) => `${h}=${req.headers.get(h) ?? ''}`).join('&');
-}
-
-// ─── Factory ───────────────────────────────────────────────────────────────
-
-/**
- * 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();
-
-  /**
-   * Known Vary headers per path. When a response includes a Vary header,
-   * we store the parsed header names so that subsequent requests to the
-   * same path can include the Vary'd header values in their cache key
-   * BEFORE rendering (i.e., on cache lookup, not just after the first
-   * render). This avoids the "first request always misses" problem for
-   * Vary'd responses.
-   */
-  const knownVaryHeaders = new Map<string, string[]>();
-
-  function buildCacheKey(req: Request, isRscPayload: boolean): string | null {
-    // Never cache non-GET requests. POST/PUT/DELETE have side effects and
-    // may carry per-request state (e.g., form flash data via ALS) that makes
-    // the rendered output unique even for the same URL.
-    if (req.method !== 'GET') return 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);
-    // Include search params in the cache key. Pages that use searchParams
-    // (e.g., ?sort=asc, ?page=2) produce different output per query string.
-    let key = `${url.pathname}${url.search}:${isRscPayload ? 'rsc' : 'html'}`;
-
-    // If we've seen a Vary header for this path before, include the varied
-    // request header values in the key so different variants get different
-    // cache entries.
-    const pathKey = `${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
-    const varyHeaders = knownVaryHeaders.get(pathKey);
-    if (varyHeaders) {
-      if (varyHeaders[0] === '*') {
-        // Vary: * means the response varies on everything — uncacheable
-        return null;
-      }
-      key += ':' + buildVarySuffix(req, varyHeaders);
-    }
-
-    return key;
-  }
-
-  /**
-   * Check if a response is cacheable.
-   * Responses with Set-Cookie headers, Cache-Control: no-store/private,
-   * error/redirect status codes, or Vary: * are never cached.
-   */
-  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;
-
-    // Respect Cache-Control: no-store and private directives.
-    // If the application explicitly says "don't cache this," we obey.
-    if (hasCacheControlNoStore(response.headers.get('Cache-Control'))) return false;
-
-    // Vary: * means the response varies on everything — don't cache
-    const vary = parseVaryHeader(response.headers.get('Vary'));
-    if (vary && vary[0] === '*') 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 {
-    // Null-body statuses (204, 304) cannot have a body per HTTP spec.
-    // The Response constructor throws if you pass a body with these statuses.
-    const isNullBody = entry.status === 204 || entry.status === 304;
-    // slice(0) creates a copy so each caller owns their buffer
-    return new Response(isNullBody ? null : entry.body.slice(0), {
-      status: entry.status,
-      headers: entry.headers,
-    });
-  }
-
-  /**
-   * Record the Vary header from a response so future requests to the same
-   * path include varied header values in their cache key.
-   */
-  function recordVaryHeaders(pathKey: string, response: Response): void {
-    const vary = parseVaryHeader(response.headers.get('Vary'));
-    if (vary) {
-      knownVaryHeaders.set(pathKey, vary);
-    }
-  }
-
-  return {
-    async getOrRender(
-      req: Request,
-      isRscPayload: boolean,
-      renderFn: () => Promise<Response>
-    ): Promise<Response> {
-      const cacheKey = buildCacheKey(req, isRscPayload);
-
-      // No cache key = skip caching and singleflight entirely.
-      // This covers POST requests, authenticated requests (publicOnly),
-      // and Vary: * responses.
-      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.
-      // We buffer the response body into an ArrayBuffer so ALL callers —
-      // including the singleflight leader — get independent copies.
-      // This fixes the body-loss bug where the leader consumed the body
-      // and concurrent waiters got an empty response.
-      const result: CacheEntry | null = await singleflight.do(cacheKey, async () => {
-        const response = await renderFn();
-
-        // Record Vary headers for future cache key construction
-        const url = new URL(req.url);
-        const pathKey = `${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
-        recordVaryHeaders(pathKey, response);
-
-        if (!isCacheable(response)) {
-          // Buffer the body even for non-cacheable responses so the
-          // singleflight leader and all concurrent waiters each get
-          // an independent copy. Without this, the leader consumes
-          // the body stream and waiters get an empty response.
-          const body = await response.arrayBuffer();
-          const headers: [string, string][] = [];
-          response.headers.forEach((value, key) => {
-            headers.push([key, value]);
-          });
-          // Return as a CacheEntry shape but DON'T store in LRU.
-          // Callers construct Responses from this, but it won't be
-          // reused for future requests.
-          return {
-            body,
-            status: response.status,
-            headers,
-            createdAt: Date.now(),
-            vary: response.headers.get('Vary'),
-          };
-        }
-
-        // Buffer the response body for caching.
-        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(),
-          vary: response.headers.get('Vary'),
-        };
-
-        // Re-check the cache key now that we know the Vary headers.
-        // The initial key may not have included Vary'd header values
-        // if this was the first request to this path. Rebuild the key
-        // with the now-known Vary headers for correct LRU storage.
-        const updatedKey = buildCacheKey(req, isRscPayload);
-        if (updatedKey) {
-          lru.set(updatedKey, entry);
-        }
-
-        return entry;
-      });
-
-      if (result === null) {
-        // Shouldn't happen — singleflight always returns a result.
-        // Defensive fallback: re-render.
-        return renderFn();
-      }
-
-      return responseFromEntry(result);
-    },
-
-    get size() {
-      return lru.size;
-    },
-
-    clear() {
-      lru.clear();
-      knownVaryHeaders.clear();
-    },
-  };
-}