@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/index.ts

@@ -1,130 +1,44 @@
 // @timber-js/app/server — Server-side primitives
 // These are the primary imports for server components, middleware, and access files.
+//
+// Framework-internal pipeline plumbing is in #server-internal (Node package import).
+// Design doc: design/triage/api-naming-spike.md §8.5
 
-export type { AccessContext } from './types';
-export type { MiddlewareContext } from './types';
-export type { RouteContext } from './types';
-export type { Metadata, MetadataRoute } from './types';
+export type { AccessContext } from './types.ts';
+export type { MiddlewareContext } from './types.ts';
+export type { RouteContext } from './types.ts';
+export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from './types.ts';
 
-// Request Context — ALS-backed headers(), cookies(), and searchParams()
+// Request Context — ALS-backed accessors (all sync)
+// Prefer defineSearchParams().get() and getSegmentParams(SEGMENT_PATH) for typed access.
 // Design doc: design/04-authorization.md §"AccessContext does not include cookies or headers"
-// Design doc: design/23-search-params.md §"Server Integration"
-export {
-  headers,
-  cookies,
-  searchParams,
-  setParsedSearchParams,
-  runWithRequestContext,
-  setMutableCookieContext,
-  markResponseFlushed,
-  getSetCookieHeaders,
-  setCookieSecrets,
-} from './request-context';
-export type { ReadonlyHeaders, RequestCookies, CookieOptions } from './request-context';
+export { getHeaders, getSegmentParams } from './request-context.ts';
+export type { ReadonlyHeaders } from './request-context.ts';
+
+// Cookie Context — ALS-backed getCookieJar() escape hatch
+// Design doc: design/29-cookies.md
+export { getCookieJar } from './cookie-context.ts';
+export type { RequestCookies, CookieOptions, SetCookieOptions } from './cookie-context.ts';
 
 // Runtime primitives
 export {
   deny,
-  notFound,
   redirect,
-  permanentRedirect,
   redirectExternal,
   RedirectType,
-  RenderError,
   waitUntil,
-  DenySignal,
-  RedirectSignal,
-} from './primitives';
-export type { RenderErrorDigest, WaitUntilAdapter } from './primitives';
-export type { JsonSerializable } from './types';
-
-// Pipeline
-export { createPipeline } from './pipeline';
-export type {
-  PipelineConfig,
-  RouteMatch,
-  RouteMatcher,
-  RouteRenderer,
-  EarlyHintsEmitter,
-} from './pipeline';
-
-// Early Hints
-export { collectEarlyHintHeaders, formatLinkHeader } from './early-hints';
-export type { EarlyHint } from './early-hints';
-
-// Early Hints 103 Sender — ALS bridge for platform adapters
-export { runWithEarlyHintsSender, sendEarlyHints103 } from './early-hints-sender';
-export type { EarlyHintsSenderFn } from './early-hints-sender';
-
-// Canonicalization
-export { canonicalize } from './canonicalize';
-export type { CanonicalizeResult } from './canonicalize';
-
-// Proxy
-export { runProxy } from './proxy';
-export type { ProxyFn, ProxyExport } from './proxy';
-
-// Middleware
-export { runMiddleware } from './middleware-runner';
-export type { MiddlewareFn } from './middleware-runner';
-
-// Tree Builder
-export { buildElementTree } from './tree-builder';
-export type {
-  TreeBuilderConfig,
-  TreeBuildResult,
-  LoadedModule,
-  ModuleLoader,
-  AccessGateProps,
-  SlotAccessGateProps,
-  ErrorBoundaryProps,
-} from './tree-builder';
-
-// Access Gates
-export { AccessGate, SlotAccessGate } from './access-gate';
-
-// Status-Code Resolver
-export { resolveStatusFile, resolveSlotDenied } from './status-code-resolver';
-export type {
-  StatusFileResolution,
-  StatusFileKind,
-  StatusFileFormat,
-  SlotDeniedResolution,
-  SlotDeniedKind,
-} from './status-code-resolver';
-
-// Flush Controller
-export { flushResponse } from './flush';
-export type { FlushOptions, FlushResult, RenderFn, RenderResult } from './flush';
-
-// CSRF Protection
-export { validateCsrf } from './csrf';
-export type { CsrfConfig, CsrfResult } from './csrf';
-
-// Body Limits
-export { parseBodySize, enforceBodyLimits, DEFAULT_LIMITS } from './body-limits';
-export type { BodyLimitsConfig, BodyLimitResult, BodyKind } from './body-limits';
-
-// Metadata
-export {
-  resolveMetadata,
-  resolveTitle,
-  resolveMetadataUrls,
-  renderMetadataToElements,
-} from './metadata';
-export type { SegmentMetadataEntry, ResolveMetadataOptions, HeadElement } from './metadata';
-
-// Metadata Routes
-export {
-  classifyMetadataRoute,
-  getMetadataRouteServePath,
-  getMetadataRouteAutoLink,
-  METADATA_ROUTE_CONVENTIONS,
-} from './metadata-routes';
-export type { MetadataRouteInfo, MetadataRouteType } from './metadata-routes';
-
-// Server Actions
-export { createActionClient, ActionError, validated } from './action-client';
+  type DenyOptions,
+  type RedirectOptions,
+} from './primitives.ts';
+// RenderError removed from public exports per TIM-724.
+// Use deny({ status: 500, data: ... }) instead. RenderError stays in
+// #server-internal for pipeline catch logic.
+export type { RenderErrorDigest } from './primitives.ts';
+// JsonSerializable moved to @timber-js/app/codec as the single canonical path.
+// Re-export removed per TIM-721.
+
+// Server Actions — user-facing action client and validation
+export { createActionClient, ActionError, validated } from './action-client.ts';
 export type {
   ActionResult,
   ActionFn,
@@ -134,90 +48,24 @@ export type {
   ActionMiddleware,
   ActionSchema,
   ValidationErrors,
-} from './action-client';
+} from './action-client.ts';
 
 // FormData Preprocessing
