@timber-js/app 0.1.1 → 0.1.3

package/src/server/instrumentation.ts

@@ -0,0 +1,136 @@
+/**
+ * Instrumentation — loads and runs the user's instrumentation.ts file.
+ *
+ * instrumentation.ts is a file convention at the project root that exports:
+ * - register() — called once at server startup, before the first request
+ * - onRequestError() — called for every unhandled server error
+ * - logger — any object with info/warn/error/debug methods
+ *
+ * See design/17-logging.md §"instrumentation.ts — The Entry Point"
+ */
+
+import { setLogger, type TimberLogger } from './logger.js';
+
+// ─── Instrumentation Types ────────────────────────────────────────────────
+
+export type InstrumentationOnRequestError = (
+  error: unknown,
+  request: InstrumentationRequestInfo,
+  context: InstrumentationErrorContext
+) => void | Promise<void>;
+
+export interface InstrumentationRequestInfo {
+  /** HTTP method: 'GET', 'POST', etc. */
+  method: string;
+  /** Request path: '/dashboard/projects/123' */
+  path: string;
+  /** Request headers as a plain object. */
+  headers: Record<string, string>;
+}
+
+export interface InstrumentationErrorContext {
+  /** Which pipeline phase the error occurred in. */
+  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route';
+  /** The route pattern: '/dashboard/projects/[id]' */
+  routePath: string;
+  /** Type of route that was matched. */
+  routeType: 'page' | 'route' | 'action';
+  /** Always set — OTEL trace ID or UUID fallback. */
+  traceId: string;
+}
+
+// ─── Instrumentation Module Shape ─────────────────────────────────────────
+
+interface InstrumentationModule {
+  register?: () => void | Promise<void>;
+  onRequestError?: InstrumentationOnRequestError;
+  logger?: TimberLogger;
+}
+
+// ─── State ────────────────────────────────────────────────────────────────
+//
+// Intentional per-app singletons (not per-request). Instrumentation loads
+// once at server startup and persists for the lifetime of the process/isolate.
+// These must NOT be migrated to ALS — they are correctly scoped to the app.
+
+let _initialized = false;
+let _onRequestError: InstrumentationOnRequestError | null = null;
+
+/**
+ * Load and initialize the user's instrumentation.ts module.
+ *
+ * - Awaits register() before returning (server blocks on this).
+ * - Picks up the logger export and wires it into the framework logger.
+ * - Stores onRequestError for later invocation.
+ *
+ * @param loader - Function that dynamically imports the user's instrumentation module.
+ *                 Returns null if no instrumentation.ts exists.
+ */
+export async function loadInstrumentation(
+  loader: () => Promise<InstrumentationModule | null>
+): Promise<void> {
+  if (_initialized) return;
+  _initialized = true;
+
+  let mod: InstrumentationModule | null;
+  try {
+    mod = await loader();
+  } catch (error) {
+    console.error('[timber] Failed to load instrumentation.ts:', error);
+    return;
+  }
+
+  if (!mod) return;
+
+  // Wire up the logger export
+  if (mod.logger && typeof mod.logger.info === 'function') {
+    setLogger(mod.logger);
+  }
+
+  // Store onRequestError for later
+  if (typeof mod.onRequestError === 'function') {
+    _onRequestError = mod.onRequestError;
+  }
+
+  // Await register() — server does not accept requests until this resolves
+  if (typeof mod.register === 'function') {
+    try {
+      await mod.register();
+    } catch (error) {
+      console.error('[timber] instrumentation.ts register() threw:', error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Call the user's onRequestError hook. Catches and logs any errors thrown
+ * by the hook itself — it must not affect the response.
+ */
+export async function callOnRequestError(
+  error: unknown,
+  request: InstrumentationRequestInfo,
+  context: InstrumentationErrorContext
+): Promise<void> {
+  if (!_onRequestError) return;
+  try {
+    await _onRequestError(error, request, context);
+  } catch (hookError) {
+    console.error('[timber] onRequestError hook threw:', hookError);
+  }
+}
+
+/**
+ * Check if onRequestError is registered.
+ */
+export function hasOnRequestError(): boolean {
+  return _onRequestError !== null;
+}
+
+/**
+ * Reset instrumentation state. Test-only.
+ */
+export function resetInstrumentation(): void {
+  _initialized = false;
+  _onRequestError = null;
+}

package/src/server/logger.ts

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ *
+ * See design/17-logging.md §"Production Logging"
+ */
+
+import { getTraceStore } from './tracing.js';
+import { formatSsrError } from './error-formatter.js';
+
+// ─── Logger Interface ─────────────────────────────────────────────────────
+
+/** Any object with standard log methods satisfies this — pino, winston, consola, console. */
+export interface TimberLogger {
+  info(msg: string, data?: Record<string, unknown>): void;
+  warn(msg: string, data?: Record<string, unknown>): void;
+  error(msg: string, data?: Record<string, unknown>): void;
+  debug(msg: string, data?: Record<string, unknown>): void;
+}
+
+// ─── Logger Registry ──────────────────────────────────────────────────────
+
+let _logger: TimberLogger | null = null;
+
+/**
+ * Set the user-provided logger. Called by the instrumentation loader
+ * when it finds a `logger` export in instrumentation.ts.
+ */
+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.
+ */
+export function getLogger(): TimberLogger | null {
+  return _logger;
+}
+
+// ─── Framework Log Helpers ────────────────────────────────────────────────
+
+/**
+ * Inject trace_id and span_id into log data for log–trace correlation.
+ * Always injects trace_id (never undefined). Injects span_id only when OTEL is active.
+ */
+function withTraceContext(data?: Record<string, unknown>): Record<string, unknown> {
+  const store = getTraceStore();
+  const enriched: Record<string, unknown> = { ...data };
+  if (store) {
+    enriched.trace_id = store.traceId;
+    if (store.spanId) {
+      enriched.span_id = store.spanId;
+    }
+  }
+  return enriched;
+}
+
+// ─── Framework Event Emitters ─────────────────────────────────────────────
+
+/** Log a completed request. Level: info. */
+export function logRequestCompleted(data: {
+  method: string;
+  path: string;
+  status: number;
+  durationMs: number;
+}): void {
+  _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));
+}
+
+/** Log a slow request warning. Level: warn. */
+export function logSlowRequest(data: {
+  method: string;
+  path: string;
+  durationMs: number;
+  threshold: number;
+}): void {
+  _logger?.warn('slow request exceeded threshold', withTraceContext(data));
+}
+
+/** Log middleware short-circuit. Level: debug. */
+export function logMiddlewareShortCircuit(data: {
+  method: string;
+  path: string;
+  status: number;
+}): void {
+  _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 (process.env.NODE_ENV !== 'production') {
+    console.error('[timber] middleware error', data.error);
+  }
+}
+
+/** 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 (process.env.NODE_ENV !== 'production') {
+    // 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));
+  }
+}
+
+/** 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 (process.env.NODE_ENV !== 'production') {
+    console.error('[timber] proxy error', data.error);
+  }
+}
+
+/** Log waitUntil() adapter missing (once at startup). Level: warn. */
+export function logWaitUntilUnsupported(): void {
+  _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));
+}
+
+/** Log staleWhileRevalidate refetch failure. Level: warn. */
+export function logSwrRefetchFailed(data: { cacheKey: string; error: unknown }): void {
+  _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));
+}

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

