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

package/src/server/response-cache.ts

@@ -10,10 +10,11 @@
  *    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.
+ * 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.
  */
@@ -65,16 +66,11 @@ interface CacheEntry {
   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;
+  /**
+   * 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 ─────────────────────────────────────────────────────────────
@@ -154,6 +150,59 @@ export interface ResponseCache {
   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.
  */
@@ -161,7 +210,22 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
   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')) {
@@ -170,13 +234,30 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
     }
 
     const url = new URL(req.url);
-    return `${req.method}:${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
+    // 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 are never cached — they contain
-   * user-specific state that must not be shared across requests.
+   * 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
@@ -188,6 +269,14 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
     // 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;
 
@@ -196,13 +285,27 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
 
   /** 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(entry.body.slice(0), {
+    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,
@@ -211,7 +314,9 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
     ): Promise<Response> {
       const cacheKey = buildCacheKey(req, isRscPayload);
 
-      // No cache key = skip caching entirely
+      // No cache key = skip caching and singleflight entirely.
+      // This covers POST requests, authenticated requests (publicOnly),
+      // and Vary: * responses.
       if (cacheKey === null) {
         return renderFn();
       }
@@ -223,18 +328,41 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
       }
 
       // 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 () => {
+      // 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)) {
-          return { response, entry: null };
+          // 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.
-        // 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) => {
@@ -246,24 +374,28 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
           status: response.status,
           headers,
           createdAt: Date.now(),
+          vary: response.headers.get('Vary'),
         };
 
-        lru.set(cacheKey, entry);
+        // 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 { response: null, entry };
+        return 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;
+      if (result === null) {
+        // Shouldn't happen — singleflight always returns a result.
+        // Defensive fallback: re-render.
+        return renderFn();
       }
 
-      return responseFromEntry(result.entry!);
+      return responseFromEntry(result);
     },
 
     get size() {
@@ -272,6 +404,7 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
 
     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

@@ -368,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.

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

@@ -45,18 +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;
+  });
 
-  // 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.
-  //
-  // Uses queueMicrotask instead of setTimeout(0) to stay within the
-  // same tick — no full event loop round-trip needed.
-  await new Promise<void>((r) => queueMicrotask(r));
+  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 })),
+  ]);
+
+  // 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;
@@ -75,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>({

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

@@ -24,11 +24,17 @@ import { isDebug } from '#/server/debug.js';
  *
  * Signals fire asynchronously via `onError` during stream consumption.
  * The first signal of each type wins — subsequent signals are ignored.
+ *
+ * `onSignal` is an optional callback fired when a DenySignal or
+ * RedirectSignal is captured. Consumers use it with Promise.race to
+ * react immediately instead of polling with setTimeout/queueMicrotask.
  */
 export interface RenderSignals {
   denySignal: DenySignal | null;
   redirectSignal: RedirectSignal | null;
   renderError: { error: unknown; status: number } | null;
+  /** Callback fired when a redirect or deny signal is captured in onError. */
+  onSignal?: () => void;
 }
 
 export interface RscStreamResult {
@@ -67,11 +73,13 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           if (isAbortError(error) || req.signal?.aborted) return;
           if (error instanceof DenySignal) {
             signals.denySignal = error;
+            signals.onSignal?.();
             // Return structured digest for client-side error boundaries
             return JSON.stringify({ type: 'deny', status: error.status, data: error.data });
           }
           if (error instanceof RedirectSignal) {
             signals.redirectSignal = error;
+            signals.onSignal?.();
             return JSON.stringify({
               type: 'redirect',
               location: error.location,
@@ -98,11 +106,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           // directive isn't at the very top of the file, or the component is
           // re-exported through a barrel file without 'use client'.
           // See LOCAL-297.
-          if (
-            isDebug() &&
-            error instanceof Error &&
-            error.message.includes('Invalid hook call')
-          ) {
+          if (isDebug() && error instanceof Error && error.message.includes('Invalid hook call')) {
             console.error(
               '[timber] A React hook was called during RSC rendering. This usually means a ' +
                 "'use client' component is being executed as a server component instead of " +

package/src/server/rsc-entry/ssr-renderer.ts

@@ -156,16 +156,19 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   try {
     const ssrResponse = await callSsr(ssrStream, navContext);
 
-    // Signal promotion: yield one microtask so async component rejections
-    // propagate to the RSC onError callback, then check if any signals
-    // were captured during rendering inside Suspense boundaries.
-    // The Response hasn't been sent yet — it's an unconsumed stream.
+    // Signal promotion: check if any signals were captured during rendering
+    // inside Suspense boundaries. If no signals are present yet, yield one
+    // microtask so async component rejections propagate to the RSC onError
+    // callback before we commit the response.
     //
-    // Uses queueMicrotask instead of setTimeout(0) to avoid yielding to
-    // the full event loop (timers phase). Microtask resolution happens
-    // within the same tick, eliminating per-request idle time under load.
+    // When signals are already captured (onSignal already fired), skip the
+    // yield entirely — react immediately. Uses queueMicrotask instead of
+    // setTimeout(0) for the fallback to avoid yielding to the full event
+    // loop (timers phase).
     // See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
-    await new Promise<void>((r) => queueMicrotask(r));
+    if (!signals.redirectSignal && !signals.denySignal && !signals.renderError) {
+      await new Promise<void>((r) => queueMicrotask(r));
+    }
 
     const promoted = checkCapturedSignals(/* skipHandledDeny */ true);
     if (promoted) {

package/src/server/tracing.ts

@@ -252,6 +252,29 @@ export async function addSpanEvent(
   }
 }
 
+/**
+ * Fire-and-forget span event — no await, no microtask overhead.
+ *
+ * Used on the cache hot path where awaiting addSpanEvent creates an
+ * unnecessary microtask per cache operation. If OTEL is not loaded yet,
+ * the event is silently dropped (acceptable for diagnostics).
+ *
+ * See TIM-370 for perf motivation.
+ */
+export function addSpanEventSync(
+  name: string,
+  attributes?: Record<string, string | number | boolean>
+): void {
+  // Fast path: if OTEL API hasn't been loaded yet, skip entirely.
+  // _otelApi is undefined (not yet loaded), null (failed to load), or the module.
+  if (!_otelApi) return;
+
+  const activeSpan = _otelApi.trace.getActiveSpan();
+  if (activeSpan) {
+    activeSpan.addEvent(name, attributes);
+  }
+}
+
 /**
  * Try to extract the OTEL trace ID from the current active span context.
  * Returns undefined if OTEL is not active or no span exists.

package/src/server/waituntil-bridge.ts

@@ -18,7 +18,10 @@ import { waitUntilAls } from './als-registry.js';
  * Called by generated entry points (Nitro node-server/bun, Cloudflare)
  * to bind the platform's lifecycle extension for the request duration.
  */
-export function runWithWaitUntil<T>(waitUntilFn: (promise: Promise<unknown>) => void, fn: () => T): T {
+export function runWithWaitUntil<T>(
+  waitUntilFn: (promise: Promise<unknown>) => void,
+  fn: () => T
+): T {
   return waitUntilAls.run(waitUntilFn, fn);
 }