-export { parseFormData, coerce } from './form-data';
+export { coerce, parseFormData } from './form-data.ts';
 
 // Form Flash (no-JS error round-trip)
-export { getFormFlash } from './form-flash';
-export type { FormFlashData } from './form-flash';
+export { getFormFlash } from './form-flash.ts';
+export type { FormFlashData } from './form-flash.ts';
 
-// Revalidation
-export {
-  revalidatePath,
-  revalidateTag,
-  executeAction,
-  buildNoJsResponse,
-  isRscActionRequest,
-} from './actions';
-export type {
-  RevalidateRenderer,
-  RevalidationState,
-  ActionHandlerConfig,
-  ActionHandlerResult,
-} from './actions';
+// Revalidation — user-facing revalidation APIs
+export { revalidatePath, revalidateTag } from './actions.ts';
 
-// Tracing — per-request trace ID via ALS
+// Tracing — per-request trace ID via ALS (user-facing accessors)
 // Design doc: design/17-logging.md §"trace_id is Always Set"
-export {
-  traceId,
-  spanId,
-  generateTraceId,
-  runWithTraceId,
-  replaceTraceId,
-  withSpan,
-  addSpanEvent,
-} from './tracing';
-export type { TraceStore } from './tracing';
-
-// Logger — structured logging
-// Design doc: design/17-logging.md §"Production Logging"
-export { setLogger, getLogger } from './logger';
-export {
-  logRequestCompleted,
-  logRequestReceived,
-  logSlowRequest,
-  logMiddlewareShortCircuit,
-  logMiddlewareError,
-  logRenderError,
-  logProxyError,
-  logWaitUntilUnsupported,
-  logWaitUntilRejected,
-  logSwrRefetchFailed,
-  logCacheMiss,
-} from './logger';
-export type { TimberLogger } from './logger';
+export { getTraceId, getSpanId, withSpan, addSpanEvent } from './tracing.ts';
 
-// Instrumentation — instrumentation.ts file convention
-// Design doc: design/17-logging.md §"instrumentation.ts"
-export { loadInstrumentation, callOnRequestError, hasOnRequestError } from './instrumentation';
-export type {
-  InstrumentationOnRequestError,
-  InstrumentationRequestInfo,
-  InstrumentationErrorContext,
-} from './instrumentation';
-
-// Dev Warnings — dev-mode misuse detection
-// Design doc: design/21-dev-server.md §"Dev-Mode Warnings", design/11-platform.md §"Dev Mode"
-export {
-  warnSuspenseWrappingChildren,
-  warnDenyInSuspense,
-  warnRedirectInSuspense,
-  warnRedirectInAccess,
-  warnStaticRequestApi,
-  warnCacheRequestProps,
-  warnSlowSlotWithoutSuspense,
-  setViteServer,
-  WarningId,
-  // Legacy aliases
-  warnDynamicApiInStaticBuild,
-  warnRedirectInSlotAccess,
-  warnDenyAfterFlush,
-} from './dev-warnings';
-export type { DevWarningConfig } from './dev-warnings';
+// Coerced param types — the post-coercion domain for segment params.
+// TIM-1347: these replaced the previous `Record<string, string | string[]>` lie.
+export type { CoercedParamValue, CoercedParams } from '../shared/param-value.ts';
 