@@ -0,0 +1,215 @@
+/**
+ * Manifest-compatible status-code file resolver.
+ *
+ * The existing status-code-resolver.ts works with SegmentNode (Map-based).
+ * This module works with ManifestSegmentNode (object-based) for use at
+ * runtime in the RSC/SSR entries, where the route manifest provides
+ * plain objects instead of Maps.
+ *
+ * Supports two format families:
+ * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
+ * - 'json': .json status files → raw JSON response, no React
+ *
+ * Follows the same fallback chains as status-code-resolver.ts:
+ *
+ * **Component chain (4xx):**
+ *   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)
+ *   Pass 4 — framework default (returns null)
+ *
+ * **JSON chain (4xx):**
+ *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
+ *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
+ *
+ * See design/10-error-handling.md §"Status-Code Files"
+ */
+
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** A file reference in the manifest (lazy import + path). */
+interface ManifestFile {
+  load: () => Promise<unknown>;
+  filePath: string;
+}
+
+/** How the status-code file was matched. */
+export type ManifestStatusFileKind =
+  | 'exact' // e.g. 403.tsx matched status 403
+  | 'category' // e.g. 4xx.tsx matched status 403
+  | 'legacy' // e.g. not-found.tsx matched status 404
+  | 'error'; // error.tsx as last resort
+
+/** Response format family for status-code resolution. */
+export type ManifestStatusFileFormat = 'component' | 'json';
+
+/** Result of resolving a status-code file from manifest segments. */
+export interface ManifestStatusFileResolution {
+  /** The matched manifest file (has load() and filePath). */
+  file: ManifestFile;
+  /** The HTTP status code (always the original status, not the file's code). */
+  status: number;
+  /** How the file was matched. */
+  kind: ManifestStatusFileKind;
+  /** Index into the segments array where the file was found. */
+  segmentIndex: number;
+}
+
+// ─── Legacy Compat Mapping ───────────────────────────────────────────────────
+
+const LEGACY_FILE_TO_STATUS: Record<string, number> = {
+  'not-found': 404,
+  'forbidden': 403,
+  'unauthorized': 401,
+};
+
+// ─── Resolver ────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the status-code file to render for a given HTTP status code,
+ * using manifest segment nodes (plain objects, not Maps).
+ *
+ * @param status - The HTTP status code (4xx or 5xx).
+ * @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 resolveManifestStatusFile(
+  status: number,
+  segments: ReadonlyArray<ManifestSegmentNode>,
+  format: ManifestStatusFileFormat = 'component'
+): ManifestStatusFileResolution | 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)
+ */
+function resolve4xx(
+  status: number,
+  segments: ReadonlyArray<ManifestSegmentNode>
+): ManifestStatusFileResolution | 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[statusStr];
+    if (exact) {
+      return { file: exact, status, kind: 'exact', segmentIndex: i };
+    }
+
+    // Category catch-all
+    const category = segment.statusFiles['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[name];
+        if (file) {
+          return { file, status, kind: 'legacy', segmentIndex: i };
+        }
+      }
+    }
+  }
+
+  // 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 };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 5xx component fallback chain (single pass, per-segment):
+ *   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
+ */
+function resolve5xx(
+  status: number,
+  segments: ReadonlyArray<ManifestSegmentNode>
+): ManifestStatusFileResolution | null {
+  const statusStr = String(status);
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i];
+
+    if (segment.statusFiles) {
+      const exact = segment.statusFiles[statusStr];
+      if (exact) {
+        return { file: exact, status, kind: 'exact', segmentIndex: i };
+      }
+
+      const categoryKey = '5xx';
+      const category = segment.statusFiles[categoryKey];
+      if (category) {
+        return { file: category, status, kind: 'category', segmentIndex: i };
+      }
+    }
+
+    if (segment.error) {
+      return { file: segment.error, status, kind: 'error', segmentIndex: i };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * JSON fallback chain (for both 4xx and 5xx):
+ *   At each segment (leaf → root): {status}.json → {category}.json
+ *   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
+ */
+function resolveJson(
+  status: number,
+  segments: ReadonlyArray<ManifestSegmentNode>
+): ManifestStatusFileResolution | 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[statusStr];
+    if (exact) {
+      return { file: exact, status, kind: 'exact', segmentIndex: i };
+    }
+
+    const category = segment.jsonStatusFiles[categoryKey];
+    if (category) {
+      return { file: category, status, kind: 'category', segmentIndex: i };
+    }
+  }
+
+  return null;
+}