@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/server/logger.ts

@@ -1,16 +1,18 @@
 /**
  * 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 { generateTraceId, getTraceStore } from './tracing.ts';
+import { createDefaultLogger } from './default-logger.ts';
+import { isDevMode } from './debug.ts';
+import { isControlFlowSignal } from './signal-identity.ts';
+import type { CsrfRejectReason } from './csrf.ts';
 
 // ─── Logger Interface ─────────────────────────────────────────────────────
 
@@ -24,21 +26,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;
 }
 
@@ -52,7 +57,7 @@ function withTraceContext(data?: Record<string, unknown>): Record<string, unknow
   const store = getTraceStore();
   const enriched: Record<string, unknown> = { ...data };
   if (store) {
-    enriched.trace_id = store.traceId;
+    enriched.trace_id = store.request.traceId;
     if (store.spanId) {
       enriched.span_id = store.spanId;
     }
@@ -62,6 +67,25 @@ function withTraceContext(data?: Record<string, unknown>): Record<string, unknow
 
 // ─── Framework Event Emitters ─────────────────────────────────────────────
 
+/**
+ * Log a CSRF rejection. Level: warn — the 403 body is deliberately terse,
+ * so this line is the only place the rejected origin is visible (TIM-1459).
+ * `detail` names the observed origin and, where one exists, the expected one.
+ *
+ * The gate runs inside the pipeline's trace scope, so the line carries the
+ * request's `trace_id`. A caller outside any scope still gets one minted
+ * here — the field is always present (design/17-logging.md §"trace_id is
+ * Always Set").
+ */
+export function logCsrfRejected(
+  detail: string,
+  data: { method: string; path: string; reason: CsrfRejectReason }
+): void {
+  const fields = withTraceContext(data);
+  fields.trace_id ??= generateTraceId();
+  _logger.warn(`CSRF origin check failed: ${detail}`, fields);
+}
+
 /** Log a completed request. Level: info. */
 export function logRequestCompleted(data: {
   method: string;
@@ -71,12 +95,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 +112,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 +121,118 @@ 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);
-  }
+  if (isControlFlowSignal(data.error)) return;
+  _logger.error('unhandled error in middleware phase', withTraceContext(data));
+}
+
+/** Log unhandled error in route setup (matching, param coercion). Level: error. */
+export function logRouteSetupError(data: { method: string; path: string; error: unknown }): void {
+  if (isControlFlowSignal(data.error)) return;
+  _logger.error('unhandled error in route setup', 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));
-  }
+export function logRenderError(data: {
+  method: string;
+  path: string;
+  error: unknown;
+  errorId?: string;
+}): void {
+  if (isControlFlowSignal(data.error)) return;
+  _logger.error('unhandled render-phase error', withTraceContext(data));
+}
+
+/**
+ * Log a status page, error page, `global-error.tsx` or fallback layout that
+ * failed to load and was skipped: the next fallback tier answers in its place.
+ * Level: error — a boundary that vanished is a bug in the app, even though the
+ * request still gets a page. The caller writes it once per file and failure.
+ */
+export function logSkippedModule(data: {
+  method: string;
+  path: string;
+  file: string;
+  error: unknown;
+}): void {
+  _logger.error('route file failed to load and was skipped', 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 {
+  if (isControlFlowSignal(data.error)) return;
+  _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 {
+  if (isControlFlowSignal(data.error)) return;
+  _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 a cache value that loses fidelity through JSON serialization. Level: warn. */
+export function logLossyCacheValue(data: { cacheKey: string; types: string }): void {
+  _logger.warn(
+    'cache value contains types that lose fidelity through JSON serialization in ' +
+      'Redis/KV cache handlers: Date becomes an ISO string, Map/Set become {}, BigInt throws. ' +
+      'The MemoryCacheHandler preserves them. Transform values to JSON-safe types before ' +
+      'caching, or use MemoryCacheHandler for values that require type preservation.',
+    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));
+}
+
+// ─── Swallow Helper ───────────────────────────────────────────────────────
+
+/**
+ * Log an intentionally swallowed error. Provides observability into catch
+ * blocks that are deliberately empty — the error is consumed, never rethrown.
+ *
+ * Default level: `warn` in dev (so the overlay surfaces patterns), `debug`
+ * in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`
+ * to override.
+ *
+ * **Infallible** — swallow() itself never throws, even if the logger is
+ * broken. A thrown swallow would turn a benign catch into a crash.
+ */
+export function swallow(err: unknown, reason: string, opts?: { level?: 'debug' | 'warn' }): void {
+  try {
+    const level = opts?.level ?? (isDevMode() ? 'warn' : 'debug');
+    _logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));
+  } catch {
+    // swallow() must never throw.
+  }
 }

package/src/server/metadata-collector.ts

@@ -0,0 +1,177 @@
+/**
+ * Render-time metadata resolution components.
+ *
+ * MetadataCollector runs below AccessGate for each segment, collecting
+ * metadata entries into a request-scoped array. MetadataHead runs at
+ * the page level, merging all collected entries and rendering Float-
+ * hoisted head elements.
+ *
+ * MetadataCollector is synchronous: it starts dynamic metadata() calls
+ * without awaiting and pushes the promise into the entries array, then
+ * returns children immediately. This lets React descend into the page
+ * subtree while metadata I/O runs concurrently (TIM-1367). A sibling
+ * MetadataSettle component awaits the promise so errors surface at the
+ * collector's tree position (caught by that segment's error boundary).
+ *
+ * MetadataHead is async: it awaits all entry promises before merging.
+ * Ordering is guaranteed by tree position — ancestor collectors push
+ * before MetadataHead renders.
+ *
+ * AccessGate denial prevents MetadataCollector from rendering, so
+ * metadata() never starts for denied segments (TIM-1027).
+ *
+ * See TIM-1363, TIM-1367, design/16-metadata.md.
+ */
+
+import { createElement, Fragment } from 'react';
+import type { ReactNode } from 'react';
+
+import { requestContextAls } from './als-registry.ts';
+import type { Metadata } from './types.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import { withSpan } from './tracing.ts';
+import { resolveMetadata, renderMetadataToElements, headElementsToReact } from './metadata.ts';
+import type { SegmentMetadataEntry } from './metadata.ts';
+import { collectMetadataRouteHeadElements } from './metadata-routes.ts';
+
+// ─── Request-scoped metadata entry store ────────────────────────────────
+
+/**
+ * Internal entry type that supports deferred (promise) metadata for
+ * concurrent resolution (TIM-1367). Dynamic metadata pushes a promise;
+ * static metadata pushes the resolved object directly.
+ */
+interface DeferredMetadataEntry {
+  metadata: Metadata | Promise<Metadata | null>;
+  isPage: boolean;
+}
+
+function getDeferredMetadataEntries(): DeferredMetadataEntry[] {
+  const store = requestContextAls.getStore();
+  if (!store) return [];
+  store._metadataEntries ??= [];
+  return store._metadataEntries as DeferredMetadataEntry[];
+}
+
+// ─── MetadataSettle ─────────────────────────────────────────────────────
+
+interface MetadataSettleProps {
+  promise: Promise<Metadata | null>;
+}
+
+/**
+ * Tiny async server component rendered as a sibling of the collector's
+ * children. Its sole job is error ownership: awaiting the metadata
+ * promise so that rejections surface at THIS tree position (caught by
+ * the owning segment's error boundary, not MetadataHead's).
+ */
+async function MetadataSettle(props: MetadataSettleProps): Promise<ReactNode> {
+  await props.promise;
+  return null;
+}
+
+// ─── MetadataCollector ──────────────────────────────────────────────────
+
+export interface MetadataCollectorProps {
+  metadataExport: Metadata | (() => Promise<Metadata>);
+  segmentName: string;
+  isPage: boolean;
+  children: ReactNode;
+}
+
+/**
+ * Synchronous server component that collects one segment's metadata
+ * during render. Placed between AccessGate and the layout/page. When
+ * AccessGate denies, this component never renders, so dynamic
+ * metadata() never starts for denied segments (TIM-1027).
+ *
+ * Static metadata objects are pushed synchronously (no side effects).
+ * Dynamic metadata functions are started (not awaited) and pushed as
+ * promises — React descends into children immediately while the I/O
+ * runs concurrently (TIM-1367). A sibling MetadataSettle component
+ * awaits the promise for error ownership.
+ */
+export function MetadataCollector(props: MetadataCollectorProps): ReactNode {
+  const { metadataExport, segmentName, isPage, children } = props;
+
+  if (typeof metadataExport === 'function') {
+    const promise = withSpan('timber.metadata', { 'timber.segment': segmentName }, () =>
+      (metadataExport as () => Promise<Metadata>)()
+    ).then((v) => v ?? null);
+    // Suppress unhandled rejection — MetadataSettle and MetadataHead
+    // both attach handlers, but a fast-rejecting promise can fire
+    // Node's unhandledRejection before they do.
+    promise.catch(() => {});
+
+    getDeferredMetadataEntries().push({ metadata: promise, isPage });
+
+    return createElement(Fragment, null, children, createElement(MetadataSettle, { promise }));
+  }
+
+  getDeferredMetadataEntries().push({ metadata: metadataExport, isPage });
+  return children;
+}
+
+// ─── MetadataHead ───────────────────────────────────────────────────────
+
+export interface MetadataHeadProps {
+  segments: ManifestSegmentNode[];
+  /** The matcher's raw (pre-coercion) params — fill the owning segment's URL for auto-links. */
+  rawSegmentParams: Record<string, string | string[]>;
+  requestUrl: string;
+  metadataRouteHashes?: Record<string, string>;
+}
+
+/**
+ * Async server component that awaits all deferred metadata promises,
+ * merges entries, auto-links metadata routes, and renders Float-
+ * hoisted head elements.
+ *
+ * Rendered as a SIBLING of the page element (not a wrapper) so React
+ * processes both concurrently — the page starts rendering immediately
+ * while MetadataHead awaits metadata promises. Both resolve before
+ * onShellReady (they're outside Suspense), but they overlap. Float
+ * hoists the head elements to <head> regardless of tree position.
+ *
+ * Ordering is guaranteed by tree position: every MetadataCollector
+ * is an ancestor of the Fragment containing MetadataHead, so its
+ * synchronous push into the entries array happens-before MetadataHead
+ * executes.
+ *
+ * See TIM-1367 for the concurrent resolution design.
+ */
+export async function MetadataHead(props: MetadataHeadProps): Promise<ReactNode> {
+  const { segments, rawSegmentParams, requestUrl, metadataRouteHashes } = props;
+  const deferredEntries = getDeferredMetadataEntries();
+
+  // Resolve all deferred metadata concurrently. Rejected entries are
+  // dropped — their errors are surfaced by MetadataSettle at the
+  // owning segment's error boundary, not here.
+  const settled = await Promise.allSettled(
+    deferredEntries.map((e) =>
+      e.metadata instanceof Promise ? e.metadata : Promise.resolve(e.metadata)
+    )
+  );
+  const entries: SegmentMetadataEntry[] = [];
+  for (let i = 0; i < settled.length; i++) {
+    const s = settled[i];
+    if (s.status === 'fulfilled' && s.value) {
+      entries.push({ metadata: s.value, isPage: deferredEntries[i].isPage });
+    }
+  }
+
+  const resolved = resolveMetadata(entries);
+  const headElements = renderMetadataToElements(resolved);
+
+  const autoLinked = collectMetadataRouteHeadElements(
+    segments,
+    Infinity,
+    resolved,
+    new URL(requestUrl),
+    rawSegmentParams,
+    metadataRouteHashes
+  );
+  headElements.push(...autoLinked);
+
+  return headElementsToReact(headElements);
+}

package/src/server/metadata-platform.ts

@@ -6,8 +6,8 @@
  * See design/16-metadata.md
  */
 
-import type { Metadata } from './types.js';
-import type { HeadElement } from './metadata.js';
+import type { Metadata } from './types.ts';
+import type { HeadElement } from './metadata.ts';
 
 /**
  * Render icon link elements (favicon, shortcut, apple-touch-icon, custom).

package/src/server/metadata-render.ts

@@ -6,9 +6,9 @@
  * See design/16-metadata.md
  */
 
-import type { Metadata } from './types.js';
-import type { HeadElement } from './metadata.js';
-import { renderOpenGraph, renderTwitter } from './metadata-social.js';
+import type { Metadata } from './types.ts';
+import type { HeadElement } from './metadata.ts';
+import { renderOpenGraph, renderTwitter } from './metadata-social.ts';
 import {
   renderIcons,
   renderAlternates,
@@ -16,7 +16,7 @@ import {
   renderAppleWebApp,
   renderAppLinks,
   renderItunes,
-} from './metadata-platform.js';
+} from './metadata-platform.ts';
 
 // ─── Render to Elements ──────────────────────────────────────────────────────
 
@@ -78,14 +78,36 @@ export function renderMetadataToElements(metadata: Metadata): HeadElement[] {
     }
   }
 
-  // Open Graph
+  // Open Graph — inherit title/description from top-level when not set explicitly
   if (metadata.openGraph) {
-    renderOpenGraph(metadata.openGraph, elements);
+    const og = { ...metadata.openGraph };
+    if (og.title === undefined && typeof metadata.title === 'string') {
+      og.title = metadata.title;
+    }
+    if (og.description === undefined && metadata.description) {
+      og.description = metadata.description;
+    }
+    renderOpenGraph(og, elements);
   }
 
-  // Twitter
+  // Twitter — inherit title/description from openGraph or top-level when not set
   if (metadata.twitter) {
-    renderTwitter(metadata.twitter, elements);
+    const tw = { ...metadata.twitter };
+    if (tw.title === undefined) {
+      tw.title =
+        metadata.openGraph?.title !== undefined
+          ? metadata.openGraph.title
+          : typeof metadata.title === 'string'
+            ? metadata.title
+            : undefined;
+    }
+    if (tw.description === undefined) {
+      tw.description =
+        metadata.openGraph?.description !== undefined
+          ? metadata.openGraph.description
+          : metadata.description;
+    }
+    renderTwitter(tw, elements);
   }
 
   // Icons