-// Route Handler — route.ts API endpoints
-// Design doc: design/07-routing.md §"route.ts — API Endpoints"
-export { handleRouteRequest, resolveAllowedMethods } from './route-handler';
-export type { RouteModule, RouteHandler, HttpMethod } from './route-handler';
+// Segment params types — re-exported for convenience.

package/src/server/instrumentation.ts

@@ -9,7 +9,7 @@
  * See design/17-logging.md §"instrumentation.ts — The Entry Point"
  */
 
-import { setLogger, type TimberLogger } from './logger.js';
+import { setLogger, type TimberLogger } from './logger.ts';
 
 // ─── Instrumentation Types ────────────────────────────────────────────────
 

package/src/server/internal.ts

@@ -0,0 +1,173 @@
+// #server-internal — Framework-internal server exports
+//
+// This module is a Node package import (#server-internal in package.json
+// "imports" field). It is only resolvable from within @timber-js/app —
+// external consumers cannot import it.
+//
+// These exports are consumed by entry modules (rsc-entry, ssr-entry),
+// adapters, dev server plugins, and build plugins. They are NOT part of
+// the user-facing API and should not appear in documentation or autocomplete
+// for application developers.
+//
+// Design doc: design/triage/api-naming-spike.md §8.5
+
+// ── Request Context internals ────────────────────────────────────────────
+export {
+  getSearchParams,
+  getSegmentParams,
+  getHeader,
+  setSegmentParams,
+  runWithRequestContext,
+  setMutableCookieContext,
+  markResponseFlushed,
+} from './request-context.ts';
+export { getCookie, getSetCookieHeaders } from './cookie-context.ts';
+
+// ── Form-data coercion (internal) ────────────────────────────────────────
+export { coerce } from './form-data.ts';
+
+// ── Signal classes (instanceof targets for pipeline catch logic) ──────────
+export { DenySignal, RedirectSignal, RenderError } from './primitives.ts';
+export type { RenderErrorDigest } from './primitives.ts';
+
+// ── Pipeline ─────────────────────────────────────────────────────────────
+export { createPipeline } from './pipeline.ts';
+export type {
+  PipelineConfig,
+  RouteMatch,
+  RouteMatcher,
+  RouteRenderer,
+  EarlyHintsEmitter,
+} from './pipeline.ts';
+
+// ── Early Hints ──────────────────────────────────────────────────────────
+export { collectEarlyHintHeaders, formatLinkHeader } from './early-hints.ts';
+export type { EarlyHint } from './early-hints.ts';
+
+// ── Early Hints 103 Sender — ALS bridge for platform adapters ────────────
+export { runWithEarlyHintsSender, sendEarlyHints103 } from './early-hints-sender.ts';
+export type { EarlyHintsSenderFn } from './early-hints-sender.ts';
+
+// ── Canonicalization ─────────────────────────────────────────────────────
+export { canonicalize } from './canonicalize.ts';
+export type { CanonicalizeResult } from './canonicalize.ts';
+
+// ── Proxy ────────────────────────────────────────────────────────────────
+export { runProxy } from './proxy.ts';
+export type { ProxyFn, ProxyExport } from './proxy.ts';
+
+// ── Middleware ────────────────────────────────────────────────────────────
+export { runMiddleware } from './middleware-runner.ts';
+export type { MiddlewareFn } from './middleware-runner.ts';
+
+// ── Element Tree Types ──────────────────────────────────────────────────
+export type { LoadedComponent } from './utils/element-type.ts';
+export type { ErrorBoundaryProps } from './error-boundary-wrapper.ts';
+
+// ── Access Gates ─────────────────────────────────────────────────────────
+export { AccessGate, SlotAccessGate } from './access-gate.tsx';
+export type { AccessGateProps, SlotAccessGateProps, CreateElement } from './access-gate.tsx';
+
+// ── Status-Code Resolver ─────────────────────────────────────────────────
+export { resolveStatusFile, resolveSlotDenied } from './status-code-resolver.ts';
+export type {
+  StatusFileResolution,
+  StatusFileKind,
+  StatusFileFormat,
+  SlotDeniedResolution,
+  SlotDeniedKind,
+} from './status-code-resolver.ts';
+
+// ── CSRF Protection ──────────────────────────────────────────────────────
+export { validateCsrf } from './csrf.ts';
+export type { CsrfConfig, CsrfResult } from './csrf.ts';
+
+// ── Body Limits ──────────────────────────────────────────────────────────
+export { parseBodySize, enforceBodyLimits, DEFAULT_LIMITS } from './body-limits.ts';
+export type { BodyLimitsConfig, BodyLimitResult, BodyKind } from './body-limits.ts';
+
+// ── Metadata ─────────────────────────────────────────────────────────────
+export {
+  resolveMetadata,
+  resolveTitle,
+  resolveMetadataUrls,
+  renderMetadataToElements,
+} from './metadata.ts';
+export type { SegmentMetadataEntry, ResolveMetadataOptions } from './metadata.ts';
+
+// ── Metadata Routes ──────────────────────────────────────────────────────
+export {
+  classifyMetadataRoute,
+  getMetadataRouteServePath,
+  getMetadataRouteAutoLink,
+  METADATA_ROUTE_CONVENTIONS,
+} from './metadata-routes.ts';
+export type {
+  MetadataRouteInfo,
+  MetadataRouteType,
+  AutoLinkTag,
+  AutoLinkLink,
+  AutoLinkMeta,
+} from './metadata-routes.ts';
+
+// ── Server Actions (pipeline internals) ──────────────────────────────────
+export { executeAction } from './actions.ts';
+export type {
+  RevalidateRenderer,
+  RevalidationState,
+  ActionHandlerConfig,
+  ActionHandlerResult,
+} from './actions.ts';
+
+// ── Tracing internals ────────────────────────────────────────────────────
+export { runWithTraceId, replaceTraceId, generateTraceId } from './tracing.ts';
+export type { TraceStore } from './tracing.ts';
+
+// ── Logger ───────────────────────────────────────────────────────────────
+export { setLogger, getLogger } from './logger.ts';
+export {
+  logRequestCompleted,
+  logRequestReceived,
+  logSlowRequest,
+  logMiddlewareShortCircuit,
+  logMiddlewareError,
+  logRenderError,
+  logProxyError,
+  logWaitUntilUnsupported,
+  logWaitUntilRejected,
+  logSwrRefetchFailed,
+  logCacheMiss,
+} from './logger.ts';
+export type { TimberLogger } from './logger.ts';
+
+// ── Instrumentation ──────────────────────────────────────────────────────
+export { loadInstrumentation, callOnRequestError, hasOnRequestError } from './instrumentation.ts';
+export type {
+  InstrumentationOnRequestError,
+  InstrumentationRequestInfo,
+  InstrumentationErrorContext,
+} from './instrumentation.ts';
+
+// ── Route Handler ────────────────────────────────────────────────────────
+export { handleRouteRequest, resolveAllowedMethods } from './route-handler.ts';
+export type { RouteModule, RouteHandler, HttpMethod } from './route-handler.ts';
+
+// ── Render Timeout ───────────────────────────────────────────────────────
+export { RenderTimeoutError } from './render-timeout.ts';
+export type { RenderTimeout } from './render-timeout.ts';
+
+// ── Prebuilt Components (cache.component transform targets) ─────────────
+export {
+  __prebuilt,
+  __prebuiltDev,
+  getPrebuiltRegistration,
+  getPrebuiltRegistry,
+} from './prebuilt-runtime.ts';
+export type { PrebuiltComponentOptions, PrebuiltRegistration } from './prebuilt-runtime.ts';
+export { setPrebuiltPayloadSource, hasPrebuiltPayloadSource } from './prebuilt/payload-source.ts';
+export type {
+  PrebuiltManifest,
+  PrebuiltManifestEntry,
+  PrebuiltPayloadSource,
+} from './prebuilt/payload-source.ts';
+export { computeComponentCacheKey } from './prebuilt/cache-key.ts';

package/src/server/logger.ts

@@ -1,15 +1,17 @@
 /**
  * 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 { getTraceStore } from './tracing.ts';
+import { createDefaultLogger } from './default-logger.ts';
+import { isDevMode } from './debug.ts';
+import { isControlFlowSignal } from './primitives.ts';
 
 // ─── Logger Interface ─────────────────────────────────────────────────────
 
@@ -23,21 +25,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;
 }
 
@@ -70,12 +75,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. */
@@ -87,7 +92,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. */
@@ -96,54 +101,86 @@ 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 (process.env.NODE_ENV !== 'production') {
-    console.error('[timber] middleware error', data.error);
-  }
+  if (isControlFlowSignal(data.error)) return;
+  _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 (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));
-  }
+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 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);
-  }
+  _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 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.
+  }
 }