@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/server/request-context.ts

@@ -13,6 +13,7 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { Routes } from '#/index.js';
 import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
+import { isDebug } from './debug.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -117,7 +118,7 @@ export function cookies(): RequestCookies {
     set(name: string, value: string, options?: CookieOptions): void {
       assertMutable(store, 'set');
       if (store.flushed) {
-        if (process.env.NODE_ENV !== 'production') {
+        if (isDebug()) {
           console.warn(
             `[timber] warn: cookies().set('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
@@ -146,7 +147,7 @@ export function cookies(): RequestCookies {
     delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
       assertMutable(store, 'delete');
       if (store.flushed) {
-        if (process.env.NODE_ENV !== 'production') {
+        if (isDebug()) {
           console.warn(
             `[timber] warn: cookies().delete('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\n` +

package/src/server/response-cache.ts

@@ -0,0 +1,410 @@
+/**
+ * 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();
+    },
+  };
+}

package/src/server/route-element-builder.ts

@@ -352,12 +352,7 @@ export async function buildRouteElement(
     //   same urlPath (e.g., /(marketing) and /(app) both have "/"),
     //   which would cause the wrong cached layout to be reused
     const skip =
-      shouldSkipSegment(
-        segment.urlPath,
-        layoutComponent,
-        isLeaf,
-        clientStateTree ?? null
-      ) &&
+      shouldSkipSegment(segment.urlPath, layoutComponent, isLeaf, clientStateTree ?? null) &&
       hasRenderedLayoutBelow &&
       segment.segmentType !== 'group';
 

package/src/server/rsc-entry/index.ts

@@ -63,10 +63,16 @@ import {
   isRscPayloadRequest,
 } from './helpers.js';
 import { parseClientStateTree } from '#/server/state-tree-diff.js';
+import {
+  createResponseCache,
+  resolveResponseCacheConfig,
+  type ResponseCache,
+} from '#/server/response-cache.js';
 import { buildRscPayloadResponse } from './rsc-payload.js';
 import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
 import { callSsr } from './ssr-bridge.js';
+import { isDebug, isDevMode, setDebugFromConfig } from '#/server/debug.js';
 
 // Dev-only pipeline error handler, set by the dev server after import.
 // In production this is always undefined — no overhead.
@@ -121,13 +127,31 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     buildManifest: buildManifest as BuildManifest,
   });
 
-  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
-  // In production, isDev is false — no tracing, no overhead.
-  // The DevSpanProcessor handles all formatting and stderr output.
-  const isDev = process.env.NODE_ENV !== 'production';
+  // Initialize debug flag from config before anything else.
+  // This allows timber.config.ts `debug: true` to enable debug logging
+  // in production without the TIMBER_DEBUG env var.
+  if ((runtimeConfig as Record<string, unknown>).debug) {
+    setDebugFromConfig(true);
+  }
+
+  // Two separate flags for two different security levels:
+  //
+  // isDev (isDevMode) — gates client-visible behavior: dev error pages with
+  //   stack traces, detailed Server-Timing headers, error messages in action
+  //   payloads. Statically replaced in production → tree-shaken to zero.
+  //   TIMBER_DEBUG cannot enable this.
+  //
+  // debugEnabled (isDebug) — gates server-side logging only: stderr warnings,
+  //   OTEL dev tracing, console.error fallbacks. TIMBER_DEBUG enables this.
+  //   Never affects what clients see.
+  const isDev = isDevMode();
+  const debugEnabled = isDebug();
   const slowPhaseMs = (runtimeConfig as Record<string, unknown>).slowPhaseMs as number | undefined;
 
-  if (isDev) {
+  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
+  // In production with TIMBER_DEBUG, this enables server-side tracing output
+  // without exposing anything to clients.
+  if (debugEnabled) {
     const devLogMode = resolveLogMode();
     if (devLogMode !== 'quiet') {
       await initDevTracing({ mode: devLogMode, slowPhaseMs });
@@ -140,6 +164,17 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
 
   const typedBuildManifest = buildManifest as BuildManifest;
 
+  // Initialize response-level caching and singleflight deduplication.
+  // See design/31-benchmarking.md for performance motivation.
+  const responseCacheRaw = (runtimeConfig as Record<string, unknown>).responseCache as
+    | { maxSize?: number; ttlMs?: number; publicOnly?: boolean }
+    | false
+    | undefined;
+  const responseCacheConfig = resolveResponseCacheConfig(responseCacheRaw);
+  const responseCache: ResponseCache | null = responseCacheConfig
+    ? createResponseCache(responseCacheConfig)
+    : null;
+
   const pipelineConfig: PipelineConfig = {
     proxyLoader: manifest.proxy?.load,
     matchRoute,
@@ -170,14 +205,17 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       _requestHeaderOverlay: Headers,
       interception?: InterceptionContext
     ) => {
-      return renderRoute(
-        req,
-        match,
-        responseHeaders,
-        clientBootstrap,
-        clientJsDisabled,
-        interception
-      );
+      const doRender = () =>
+        renderRoute(req, match, responseHeaders, clientBootstrap, clientJsDisabled, interception);
+
+      // Response cache wraps the render with singleflight + LRU.
+      // Interception requests (modals) are excluded — they depend on
+      // X-Timber-URL which makes caching semantics ambiguous.
+      if (responseCache && !interception) {
+        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
+        return responseCache.getOrRender(req, isRsc, doRender);
+      }
+      return doRender();
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
       return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap);
@@ -330,7 +368,8 @@ async function renderRoute(
     throw error;
   }
 
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } = routeResult;
+  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
+    routeResult;
 
   // Build head HTML for injection into the SSR output.
   // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
@@ -347,6 +386,14 @@ async function renderRoute(
     headHtml += buildCssLinkTags(cssUrls);
   }
 
+  // Inline font CSS as a <style> tag — @font-face rules and scoped classes.
+  // The font CSS is set on globalThis by the transformed font file's
+  // side-effect import of virtual:timber-font-css-register.
+  const fontCss = (globalThis as Record<string, unknown>).__timber_font_css as string | undefined;
+  if (fontCss) {
+    headHtml += `<style data-timber-fonts>${fontCss}</style>`;
+  }
+
   const fontEntries = collectRouteFonts(segments, typedManifest);
   if (fontEntries.length > 0) {
     headHtml += buildFontPreloadTags(fontEntries);

package/src/server/rsc-entry/rsc-payload.ts

@@ -45,15 +45,45 @@ export async function buildRscPayloadResponse(
   skippedSegments?: string[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
+  // Race the first read against signal detection — if an async component
+  // throws a RedirectSignal or DenySignal, the onError callback fires
+  // signals.onSignal() and we can react immediately without waiting for
+  // the full macrotask queue.
+  //
+  // The rejection chain for an async-wrapped page component:
+  //   1. PageComponent throws RedirectSignal
+  //   2. withSpan catches and re-throws (microtask 1)
+  //   3. TracedPage promise rejects (microtask 2)
+  //   4. React Flight rejection handler → onError (microtask 3+)
+  //
+  // Promise.race reacts the instant onError fires, eliminating the
+  // per-request setTimeout(0) macrotask delay for the common case
+  // (no signal). A 50ms ceiling timeout guards against edge cases
+  // where onError never fires.
   const reader = rscStream.getReader();
-  const firstRead = await reader.read();
+  const signalDetected = new Promise<void>((resolve) => {
+    signals.onSignal = resolve;
+  });
+
+  type RaceResult =
+    | { type: 'data'; chunk: ReadableStreamReadResult<Uint8Array> }
+    | { type: 'signal' };
+
+  const first: RaceResult = await Promise.race([
+    reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
+    signalDetected.then(() => ({ type: 'signal' as const })),
+  ]);
 
-  // Yield to the microtask queue so that async component rejections
-  // (e.g. an async-wrapped page component that throws redirect())
-  // propagate to the onError callback before we check the signals.
-  // The rejected Promise from an async component resolves in the next
-  // microtask after read(), so we need at least one tick.
-  await new Promise<void>((r) => setTimeout(r, 0));
+  // If data arrived first, still check signals — they may have fired
+  // concurrently. Also do a final ceiling timeout check for edge cases
+  // where the signal fires just after the first read resolves.
+  if (first.type === 'data' && !signals.redirectSignal && !signals.denySignal) {
+    // Brief yield to let any in-flight microtask rejections complete.
+    await new Promise<void>((r) => setTimeout(r, 0));
+  }
+
+  // Detach the callback — no longer needed after this point.
+  signals.onSignal = undefined;
 
   // Check for redirect/deny signals detected during initial rendering
   const trackedRedirect = signals.redirectSignal as RedirectSignal | null;
@@ -72,6 +102,11 @@ export async function buildRscPayloadResponse(
     );
   }
 
+  // Extract the first chunk from the race result.
+  // If the signal won the race, read the first chunk now (the stream
+  // was already cancelled above, but we need a firstRead shape below).
+  const firstRead = first.type === 'data' ? first.chunk : await reader.read();
+
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.
   const patchedStream = new ReadableStream<Uint8Array>({