@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.120

package/src/server/status-code-resolver.ts

@@ -5,6 +5,12 @@
  * correct file to render by walking the fallback chain described in
  * design/10-error-handling.md §"Status-Code Files".
  *
+ * **Generic over `TFile`** (TIM-848). Walks `SegmentNode<TFile>` trees
+ * regardless of whether `TFile` is the build-time `RouteFile` or the
+ * runtime `ManifestFile`. Before TIM-848 there were two near-identical
+ * resolvers — one for the Map-based scanner output and one for the
+ * object-based runtime manifest. Now there is one.
+ *
  * Supports two format families:
  * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
  * - 'json': .json status files → raw JSON response, no React
@@ -17,17 +23,16 @@
  *   Pass 3 — error.tsx (leaf → root)
  *   Pass 4 — framework default (returns null)
  *
- * **JSON chain (4xx):**
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
+ * **JSON chain (4xx and 5xx):**
+ *   Pass 1 — json status files (leaf → root): {status}.json → {category}.json
  *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
  *
- * **5xx (component only):**
+ * **5xx component:**
  *   Per-segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
- *   Then global-error.tsx (future)
  *   Then framework default (returns null)
  */
 
-import type { SegmentNode, RouteFile } from '#/routing/types.js';
+import type { SegmentNode } from '../routing/types.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -42,9 +47,9 @@ export type StatusFileKind =
 export type StatusFileFormat = 'component' | 'json';
 
 /** Result of resolving a status-code file for a segment chain. */
