@timber-js/app 0.2.0-alpha.37 → 0.2.0-alpha.39

package/src/plugins/dev-error-overlay.ts

@@ -180,6 +180,63 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
   return lines.join('\n');
 }
 
+// ─── RSC Debug Context ──────────────────────────────────────────────────────
+
+/**
+ * Component info extracted from the RSC debug channel.
+ * Contains only names, environments, and stack frames — never source code.
+ */
+export interface RscDebugComponentInfo {
+  name: string;
+  env: string | null;
+  stack: unknown[] | null;
+}
+
+/**
+ * Format RSC debug component info into a readable string for the overlay.
+ *
+ * Renders the server component tree that was active when an error occurred,
+ * including component names and source locations from stack frames. This
+ * gives developers visibility into which server components were rendering
+ * without exposing source code.
+ *
+ * Returns an empty string if no components are provided.
+ */
+export function formatRscDebugContext(components: RscDebugComponentInfo[]): string {
+  if (!components || components.length === 0) return '';
+
+  // Deduplicate by name — the debug channel may emit the same component
+  // multiple times (e.g., when re-rendered or when multiple instances exist).
+  const seen = new Set<string>();
+  const unique: RscDebugComponentInfo[] = [];
+  for (const c of components) {
+    if (!seen.has(c.name)) {
+      seen.add(c.name);
+      unique.push(c);
+    }
+  }
+
+  const lines: string[] = ['Server Component Tree:'];
+  for (let i = 0; i < unique.length; i++) {
+    const c = unique[i]!;
+    const indent = '  '.repeat(i + 1);
+    const envLabel = c.env ? ` [${c.env}]` : '';
+
+    // Extract file location from stack frames if available
+    let locStr = '';
+    if (c.stack && c.stack.length > 0) {
+      const frame = c.stack[0] as [string, string, number, number] | undefined;
+      if (Array.isArray(frame) && frame.length >= 3) {
+        locStr = ` (${frame[1]}:${frame[2]})`;
+      }
+    }
+
+    lines.push(`${indent}${c.name}${envLabel}${locStr}`);
+  }
+
+  return lines.join('\n');
+}
+
 // ─── Overlay Integration ────────────────────────────────────────────────────
 
 /**
@@ -188,13 +245,19 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
  * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
  * then sends the error via `server.hot.send()` for the browser overlay.
  *
+ * When `rscDebugComponents` is provided (dev mode only), the server
+ * component tree context is appended to the error message. This helps
+ * developers identify which server component caused the error without
+ * exposing source code.
+ *
  * The dev server remains running — errors are handled, not fatal.
  */
 export function sendErrorToOverlay(
   server: ViteDevServer,
   error: Error,
   phase: ErrorPhase,
-  projectRoot: string
+  projectRoot: string,
+  rscDebugComponents?: RscDebugComponentInfo[]
 ): void {
   // Fix stack trace to use source-mapped positions
   server.ssrFixStacktrace(error);
@@ -212,6 +275,12 @@ export function sendErrorToOverlay(
     message = `${error.message}\n\nComponent Stack:\n${componentStack.trim()}`;
   }
 
+  // Append RSC debug context if available (dev mode only)
+  const debugContext = formatRscDebugContext(rscDebugComponents ?? []);
+  if (debugContext) {
+    message = `${message}\n\n${debugContext}`;
+  }
+
   // Send to browser via Vite's error overlay protocol
   try {
     server.hot.send({

package/src/plugins/dev-server.ts

@@ -161,12 +161,26 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
 
       // Wire pipeline errors into the browser error overlay.
       // setDevPipelineErrorHandler is only defined in dev (rsc-entry.ts exports it).
+      // The handler receives optional RSC debug component data (component names,
+      // environments, stack frames) from the Flight debug channel for render errors.
       const setHandler = rscModule.setDevPipelineErrorHandler as
-        | ((fn: (error: Error, phase: string) => void) => void)
+        | ((
+            fn: (
+              error: Error,
+              phase: string,
+              debugComponents?: Array<{ name: string; env: string | null; stack: unknown[] | null }>
+            ) => void
+          ) => void)
         | undefined;
       if (typeof setHandler === 'function') {
-        setHandler((error) => {
-          sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
+        setHandler((error, _phase, debugComponents) => {
+          sendErrorToOverlay(
+            server,
+            error,
+            classifyErrorPhase(error, projectRoot),
+            projectRoot,
+            debugComponents
+          );
         });
       }
     } catch (error) {
@@ -317,6 +331,17 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
   nodeRes.flushHeaders();
 
   const reader = webResponse.body.getReader();
+
+  // Cancel the reader when the client disconnects. This causes any pending
+  // reader.read() to reject, breaking the pump loop. Critical for SSE and
+  // other infinite streams — without this, disconnected clients leak readers.
+  let clientDisconnected = false;
+  const onClose = () => {
+    clientDisconnected = true;
+    reader.cancel('Client disconnected').catch(() => {});
+  };
+  nodeRes.on('close', onClose);
+
   try {
     while (true) {
       const { done, value } = await reader.read();
@@ -325,9 +350,18 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
       // don't need back-pressure here — just keep pushing chunks.
       nodeRes.write(value);
     }
+  } catch (err) {
+    // reader.cancel() from the close handler causes read() to reject.
+    // This is expected on client disconnect — not an error.
+    if (!clientDisconnected) {
+      throw err;
+    }
   } finally {
+    nodeRes.off('close', onClose);
     reader.releaseLock();
-    nodeRes.end();
+    if (!nodeRes.writableEnded) {
+      nodeRes.end();
+    }
   }
 }
 

package/src/plugins/entries.ts

@@ -106,6 +106,7 @@ function generateConfigModule(ctx: PluginContext): string {
     topLoader: ctx.config.topLoader,
     debug: ctx.config.debug ?? false,
     serverTiming: ctx.config.serverTiming,
+    renderTimeoutMs: ctx.config.renderTimeoutMs ?? 30_000,
     // Per-build deployment ID for version skew detection (TIM-446).
     // Null in dev mode — HMR handles code updates without full reloads.
     deploymentId: ctx.deploymentId ?? null,

package/src/server/action-handler.ts

@@ -32,6 +32,7 @@ import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './b
 import { parseFormData } from './form-data.js';
 import type { FormFlashData } from './form-flash.js';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
+import { logActionError } from './logger.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -193,7 +194,7 @@ async function handleRscAction(
     });
   } catch (error) {
     // Log full error server-side for debugging
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return structured error response — ActionError gets its code/data,
     // unexpected errors get sanitized { code: 'INTERNAL_ERROR' }
@@ -309,7 +310,7 @@ async function handleFormAction(
       renderer: config.revalidateRenderer,
     });
   } catch (error) {
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return the error as flash data for re-render.
     // handleActionError produces { serverError } for ActionErrors

package/src/server/default-logger.ts

@@ -0,0 +1,95 @@
+/**
+ * DefaultLogger — human-readable stderr logging when no custom logger is configured.
+ *
+ * Ships as the fallback so production deployments always have error visibility,
+ * even without an `instrumentation.ts` logger export. Output is one line per
+ * event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+ *
+ * Format:
+ *   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+ *   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+ *   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+ *
+ * Behavior:
+ * - Suppressed entirely in dev mode (dev logging handles all output)
+ * - `debug` suppressed unless TIMBER_DEBUG is set
+ * - Replaced entirely when a custom logger is set via `setLogger()`
+ *
+ * See design/17-logging.md §"DefaultLogger"
+ */
+
+import { isDevMode, isDebug } from './debug.js';
+import { formatSsrError } from './error-formatter.js';
+import type { TimberLogger } from './logger.js';
+
+/**
+ * Format data fields as `key=value` pairs for human-readable output.
+ * - `error` key is serialized via formatSsrError for stack trace cleanup
+ * - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+ * - Other values are stringified inline
+ */
+function formatDataFields(data?: Record<string, unknown>): string {
+  if (!data) return '';
+
+  const parts: string[] = [];
+  let traceId: string | undefined;
+
+  for (const [key, value] of Object.entries(data)) {
+    if (key === 'trace_id') {
+      // Defer trace_id to the end
+      traceId = typeof value === 'string' ? value : String(value);
+      continue;
+    }
+    if (key === 'error') {
+      // Serialize errors with formatSsrError for clean output
+      parts.push(`error=${formatSsrError(value)}`);
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+    parts.push(`${key}=${value}`);
+  }
+
+  // trace_id always last, truncated to 8 chars for readability
+  if (traceId) {
+    parts.push(`trace_id=${traceId.slice(0, 8)}`);
+  }
+
+  return parts.length > 0 ? '  ' + parts.join('  ') : '';
+}
+
+/** Pad level string to fixed width for alignment. */
+function padLevel(level: string): string {
+  return level.padEnd(5);
+}
+
+export function createDefaultLogger(): TimberLogger {
+  return {
+    error(msg: string, data?: Record<string, unknown>): void {
+      if (isDevMode()) return;
+      const fields = formatDataFields(data);
+      // Use process.stderr.write for consistent output (no extra newline handling)
+      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\n`);
+    },
+
+    warn(msg: string, data?: Record<string, unknown>): void {
+      if (isDevMode()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('WARN')}  ${msg}${fields}\n`);
+    },
+
+    info(msg: string, data?: Record<string, unknown>): void {
+      if (isDevMode()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('INFO')}  ${msg}${fields}\n`);
+    },
+
+    debug(msg: string, data?: Record<string, unknown>): void {
+      // debug is suppressed in dev (dev logger handles it) and in
+      // production unless TIMBER_DEBUG is explicitly set.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('DEBUG')}  ${msg}${fields}\n`);
+    },
+  };
+}

package/src/server/flush.ts

@@ -9,6 +9,7 @@
  */
 
 import { DenySignal, RedirectSignal, RenderError } from './primitives.js';
+import { logRenderError } from './logger.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -169,7 +170,7 @@ function handleSignal(error: unknown, responseHeaders: Headers): FlushResult {
   }
 
   // Unknown error → HTTP 500
-  console.error('[timber] Unhandled render-phase error:', error);
+  logRenderError({ method: '', path: '', error });
   return {
     response: new Response(null, {
       status: 500,

package/src/server/html-injectors.ts

@@ -17,6 +17,7 @@ import {
   type FlightInjectionState,
   type FlightInjectionEvent,
 } from './flight-injection-state.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
 
 /**
  * Inject HTML content before a closing tag in the stream.
@@ -118,11 +119,13 @@ export function injectScripts(
  * flightInitScript() — see flight-scripts.ts.
  */
 export function createInlinedRscStream(
-  rscStream: ReadableStream<Uint8Array>
+  rscStream: ReadableStream<Uint8Array>,
+  renderTimeoutMs?: number
 ): ReadableStream<Uint8Array> {
   const encoder = new TextEncoder();
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
+  const timeoutMs = renderTimeoutMs ?? 30_000;
 
   return new ReadableStream<Uint8Array>({
     // No bootstrap signal here — the init script is in <head> via
@@ -130,7 +133,11 @@ export function createInlinedRscStream(
     // __timber_f array exists before any chunk scripts execute.
     async pull(controller) {
       try {
-        const { done, value } = await rscReader.read();
+        const readPromise = rscReader.read();
+        const { done, value } =
+          timeoutMs > 0
+            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
         if (done) {
           controller.close();
           return;
@@ -140,6 +147,9 @@ export function createInlinedRscStream(
           controller.enqueue(encoder.encode(flightChunkScript(decoded)));
         }
       } catch (error) {
+        if (error instanceof RenderTimeoutError) {
+          rscReader.cancel(error).catch(() => {});
+        }
         controller.error(error);
       }
     },
@@ -173,7 +183,8 @@ export function createInlinedRscStream(
  * Inspired by Next.js createFlightDataInjectionTransformStream.
  */
 function createFlightInjectionTransform(
-  rscScriptStream: ReadableStream<Uint8Array>
+  rscScriptStream: ReadableStream<Uint8Array>,
+  renderTimeoutMs?: number
 ): TransformStream<Uint8Array, Uint8Array> {
   const encoder = new TextEncoder();
   const decoder = new TextDecoder();
@@ -181,6 +192,7 @@ function createFlightInjectionTransform(
   const suffixBytes = encoder.encode(suffix);
 
   const rscReader = rscScriptStream.getReader();
+  const timeoutMs = renderTimeoutMs ?? 30_000;
 
   const machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
     initial: { phase: 'init' },
@@ -205,7 +217,15 @@ function createFlightInjectionTransform(
 
     try {
       for (;;) {
-        const { done, value } = await rscReader.read();
+        // Guard each RSC read with a timeout so a permanently hung
+        // RSC stream eventually aborts. When timeoutMs <= 0, the
+        // guard is disabled. See design/02-rendering-pipeline.md
+        // §"Streaming Constraints".
+        const readPromise = rscReader.read();
+        const { done, value } =
+          timeoutMs > 0
+            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
         if (done) {
           machine.send({ type: 'PULL_DONE' });
           return;
@@ -220,6 +240,10 @@ function createFlightInjectionTransform(
         }
       }
     } catch (err) {
+      // On timeout, cancel the RSC reader to release resources.
+      if (err instanceof RenderTimeoutError) {
+        rscReader.cancel(err).catch(() => {});
+      }
       machine.send({ type: 'PULL_ERROR', error: err });
     }
   }
@@ -326,16 +350,17 @@ function createFlightInjectionTransform(
  */
 export function injectRscPayload(
   htmlStream: ReadableStream<Uint8Array>,
-  rscStream: ReadableStream<Uint8Array> | undefined
+  rscStream: ReadableStream<Uint8Array> | undefined,
+  renderTimeoutMs?: number
 ): ReadableStream<Uint8Array> {
   if (!rscStream) return htmlStream;
 
   // Transform RSC binary stream → stream of <script> tags
-  const rscScriptStream = createInlinedRscStream(rscStream);
+  const rscScriptStream = createInlinedRscStream(rscStream, renderTimeoutMs);
 
   // Single transform: strip </body></html>, inject RSC scripts at
   // body level, re-emit suffix at the very end.
-  return htmlStream.pipeThrough(createFlightInjectionTransform(rscScriptStream));
+  return htmlStream.pipeThrough(createFlightInjectionTransform(rscScriptStream, renderTimeoutMs));
 }
 
 /**

package/src/server/index.ts

@@ -222,3 +222,7 @@ export type { DevWarningConfig } from './dev-warnings';
 // Design doc: design/07-routing.md §"route.ts — API Endpoints"
 export { handleRouteRequest, resolveAllowedMethods } from './route-handler';
 export type { RouteModule, RouteHandler, HttpMethod } from './route-handler';
+
+// Render timeout — design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+export { RenderTimeoutError } from './render-timeout';
+export type { RenderTimeout } from './render-timeout';

package/src/server/logger.ts

@@ -1,16 +1,15 @@
 /**
  * Logger — structured logging with environment-aware formatting.
  *
- * timber.js does not ship a logger. Users export any object with
- * info/warn/error/debug methods from instrumentation.ts and the framework
- * picks it up. Silent if no logger export is present.
+ * timber.js ships a DefaultLogger that writes human-readable lines to stderr
+ * in production. Users can export a custom logger from instrumentation.ts to
+ * replace it with pino, winston, or any TimberLogger-compatible object.
  *
  * See design/17-logging.md §"Production Logging"
  */
 
 import { getTraceStore } from './tracing.js';
-import { formatSsrError } from './error-formatter.js';
-import { isDebug } from './debug.js';
+import { createDefaultLogger } from './default-logger.js';
 
 // ─── Logger Interface ─────────────────────────────────────────────────────
 
@@ -24,21 +23,24 @@ export interface TimberLogger {
 
 // ─── Logger Registry ──────────────────────────────────────────────────────
 
-let _logger: TimberLogger | null = null;
+// Initialize with DefaultLogger so production errors are never silent.
+// Replaced when setLogger() is called from instrumentation.ts.
+let _logger: TimberLogger = createDefaultLogger();
 
 /**
  * Set the user-provided logger. Called by the instrumentation loader
- * when it finds a `logger` export in instrumentation.ts.
+ * when it finds a `logger` export in instrumentation.ts. Replaces
+ * the DefaultLogger entirely.
  */
 export function setLogger(logger: TimberLogger): void {
   _logger = logger;
 }
 
 /**
- * Get the current logger, or null if none configured.
- * Framework-internal — used at framework event points to emit structured logs.
+ * Get the current logger. Always non-null — returns DefaultLogger when
+ * no custom logger is configured.
  */
-export function getLogger(): TimberLogger | null {
+export function getLogger(): TimberLogger {
   return _logger;
 }
 
@@ -71,12 +73,12 @@ export function logRequestCompleted(data: {
   /** Number of concurrent in-flight requests (including this one) at completion time. */
   concurrency?: number;
 }): void {
-  _logger?.info('request completed', withTraceContext(data));
+  _logger.info('request completed', withTraceContext(data));
 }
 
 /** Log request received. Level: debug. */
 export function logRequestReceived(data: { method: string; path: string }): void {
-  _logger?.debug('request received', withTraceContext(data));
+  _logger.debug('request received', withTraceContext(data));
 }
 
 /** Log a slow request warning. Level: warn. */
@@ -88,7 +90,7 @@ export function logSlowRequest(data: {
   /** Number of concurrent in-flight requests at the time the slow request completed. */
   concurrency?: number;
 }): void {
-  _logger?.warn('slow request exceeded threshold', withTraceContext(data));
+  _logger.warn('slow request exceeded threshold', withTraceContext(data));
 }
 
 /** Log middleware short-circuit. Level: debug. */
@@ -97,54 +99,55 @@ export function logMiddlewareShortCircuit(data: {
   path: string;
   status: number;
 }): void {
-  _logger?.debug('middleware short-circuited', withTraceContext(data));
+  _logger.debug('middleware short-circuited', withTraceContext(data));
 }
 
 /** Log unhandled error in middleware phase. Level: error. */
 export function logMiddlewareError(data: { method: string; path: string; error: unknown }): void {
-  if (_logger) {
-    _logger.error('unhandled error in middleware phase', withTraceContext(data));
-  } else if (isDebug()) {
-    console.error('[timber] middleware error', data.error);
-  }
+  _logger.error('unhandled error in middleware phase', withTraceContext(data));
 }
 
 /** Log unhandled render-phase error. Level: error. */
 export function logRenderError(data: { method: string; path: string; error: unknown }): void {
-  if (_logger) {
-    _logger.error('unhandled render-phase error', withTraceContext(data));
-  } else if (isDebug()) {
-    // No logger configured — fall back to console.error in dev with
-    // cleaned-up error messages (vendor paths rewritten, hints added).
-    console.error('[timber] render error:', formatSsrError(data.error));
-  }
+  _logger.error('unhandled render-phase error', withTraceContext(data));
 }
 
 /** Log proxy.ts uncaught error. Level: error. */
 export function logProxyError(data: { error: unknown }): void {
-  if (_logger) {
-    _logger.error('proxy.ts threw uncaught error', withTraceContext(data));
-  } else if (isDebug()) {
-    console.error('[timber] proxy error', data.error);
-  }
+  _logger.error('proxy.ts threw uncaught error', withTraceContext(data));
+}
+
+/** Log unhandled error in server action. Level: error. */
+export function logActionError(data: { method: string; path: string; error: unknown }): void {
+  _logger.error('unhandled server action error', withTraceContext(data));
+}
+
+/** Log unhandled error in route handler. Level: error. */
+export function logRouteError(data: { method: string; path: string; error: unknown }): void {
+  _logger.error('unhandled route handler error', withTraceContext(data));
+}
+
+/** Log SSR streaming error (post-shell). Level: error. */
+export function logStreamingError(data: { error: unknown }): void {
+  _logger.error('SSR streaming error (post-shell)', withTraceContext(data));
 }
 
 /** Log waitUntil() adapter missing (once at startup). Level: warn. */
 export function logWaitUntilUnsupported(): void {
-  _logger?.warn('adapter does not support waitUntil()');
+  _logger.warn('adapter does not support waitUntil()');
 }
 
 /** Log waitUntil() promise rejection. Level: warn. */
 export function logWaitUntilRejected(data: { error: unknown }): void {
-  _logger?.warn('waitUntil() promise rejected', withTraceContext(data));
+  _logger.warn('waitUntil() promise rejected', withTraceContext(data));
 }
 
 /** Log staleWhileRevalidate refetch failure. Level: warn. */
 export function logSwrRefetchFailed(data: { cacheKey: string; error: unknown }): void {
-  _logger?.warn('staleWhileRevalidate refetch failed', withTraceContext(data));
+  _logger.warn('staleWhileRevalidate refetch failed', withTraceContext(data));
 }
 
 /** Log cache miss. Level: debug. */
 export function logCacheMiss(data: { cacheKey: string }): void {
-  _logger?.debug('timber.cache MISS', withTraceContext(data));
+  _logger.debug('timber.cache MISS', withTraceContext(data));
 }