@timber-js/app 0.1.1 → 0.1.2

package/src/server/tracing.ts

@@ -0,0 +1,281 @@
+/**
+ * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
+ *
+ * traceId() 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.
+ *
+ * See design/17-logging.md §"trace_id is Always Set"
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+
+// ─── ALS Store ────────────────────────────────────────────────────────────
+
+export interface TraceStore {
+  /** 32-char lowercase hex trace ID (OTEL or UUID fallback). */
+  traceId: string;
+  /** OTEL span ID if available, undefined otherwise. */
+  spanId?: string;
+}
+
+const traceAls = new AsyncLocalStorage<TraceStore>();
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Returns the current request's trace ID — always a 32-char lowercase hex string.
+ *
+ * With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).
+ * Without OTEL: crypto.randomUUID() with hyphens stripped.
+ *
+ * Throws if called outside a request context (no ALS store).
+ */
+export function traceId(): string {
+  const store = traceAls.getStore();
+  if (!store) {
+    throw new Error(
+      '[timber] traceId() called outside of a request context. ' +
+        'It can only be used in middleware, access checks, server components, and server actions.'
+    );
+  }
+  return store.traceId;
+}
+
+/**
+ * Returns the current OTEL span ID if available, undefined otherwise.
+ */
+export function spanId(): string | undefined {
+  return traceAls.getStore()?.spanId;
+}
+
+// ─── Framework-Internal Helpers ───────────────────────────────────────────
+
+/**
+ * Generate a 32-char lowercase hex ID from crypto.randomUUID().
+ * Same format as OTEL trace IDs — zero-friction upgrade path.
+ */
+export function generateTraceId(): string {
+  return randomUUID().replace(/-/g, '');
+}
+
+/**
+ * Run a callback within a trace context. Used by the pipeline to establish
+ * per-request ALS scope.
+ */
+export function runWithTraceId<T>(id: string, fn: () => T): T {
+  return traceAls.run({ traceId: id }, fn);
+}
+
+/**
+ * Replace the trace ID in the current ALS store. Used when OTEL creates
+ * a root span and we want to switch from the UUID fallback to the real
+ * OTEL trace ID.
+ */
+export function replaceTraceId(newTraceId: string, newSpanId?: string): void {
+  const store = traceAls.getStore();
+  if (store) {
+    store.traceId = newTraceId;
+    store.spanId = newSpanId;
+  }
+}
+
+/**
+ * Update the span ID in the current ALS store. Used when entering a new
+ * OTEL span to keep log–trace correlation accurate.
+ */
+export function updateSpanId(newSpanId: string | undefined): void {
+  const store = traceAls.getStore();
+  if (store) {
+    store.spanId = newSpanId;
+  }
+}
+
+/**
+ * Get the current trace store, or undefined if outside a request context.
+ * Framework-internal — use traceId()/spanId() in user code.
+ */
+export function getTraceStore(): TraceStore | undefined {
+  return traceAls.getStore();
+}
+
+// ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────
+
+/**
+ * Initialize a minimal OTEL SDK in dev mode so spans are recorded and
+ * fed to the DevSpanProcessor for dev log output.
+ *
+ * If the user already configured an OTEL SDK in register(), we add
+ * our DevSpanProcessor alongside theirs. If no SDK is configured,
+ * we create a BasicTracerProvider with our processor.
+ *
+ * Only called in dev mode — zero overhead in production.
+ */
+export async function initDevTracing(
+  config: import('./dev-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');
+  const processor = new DevSpanProcessor(config);
+
+  // Register a context manager so OTEL can propagate the active span
+  // across async boundaries. Without this, startActiveSpan can't make
+  // spans "active" — child spans get random trace IDs and getActiveSpan()
+  // returns undefined.
+  const contextManager = new AsyncLocalStorageContextManager();
+  contextManager.enable();
+  api.context.setGlobalContextManager(contextManager);
+
+  // Create a minimal TracerProvider with our DevSpanProcessor.
+  // If the user also configures an SDK in register(), their provider
+  // will coexist — the global provider set last wins for new tracers,
+  // but our processor captures all spans from the timber.js tracer.
+  const provider = new BasicTracerProvider({
+    spanProcessors: [processor],
+  });
+  api.trace.setGlobalTracerProvider(provider);
+
+  // Reset cached tracer so next getTracer() picks up the new provider
+  _tracer = undefined;
+}
+
+// ─── OTEL Span Helpers ───────────────────────────────────────────────────
+
+/**
+ * Attempt to get the @opentelemetry/api tracer. Returns undefined if the
+ * package is not installed or no SDK is registered.
+ *
+ * timber.js depends on @opentelemetry/api as the vendor-neutral interface.
+ * The API is a no-op by default — spans are only emitted when the developer
+ * initializes an SDK in register().
+ */
+let _otelApi: typeof import('@opentelemetry/api') | null | undefined;
+
+async function getOtelApi(): Promise<typeof import('@opentelemetry/api') | null> {
+  if (_otelApi === undefined) {
+    try {
+      _otelApi = await import('@opentelemetry/api');
+    } catch {
+      _otelApi = null;
+    }
+  }
+  return _otelApi;
+}
+
+/** OTEL tracer instance, lazily created. */
+let _tracer: import('@opentelemetry/api').Tracer | null | undefined;
+
+/**
+ * Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.
+ */
+export async function getTracer(): Promise<import('@opentelemetry/api').Tracer | null> {
+  if (_tracer === undefined) {
+    const api = await getOtelApi();
+    if (api) {
+      _tracer = api.trace.getTracer('timber.js');
+    } else {
+      _tracer = null;
+    }
+  }
+  return _tracer;
+}
+
+/**
+ * Run a function within an OTEL span. If OTEL is not available, runs the function
+ * directly without any span overhead.
+ *
+ * Automatically:
+ * - Creates the span as a child of the current context
+ * - Updates the ALS span ID for log–trace correlation
+ * - Ends the span when the function completes
+ * - Records exceptions on error
+ */
+export async function withSpan<T>(
+  name: string,
+  attributes: Record<string, string | number | boolean>,
+  fn: () => T | Promise<T>
+): Promise<T> {
+  const tracer = await getTracer();
+  if (!tracer) {
+    return fn();
+  }
+
+  const api = (await getOtelApi())!;
+  return tracer.startActiveSpan(name, { attributes }, async (span) => {
+    const prevSpanId = spanId();
+    updateSpanId(span.spanContext().spanId);
+    try {
+      const result = await fn();
+      span.setStatus({ code: api.SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.setStatus({ code: api.SpanStatusCode.ERROR });
+      if (error instanceof Error) {
+        span.recordException(error);
+      }
+      throw error;
+    } finally {
+      span.end();
+      updateSpanId(prevSpanId);
+    }
+  });
+}
+
+/**
+ * Set an attribute on the current active span (if any).
+ * Used for setting span attributes after span creation (e.g. timber.result on access spans).
+ */
+export async function setSpanAttribute(
+  key: string,
+  value: string | number | boolean
+): Promise<void> {
+  const api = await getOtelApi();
+  if (!api) return;
+
+  const activeSpan = api.trace.getActiveSpan();
+  if (activeSpan) {
+    activeSpan.setAttribute(key, value);
+  }
+}
+
+/**
+ * Add a span event to the current active span (if any).
+ * Used for timber.cache HIT/MISS events — recorded as span events, not child spans.
+ */
+export async function addSpanEvent(
+  name: string,
+  attributes?: Record<string, string | number | boolean>
+): Promise<void> {
+  const api = await getOtelApi();
+  if (!api) return;
+
+  const activeSpan = api.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.
+ */
+export async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {
+  const api = await getOtelApi();
+  if (!api) return undefined;
+
+  const activeSpan = api.trace.getActiveSpan();
+  if (!activeSpan) return undefined;
+
+  const ctx = activeSpan.spanContext();
+  // OTEL uses "0000000000000000" as invalid trace IDs
+  if (!ctx.traceId || ctx.traceId === '00000000000000000000000000000000') {
+    return undefined;
+  }
+
+  return { traceId: ctx.traceId, spanId: ctx.spanId };
+}

package/src/server/tree-builder.ts

@@ -0,0 +1,354 @@
+/**
+ * Element tree construction for timber.js rendering.
+ *
+ * Builds a unified React element tree from a matched segment chain, bottom-up:
+ *   page → status-code error boundaries → access gates → layout → repeat up segment chain
+ *
+ * The tree is rendered via a single `renderToReadableStream` call,
+ * giving one `React.cache` scope for the entire route.
+ *
+ * See design/02-rendering-pipeline.md §"Element Tree Construction"
+ */
+
+import type { SegmentNode, RouteFile } from '#/routing/types.js';
+import { TimberErrorBoundary } from '#/client/error-boundary.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** A loaded module for a route file convention. */
+export interface LoadedModule {
+  /** The default export (component, access function, etc.) */
+  default?: unknown;
+  /** Named exports (for route.ts method handlers, metadata, etc.) */
+  [key: string]: unknown;
+}
+
+/** Function that loads a route file's module. */
+export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
+
+/** A React element — kept opaque to avoid a React dependency in this module. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ReactElement = any;
+
+/** Function that creates a React element. Matches React.createElement signature. */
+export type CreateElement = (
+  type: unknown,
+  props: Record<string, unknown> | null,
+  ...children: unknown[]
+) => ReactElement;
+
+/**
+ * Resolved slot content for a layout.
+ * Key is slot name (without @), value is the element tree for that slot.
+ */
+export type SlotElements = Map<string, ReactElement>;
+
+/** Configuration for the tree builder. */
+export interface TreeBuilderConfig {
+  /** The matched segment chain from root to leaf. */
+  segments: SegmentNode[];
+  /** Route params extracted by the matcher (catch-all segments produce string[]). */
+  params: Record<string, string | string[]>;
+  /** Parsed search params (typed or URLSearchParams). */
+  searchParams: unknown;
+  /** Loads a route file's module. */
+  loadModule: ModuleLoader;
+  /** React.createElement or equivalent. */
+  createElement: CreateElement;
+}
+
+// ─── Component wrappers ──────────────────────────────────────────────────────
+
+/**
+ * Framework-injected access gate component.
+ *
+ * When `verdict` is provided (from the pre-render pass), AccessGate replays
+ * the stored result synchronously — no re-execution, no async, immune to
+ * Suspense timing. When `verdict` is absent, falls back to calling `accessFn`
+ * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
+ */
+export interface AccessGateProps {
+  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
+  params: Record<string, string | string[]>;
+  searchParams: unknown;
+  /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
+  segmentName?: string;
+  /**
+   * Pre-computed verdict from the pre-render pass. When set, AccessGate
+   * replays this verdict synchronously instead of calling accessFn.
+   * - 'pass': render children
+   * - DenySignal/RedirectSignal: throw synchronously
+   */
+  verdict?: 'pass' | import('./primitives.js').DenySignal | import('./primitives.js').RedirectSignal;
+  children: ReactElement;
+}
+
+/**
+ * Framework-injected slot access gate component.
+ * On denial, renders denied.tsx → default.tsx → null instead of failing the page.
+ */
+export interface SlotAccessGateProps {
+  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
+  params: Record<string, string | string[]>;
+  searchParams: unknown;
+  deniedFallback: ReactElement | null;
+  defaultFallback: ReactElement | null;
+  children: ReactElement;
+}
+
+/**
+ * Framework-injected error boundary wrapper.
+ * Wraps content with status-code error boundary handling.
+ */
+export interface ErrorBoundaryProps {
+  fallbackComponent: ReactElement | null;
+  status?: number;
+  children: ReactElement;
+}
+
+// ─── Tree Builder ────────────────────────────────────────────────────────────
+
+/**
+ * Result of building the element tree.
+ */
+export interface TreeBuildResult {
+  /** The root React element tree ready for renderToReadableStream. */
+  tree: ReactElement;
+  /** Whether the leaf segment is a route.ts (API endpoint) rather than a page. */
+  isApiRoute: boolean;
+}
+
+/**
+ * Build the unified element tree from a matched segment chain.
+ *
+ * Construction is bottom-up:
+ *   1. Start with the page component (leaf segment)
+ *   2. Wrap in status-code error boundaries (fallback chain)
+ *   3. Wrap in AccessGate (if segment has access.ts)
+ *   4. Pass as children to the segment's layout
+ *   5. Repeat up the segment chain to root
+ *
+ * Parallel slots are resolved at each layout level and composed as named props.
+ */
+export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult> {
+  const { segments, params, searchParams, loadModule, createElement } = config;
+
+  if (segments.length === 0) {
+    throw new Error('[timber] buildElementTree: empty segment chain');
+  }
+
+  const leaf = segments[segments.length - 1];
+
+  // API routes (route.ts) don't build a React tree
+  if (leaf.route && !leaf.page) {
+    return { tree: null, isApiRoute: true };
+  }
+
+  // Start with the page component
+  const pageModule = leaf.page ? await loadModule(leaf.page) : null;
+  const PageComponent = pageModule?.default as ((...args: unknown[]) => ReactElement) | undefined;
+
+  if (!PageComponent) {
+    throw new Error(
+      `[timber] No page component found for route at ${leaf.urlPath}. ` +
+        'Each route must have a page.tsx or route.ts.'
+    );
+  }
+
+  // Build the page element with params and searchParams props
+  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+
+  // Build tree bottom-up: wrap page, then walk segments from leaf to root
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i];
+
+    // Wrap in error boundaries (status-code files + error.tsx)
+    element = await wrapWithErrorBoundaries(segment, element, loadModule, createElement);
+
+    // Wrap in AccessGate if segment has access.ts
+    if (segment.access) {
+      const accessModule = await loadModule(segment.access);
+      const accessFn = accessModule.default as AccessGateProps['accessFn'];
+      element = createElement('timber:access-gate', {
+        accessFn,
+        params,
+        searchParams,
+        segmentName: segment.segmentName,
+        children: element,
+      } satisfies AccessGateProps);
+    }
+
+    // Wrap in layout (if exists and not the leaf's page-level wrapping)
+    if (segment.layout) {
+      const layoutModule = await loadModule(segment.layout);
+      const LayoutComponent = layoutModule.default as
+        | ((...args: unknown[]) => ReactElement)
+        | undefined;
+
+      if (LayoutComponent) {
+        // Resolve parallel slots for this layout
+        const slotProps: Record<string, ReactElement> = {};
+        if (segment.slots.size > 0) {
+          for (const [slotName, slotNode] of segment.slots) {
+            slotProps[slotName] = await buildSlotElement(
+              slotNode,
+              params,
+              searchParams,
+              loadModule,
+              createElement
+            );
+          }
+        }
+
+        element = createElement(LayoutComponent, {
+          ...slotProps,
+          params,
+          searchParams,
+          children: element,
+        });
+      }
+    }
+  }
+
+  return { tree: element, isApiRoute: false };
+}
+
+// ─── Slot Element Builder ────────────────────────────────────────────────────
+
+/**
+ * Build the element tree for a parallel slot.
+ *
+ * Slots have their own access.ts (SlotAccessGate) and error boundaries.
+ * On access denial: denied.tsx → default.tsx → null (graceful degradation).
+ */
+async function buildSlotElement(
+  slotNode: SegmentNode,
+  params: Record<string, string | string[]>,
+  searchParams: unknown,
+  loadModule: ModuleLoader,
+  createElement: CreateElement
+): Promise<ReactElement> {
+  // Load slot page
+  const pageModule = slotNode.page ? await loadModule(slotNode.page) : null;
+  const PageComponent = pageModule?.default as ((...args: unknown[]) => ReactElement) | undefined;
+
+  // Load default.tsx fallback
+  const defaultModule = slotNode.default ? await loadModule(slotNode.default) : null;
+  const DefaultComponent = defaultModule?.default as
+    | ((...args: unknown[]) => ReactElement)
+    | undefined;
+
+  // If no page, render default.tsx or null
+  if (!PageComponent) {
+    return DefaultComponent ? createElement(DefaultComponent, { params, searchParams }) : null;
+  }
+
+  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+
+  // Wrap in error boundaries
+  element = await wrapWithErrorBoundaries(slotNode, element, loadModule, createElement);
+
+  // Wrap in SlotAccessGate if slot has access.ts
+  if (slotNode.access) {
+    const accessModule = await loadModule(slotNode.access);
+    const accessFn = accessModule.default as SlotAccessGateProps['accessFn'];
+
+    // Load denied.tsx
+    const deniedModule = slotNode.denied ? await loadModule(slotNode.denied) : null;
+    const DeniedComponent = deniedModule?.default as
+      | ((...args: unknown[]) => ReactElement)
+      | undefined;
+
+    const deniedFallback = DeniedComponent
+      ? createElement(DeniedComponent, {
+          slot: slotNode.segmentName.replace(/^@/, ''),
+          dangerouslyPassData: undefined,
+        })
+      : null;
+    const defaultFallback = DefaultComponent
+      ? createElement(DefaultComponent, { params, searchParams })
+      : null;
+
+    element = createElement('timber:slot-access-gate', {
+      accessFn,
+      params,
+      searchParams,
+      deniedFallback,
+      defaultFallback,
+      children: element,
+    } satisfies SlotAccessGateProps);
+  }
+
+  return element;
+}
+
+// ─── Error Boundary Wrapping ─────────────────────────────────────────────────
+
+/**
+ * Wrap an element with error boundaries from a segment's status-code files.
+ *
+ * Wrapping order (innermost to outermost):
+ *   1. Specific status files (503.tsx, 429.tsx, etc.)
+ *   2. Category catch-alls (4xx.tsx, 5xx.tsx)
+ *   3. error.tsx (general error boundary)
+ *
+ * This creates the fallback chain described in design/10-error-handling.md.
+ */
+async function wrapWithErrorBoundaries(
+  segment: SegmentNode,
+  element: ReactElement,
+  loadModule: ModuleLoader,
+  createElement: CreateElement
+): Promise<ReactElement> {
+  // Wrapping is applied inside-out. The last wrap call produces the outermost boundary.
+  // Order: specific status → category → error.tsx (outermost)
+
+  if (segment.statusFiles) {
+    // Wrap with specific status files (innermost — highest priority at runtime)
+    for (const [key, file] of segment.statusFiles) {
+      if (key !== '4xx' && key !== '5xx') {
+        const status = parseInt(key, 10);
+        if (!isNaN(status)) {
+          const mod = await loadModule(file);
+          const Component = mod.default;
+          if (Component) {
+            element = createElement(TimberErrorBoundary, {
+              fallbackComponent: Component,
+              status,
+              children: element,
+            } satisfies ErrorBoundaryProps);
+          }
+        }
+      }
+    }
+
+    // Wrap with category catch-alls (4xx.tsx, 5xx.tsx)
+    for (const [key, file] of segment.statusFiles) {
+      if (key === '4xx' || key === '5xx') {
+        const mod = await loadModule(file);
+        const Component = mod.default;
+        if (Component) {
+          element = createElement(TimberErrorBoundary, {
+            fallbackComponent: Component,
+            status: key === '4xx' ? 400 : 500, // category marker
+            children: element,
+          } satisfies ErrorBoundaryProps);
+        }
+      }
+    }
+  }
+
+  // Wrap with error.tsx (outermost — catches anything not matched by status files)
+  if (segment.error) {
+    const errorModule = await loadModule(segment.error);
+    const ErrorComponent = errorModule.default;
+    if (ErrorComponent) {
+      element = createElement(TimberErrorBoundary, {
+        fallbackComponent: ErrorComponent,
+        children: element,
+      } satisfies ErrorBoundaryProps);
+    }
+  }
+
+  return element;
+}