-export interface StatusFileResolution {
+export interface StatusFileResolution<TFile> {
   /** The matched route file. */
-  file: RouteFile;
+  file: TFile;
   /** The HTTP status code (always the original status, not the file's code). */
   status: number;
   /** How the file was matched. */
@@ -57,9 +62,9 @@ export interface StatusFileResolution {
 export type SlotDeniedKind = 'denied' | 'default';
 
 /** Result of resolving a slot denied file. */
-export interface SlotDeniedResolution {
+export interface SlotDeniedResolution<TFile> {
   /** The matched route file (denied.tsx or default.tsx). */
-  file: RouteFile;
+  file: TFile;
   /** Slot name without @ prefix. */
   slotName: string;
   /** How the file was matched. */
@@ -78,6 +83,52 @@ const LEGACY_FILE_TO_STATUS: Record<string, number> = {
   'unauthorized': 401,
 };
 
+/** Reverse index: status code → legacy file name. Built once at module load. */
+const STATUS_TO_LEGACY_FILE: Record<number, string> = Object.fromEntries(
+  Object.entries(LEGACY_FILE_TO_STATUS).map(([name, status]) => [status, name])
+);
+
+// ─── Lookup Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Look up `{statusStr}` then `{categoryKey}` (e.g. "4xx" / "5xx") in a
+ * status-file group on a single segment. Shared by all three fallback
+ * chains — the only structural difference between component 4xx,
+ * component 5xx, and JSON resolution is *which* group is searched and
+ * how the per-segment loop is layered around it.
+ */
+function lookupInGroup<TFile>(
+  group: Record<string, TFile> | undefined,
+  statusStr: string,
+  categoryKey: string,
+  segmentIndex: number,
+  status: number
+): StatusFileResolution<TFile> | null {
+  if (!group) return null;
+  const exact = group[statusStr];
+  if (exact) return { file: exact, status, kind: 'exact', segmentIndex };
+  const category = group[categoryKey];
+  if (category) return { file: category, status, kind: 'category', segmentIndex };
+  return null;
+}
+
+/**
+ * Look up the legacy convention file (`not-found.tsx` / `forbidden.tsx` /
+ * `unauthorized.tsx`) for `status` on a single segment. Returns null if
+ * `status` has no legacy mapping or the file isn't present.
+ */
+function lookupLegacy<TFile>(
+  group: Record<string, TFile> | undefined,
+  status: number,
+  segmentIndex: number
+): StatusFileResolution<TFile> | null {
+  if (!group) return null;
+  const name = STATUS_TO_LEGACY_FILE[status];
+  if (!name) return null;
+  const file = group[name];
+  return file ? { file, status, kind: 'legacy', segmentIndex } : null;
+}
+
 // ─── Resolver ────────────────────────────────────────────────────────────────
 
 /**
@@ -91,101 +142,50 @@ const LEGACY_FILE_TO_STATUS: Record<string, number> = {
  * @param segments - The matched segment chain from root (index 0) to leaf (last).
  * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
  */
-export function resolveStatusFile(
+export function resolveStatusFile<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>,
+  segments: ReadonlyArray<SegmentNode<TFile>>,
   format: StatusFileFormat = 'component'
-): StatusFileResolution | null {
-  if (status >= 400 && status <= 499) {
-    return format === 'json' ? resolve4xxJson(status, segments) : resolve4xx(status, segments);
-  }
-  if (status >= 500 && status <= 599) {
-    // JSON format for 5xx uses the same json chain pattern
-    return format === 'json' ? resolve5xxJson(status, segments) : resolve5xx(status, segments);
-  }
-  return null;
+): StatusFileResolution<TFile> | null {
+  if (status < 400 || status > 599) return null;
+  if (format === 'json') return resolveJson(status, segments);
+  if (status <= 499) return resolve4xx(status, segments);
+  return resolve5xx(status, segments);
 }
 
 /**
- * 4xx component fallback chain (three separate passes):
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
+ * 4xx component fallback chain — three separate full passes leaf→root.
+ *
+ * The passes must be separate (not interleaved per-segment) so that a
+ * root-level `404.tsx` beats a leaf-level `error.tsx`. The 5xx chain
+ * inverts this and is per-segment: a leaf's `error.tsx` beats a root's
+ * `5xx.tsx`. This asymmetry is the only reason these two functions exist
+ * separately.
+ *
+ *   Pass 1 — {status}.tsx → 4xx.tsx           (statusFiles)
+ *   Pass 2 — not-found / forbidden / unauthorized (legacyStatusFiles)
+ *   Pass 3 — error.tsx                         (error)
  */
-function resolve4xx(
+function resolve4xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
 
-  // Pass 1: status files across all segments (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.statusFiles) continue;
-
-    // Exact match first
-    const exact = segment.statusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.statusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  // Pass 2: legacy compat files (leaf → root)
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-
-    for (const [name, legacyStatus] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      if (legacyStatus === status) {
-        const file = segment.legacyStatusFiles.get(name);
-        if (file) {
-          return { file, status, kind: 'legacy', segmentIndex: i };
-        }
-      }
-    }
+    const r = lookupInGroup(segments[i].statusFiles, statusStr, '4xx', i, status);
+    if (r) return r;
   }
 
-  // Pass 3: error.tsx (leaf → root)
   for (let i = segments.length - 1; i >= 0; i--) {
-    if (segments[i].error) {
-      return { file: segments[i].error!, status, kind: 'error', segmentIndex: i };
-    }
+    const r = lookupLegacy(segments[i].legacyStatusFiles, status, i);
+    if (r) return r;
   }
 
-  return null;
-}
-
-/**
- * 4xx JSON fallback chain (single pass):
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
- *   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
- */
-function resolve4xxJson(
-  status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
-  const statusStr = String(status);
-
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    // Exact match first
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.jsonStatusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
+    const errorFile = segments[i].error;
+    if (errorFile) {
+      return { file: errorFile, status, kind: 'error', segmentIndex: i };
     }
   }
 
@@ -193,33 +193,22 @@ function resolve4xxJson(
 }
 
 /**
- * 5xx component fallback chain (single pass, per-segment):
- *   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
+ * 5xx component fallback chain — single pass, per-segment leaf→root.
+ *
+ * At each segment: {status}.tsx → 5xx.tsx → error.tsx. A leaf's
+ * `error.tsx` therefore beats a root's `5xx.tsx`, which is the
+ * intentional inverse of the 4xx chain.
  */
-function resolve5xx(
+function resolve5xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
 
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
-
-    // Exact status file
-    if (segment.statusFiles) {
-      const exact = segment.statusFiles.get(statusStr);
-      if (exact) {
-        return { file: exact, status, kind: 'exact', segmentIndex: i };
-      }
-
-      // Category catch-all
-      const category = segment.statusFiles.get('5xx');
-      if (category) {
-        return { file: category, status, kind: 'category', segmentIndex: i };
-      }
-    }
-
-    // error.tsx at this segment level (for 5xx, checked per-segment)
+    const r = lookupInGroup(segment.statusFiles, statusStr, '5xx', i, status);
+    if (r) return r;
     if (segment.error) {
       return { file: segment.error, status, kind: 'error', segmentIndex: i };
     }
@@ -229,29 +218,22 @@ function resolve5xx(
 }
 
 /**
- * 5xx JSON fallback chain (single pass):
- *   At each segment (leaf → root): {status}.json → 5xx.json
- *   No error.tsx equivalent — JSON chain terminates at category catch-all.
+ * JSON fallback chain (for both 4xx and 5xx) — single pass leaf→root.
+ *
+ * At each segment: {status}.json → {category}.json. No legacy compat,
+ * no error.tsx — the JSON chain terminates at the category catch-all
+ * and the caller falls back to a bare-JSON framework default.
  */
-function resolve5xxJson(
+function resolveJson<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const categoryKey = status >= 500 ? '5xx' : '4xx';
 
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    const category = segment.jsonStatusFiles.get('5xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
+    const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
+    if (r) return r;
   }
 
   return null;
@@ -267,7 +249,9 @@ function resolve5xxJson(
  *
  * @param slotNode - The segment node for the slot (segmentType === 'slot').
  */
-export function resolveSlotDenied(slotNode: SegmentNode): SlotDeniedResolution | null {
+export function resolveSlotDenied<TFile>(
+  slotNode: SegmentNode<TFile>
+): SlotDeniedResolution<TFile> | null {
   const slotName = slotNode.segmentName.replace(/^@/, '');
 
   if (slotNode.denied) {

package/src/server/stream-utils.ts

@@ -0,0 +1,213 @@
+/**
+ * Stream utilities for the RSC rendering pipeline.
+ *
+ * teeWithErrorPropagation — wraps native ReadableStream.tee() with:
+ * 1. Cross-branch error propagation (error on one branch cancels the other)
+ * 2. Buffer divergence monitoring (warns + cancels when threshold exceeded)
+ *
+ * This prevents two classes of bugs:
+ * - Silent stalls when one tee branch errors and the other hangs indefinitely
+ * - Unbounded memory growth when one consumer (SSR) is much slower than the other
+ *
+ * Design doc: 02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+
+/** Default maximum buffer divergence before cancellation (5MB). */
+const DEFAULT_MAX_BUFFER_BYTES = 5 * 1024 * 1024;
+
+export interface TeeOptions {
+  /**
+   * Maximum byte divergence between the two branches before both are
+   * cancelled. When one branch has consumed this many more bytes than
+   * the other, the tee's internal buffer is at least this large.
+   *
+   * Default: 5MB.
+   */
+  maxBufferBytes?: number;
+}
+
+/**
+ * Tee a ReadableStream with error propagation and buffer monitoring.
+ *
+ * Delegates to the native `stream.tee()` for the actual forking, then wraps
+ * each branch in a ReadableStream that:
+ * - Tracks bytes consumed per branch
+ * - Cancels both branches if byte divergence exceeds `maxBufferBytes`
+ * - Cancels the other branch if either branch is cancelled or errors
+ *
+ * The returned streams are drop-in replacements for the native tee branches.
+ */
+export function teeWithErrorPropagation(
+  stream: ReadableStream<Uint8Array>,
+  options?: TeeOptions
+): [ReadableStream<Uint8Array>, ReadableStream<Uint8Array>] {
+  const maxBuffer = options?.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+  const [rawBranch1, rawBranch2] = stream.tee();
+
+  // Shared state for cross-branch coordination
+  let consumed1 = 0;
+  let consumed2 = 0;
+  let cancelled = false;
+
+  // Readers and controllers are assigned when wrapBranch creates the wrapped
+  // streams. We store them so cancelBoth can cancel raw tee branches AND
+  // error the wrapped stream controllers for cross-branch propagation.
+  let rawReader1: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let rawReader2: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let controller1: ReadableStreamDefaultController<Uint8Array> | undefined;
+  let controller2: ReadableStreamDefaultController<Uint8Array> | undefined;
+
+  /**
+   * Cancel both tee branches. `initiator` is the branch index (0 or 1)
+   * that triggered the cancellation — its controller is already being
+   * closed/errored by the pull/cancel that triggered this, so we skip it.
+   * Pass -1 to cancel+error both (e.g., from the buffer divergence guard).
+   *
+   * Both raw readers are always canceled regardless of initiator, because
+   * the tee source stream is only released when both branches are canceled.
+   * ReadableStreamDefaultReader.cancel() is idempotent, so double-cancel
+   * is safe.
+   */
+  function cancelBoth(reason: unknown, initiator: number = -1): void {
+    if (cancelled) return;
+    cancelled = true;
+    // Cancel both raw readers — tee source requires both branches canceled.
+    rawReader1?.cancel(reason).catch(() => {});
+    rawReader2?.cancel(reason).catch(() => {});
+    // Error wrapped controllers so consumers see the failure.
+    // Skip the initiator's controller — it's already being closed/errored.
+    if (initiator !== 0) {
+      try {
+        controller1?.error(reason);
+      } catch {
+        /* already closed/errored */
+      }
+    }
+    if (initiator !== 1) {
+      try {
+        controller2?.error(reason);
+      } catch {
+        /* already closed/errored */
+      }
+    }
+  }
+
+  function wrapBranch(
+    branchIndex: number,
+    rawBranch: ReadableStream<Uint8Array>,
+    assignReader: (r: ReadableStreamDefaultReader<Uint8Array>) => void,
+    assignController: (c: ReadableStreamDefaultController<Uint8Array>) => void,
+    addConsumed: (n: number) => void,
+    getSelfConsumed: () => number,
+    getOtherConsumed: () => number
+  ): ReadableStream<Uint8Array> {
+    const reader = rawBranch.getReader();
+    assignReader(reader);
+
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        assignController(controller);
+      },
+
+      async pull(controller) {
+        if (cancelled) {
+          return;
+        }
+
+        try {
+          const { done, value } = await reader.read();
+
+          // Re-check after await — cancelBoth may have fired while we
+          // were waiting on the raw reader.
+          if (cancelled) return;
+
+          if (done) {
+            try {
+              controller.close();
+            } catch {
+              /* controller already errored by cancelBoth */
+            }
+            return;
+          }
+
+          addConsumed(value.byteLength);
+
+          // Check buffer divergence: the difference in consumed bytes
+          // approximates the tee's internal buffer size.
+          const divergence = getSelfConsumed() - getOtherConsumed();
+          if (divergence > maxBuffer) {
+            const error = new Error(
+              `RSC stream tee buffer exceeded ${formatBytes(maxBuffer)} ` +
+                `(divergence: ${formatBytes(divergence)}). ` +
+                `This usually means SSR is much slower than the inline stream consumer. ` +
+                `Consider reducing RSC payload size or increasing the tee buffer limit.`
+            );
+            console.warn(`[timber] ${error.message}`);
+            cancelBoth(error);
+            return;
+          }
+
+          controller.enqueue(value);
+        } catch (err) {
+          if (!cancelled) {
+            // Source stream errored — propagate to both branches.
+            // cancelBoth with initiator skips our own controller,
+            // so we error it explicitly here.
+            cancelBoth(err, branchIndex);
+            try {
+              controller.error(err);
+            } catch {
+              /* already closed/errored */
+            }
+          }
+        }
+      },
+
+      cancel(reason) {
+        // Consumer cancelled this branch — propagate to the other
+        cancelBoth(reason, branchIndex);
+      },
+    });
+  }
+
+  const wrapped1 = wrapBranch(
+    0,
+    rawBranch1,
+    (r) => {
+      rawReader1 = r;
+    },
+    (c) => {
+      controller1 = c;
+    },
+    (n) => {
+      consumed1 += n;
+    },
+    () => consumed1,
+    () => consumed2
+  );
+
+  const wrapped2 = wrapBranch(
+    1,
+    rawBranch2,
+    (r) => {
+      rawReader2 = r;
+    },
+    (c) => {
+      controller2 = c;
+    },
+    (n) => {
+      consumed2 += n;
+    },
+    () => consumed2,
+    () => consumed1
+  );
+
+  return [wrapped1, wrapped2];
+}
+
+/** Format bytes as human-readable string (e.g., "5.00 MB"). */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}

package/src/server/tracing.ts

@@ -1,7 +1,7 @@
 /**
  * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
  *
- * traceId() is always available in server code (middleware, access, components, actions).
+ * getTraceId() is always available in server code (middleware, access, components, actions).
  * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
  * or a crypto.randomUUID()-derived fallback otherwise.
  *
@@ -24,11 +24,11 @@ export type { TraceStore } from './als-registry.js';
  *
  * Throws if called outside a request context (no ALS store).
  */
-export function traceId(): string {
+export function getTraceId(): string {
   const store = traceAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] traceId() called outside of a request context. ' +
+      '[timber] getTraceId() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
@@ -38,7 +38,7 @@ export function traceId(): string {
 /**
  * Returns the current OTEL span ID if available, undefined otherwise.
  */
-export function spanId(): string | undefined {
+export function getSpanId(): string | undefined {
   return traceAls.getStore()?.spanId;
 }
 
@@ -86,7 +86,7 @@ export function updateSpanId(newSpanId: string | undefined): void {
 
 /**
  * Get the current trace store, or undefined if outside a request context.
- * Framework-internal — use traceId()/spanId() in user code.
+ * Framework-internal — use getTraceId()/getSpanId() in user code.
  */
 export function getTraceStore(): TraceStore | undefined {
   return traceAls.getStore();
@@ -105,14 +105,25 @@ export function getTraceStore(): TraceStore | undefined {
  * Only called in dev mode — zero overhead in production.
  */
 export async function initDevTracing(
-  config: import('./dev-logger.js').DevLoggerConfig
+  config: import('../dev-tools/logger.js').DevLoggerConfig
 ): Promise<void> {
   const api = await getOtelApi();
   if (!api) return;
 
-  const { DevSpanProcessor } = await import('./dev-span-processor.js');
-  const { BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base');
-  const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');
+  let DevSpanProcessor: typeof import('../dev-tools/instrumentation.js').DevSpanProcessor;
+  let BasicTracerProvider: typeof import('@opentelemetry/sdk-trace-base').BasicTracerProvider;
+  let AsyncLocalStorageContextManager: typeof import('@opentelemetry/context-async-hooks').AsyncLocalStorageContextManager;
+
+  try {
+    ({ DevSpanProcessor } = await import('../dev-tools/instrumentation.js'));
+    ({ BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base'));
+    ({ AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks'));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[timber] Dev tracing disabled — failed to load OTEL packages:\n  ${msg}`);
+    return;
+  }
+
   const processor = new DevSpanProcessor(config);
 
   // Register a context manager so OTEL can propagate the active span
@@ -199,7 +210,7 @@ export async function withSpan<T>(
 
   const api = (await getOtelApi())!;
   return tracer.startActiveSpan(name, { attributes }, async (span) => {
-    const prevSpanId = spanId();
+    const prevSpanId = getSpanId();
     updateSpanId(span.spanContext().spanId);
     try {
       const result = await fn();