@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/src/server/index.ts

@@ -1,129 +1,45 @@
 // @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';
 
-// Request Context — ALS-backed headers(), cookies(), and searchParams()
+// Request Context — ALS-backed getHeaders(), getCookies(), and getSearchParams()
 // 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,
+  getHeaders,
+  getHeader,
+  getCookies,
+  getCookie,
+  getSearchParams,
+  getSegmentParams,
 } from './request-context';
 export type { ReadonlyHeaders, RequestCookies, CookieOptions } from './request-context';
 
 // Runtime primitives
 export {
   deny,
-  notFound,
   redirect,
-  permanentRedirect,
   redirectExternal,
   RedirectType,
-  RenderError,
   waitUntil,
-  DenySignal,
-  RedirectSignal,
+  type DenyOptions,
+  type RedirectOptions,
 } from './primitives';
+// 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, WaitUntilAdapter } from './primitives';
-export type { JsonSerializable } from './types';
+// JsonSerializable moved to @timber-js/app/codec as the single canonical path.
+// Re-export removed per TIM-721.
 
-// 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
+// Server Actions — user-facing action client and validation
 export { createActionClient, ActionError, validated } from './action-client';
 export type {
   ActionResult,
@@ -143,81 +59,13 @@ export { parseFormData, coerce } from './form-data';
 export { getFormFlash } from './form-flash';
 export type { FormFlashData } from './form-flash';
 
-// 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';
 
-// 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';
-
-// 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';
+export { getTraceId, getSpanId, withSpan, addSpanEvent } from './tracing';
 
-// 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.
+// defineSegmentParams itself lives at @timber-js/app/segment-params.
+export type { ParamsDefinition, InferParamField, ParamField } from '../segment-params/define.js';

package/src/server/internal.ts

@@ -0,0 +1,169 @@
+// #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 {
+  setSegmentParams,
+  runWithRequestContext,
+  setMutableCookieContext,
+  markResponseFlushed,
+  getSetCookieHeaders,
+} from './request-context.js';
+
+// ── Signal classes (instanceof targets for pipeline catch logic) ──────────
+export { DenySignal, RedirectSignal, RenderError } from './primitives.js';
+export type { RenderErrorDigest } from './primitives.js';
+
+// ── Pipeline ─────────────────────────────────────────────────────────────
+export { createPipeline } from './pipeline.js';
+export type {
+  PipelineConfig,
+  RouteMatch,
+  RouteMatcher,
+  RouteRenderer,
+  EarlyHintsEmitter,
+} from './pipeline.js';
+
+// ── Early Hints ──────────────────────────────────────────────────────────
+export { collectEarlyHintHeaders, formatLinkHeader } from './early-hints.js';
+export type { EarlyHint } from './early-hints.js';
+
+// ── Early Hints 103 Sender — ALS bridge for platform adapters ────────────
+export { runWithEarlyHintsSender, sendEarlyHints103 } from './early-hints-sender.js';
+export type { EarlyHintsSenderFn } from './early-hints-sender.js';
+
+// ── Canonicalization ─────────────────────────────────────────────────────
+export { canonicalize } from './canonicalize.js';
+export type { CanonicalizeResult } from './canonicalize.js';
+
+// ── Proxy ────────────────────────────────────────────────────────────────
+export { runProxy } from './proxy.js';
+export type { ProxyFn, ProxyExport } from './proxy.js';
+
+// ── Middleware ────────────────────────────────────────────────────────────
+export { runMiddleware } from './middleware-runner.js';
+export type { MiddlewareFn } from './middleware-runner.js';
+
+// ── Tree Builder ─────────────────────────────────────────────────────────
+export { buildElementTree } from './tree-builder.js';
+export type {
+  TreeBuilderConfig,
+  TreeBuildResult,
+  LoadedModule,
+  ModuleLoader,
+  AccessGateProps,
+  SlotAccessGateProps,
+  ErrorBoundaryProps,
+} from './tree-builder.js';
+
+// ── Access Gates ─────────────────────────────────────────────────────────
+export { AccessGate, SlotAccessGate } from './access-gate.js';
+
+// ── Status-Code Resolver ─────────────────────────────────────────────────
+export { resolveStatusFile, resolveSlotDenied } from './status-code-resolver.js';
+export type {
+  StatusFileResolution,
+  StatusFileKind,
+  StatusFileFormat,
+  SlotDeniedResolution,
+  SlotDeniedKind,
+} from './status-code-resolver.js';
+
+// ── Flush Controller ─────────────────────────────────────────────────────
+export { flushResponse } from './flush.js';
+export type { FlushOptions, FlushResult, RenderFn, RenderResult } from './flush.js';
+
+// ── CSRF Protection ──────────────────────────────────────────────────────
+export { validateCsrf } from './csrf.js';
+export type { CsrfConfig, CsrfResult } from './csrf.js';
+
+// ── Body Limits ──────────────────────────────────────────────────────────
+export { parseBodySize, enforceBodyLimits, DEFAULT_LIMITS } from './body-limits.js';
+export type { BodyLimitsConfig, BodyLimitResult, BodyKind } from './body-limits.js';
+
+// ── Metadata ─────────────────────────────────────────────────────────────
+export {
+  resolveMetadata,
+  resolveTitle,
+  resolveMetadataUrls,
+  renderMetadataToElements,
+} from './metadata.js';
+export type { SegmentMetadataEntry, ResolveMetadataOptions, HeadElement } from './metadata.js';
+
+// ── Metadata Routes ──────────────────────────────────────────────────────
+export {
+  classifyMetadataRoute,
+  getMetadataRouteServePath,
+  getMetadataRouteAutoLink,
+  METADATA_ROUTE_CONVENTIONS,
+} from './metadata-routes.js';
+export type { MetadataRouteInfo, MetadataRouteType } from './metadata-routes.js';
+
+// ── Server Actions (pipeline internals) ──────────────────────────────────
+export { executeAction, buildNoJsResponse, isRscActionRequest } from './actions.js';
+export type {
+  RevalidateRenderer,
+  RevalidationState,
+  ActionHandlerConfig,
+  ActionHandlerResult,
+} from './actions.js';
+
+// ── Tracing internals ────────────────────────────────────────────────────
+export { runWithTraceId, replaceTraceId, generateTraceId } from './tracing.js';
+export type { TraceStore } from './tracing.js';
+
+// ── Logger ───────────────────────────────────────────────────────────────
+export { setLogger, getLogger } from './logger.js';
+export {
+  logRequestCompleted,
+  logRequestReceived,
+  logSlowRequest,
+  logMiddlewareShortCircuit,
+  logMiddlewareError,
+  logRenderError,
+  logProxyError,
+  logWaitUntilUnsupported,
+  logWaitUntilRejected,
+  logSwrRefetchFailed,
+  logCacheMiss,
+} from './logger.js';
+export type { TimberLogger } from './logger.js';
+
+// ── Instrumentation ──────────────────────────────────────────────────────
+export { loadInstrumentation, callOnRequestError, hasOnRequestError } from './instrumentation.js';
+export type {
+  InstrumentationOnRequestError,
+  InstrumentationRequestInfo,
+  InstrumentationErrorContext,
+} from './instrumentation.js';
+
+// ── Dev Warnings ─────────────────────────────────────────────────────────
+export {
+  warnSuspenseWrappingChildren,
+  warnDenyInSuspense,
+  warnRedirectInSuspense,
+  warnRedirectInAccess,
+  warnStaticRequestApi,
+  warnSlowSlotWithoutSuspense,
+  setViteServer,
+  WarningId,
+} from './dev-warnings.js';
+export type { DevWarningConfig } from './dev-warnings.js';
+
+// ── Route Handler ────────────────────────────────────────────────────────
+export { handleRouteRequest, resolveAllowedMethods } from './route-handler.js';
+export type { RouteModule, RouteHandler, HttpMethod } from './route-handler.js';
+
+// ── Render Timeout ───────────────────────────────────────────────────────
+export { RenderTimeoutError } from './render-timeout.js';
+export type { RenderTimeout } from './render-timeout.js';

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,60 @@ 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));
-  }
+export function logRenderError(data: {
+  method: string;
+  path: string;
+  error: unknown;
+  errorId?: string;
+}): void {
+  _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));
 }

package/src/server/middleware-runner.ts

@@ -1,9 +1,9 @@
 /**
- * Middleware runner — executes a route's middleware.ts before rendering.
+ * Middleware runner — executes a route's middleware.ts chain before rendering.
  *
- * Only the leaf route's middleware runs. There is no middleware chain.
- * Middleware does NOT have next() — it either short-circuits with a Response
- * or returns void to continue to access checks + render.
+ * All middleware.ts files in the segment chain run, root to leaf (top-down).
+ * The first middleware that returns a Response short-circuits the chain.
+ * There is no next() — each middleware is independent.
  *
  * See design/07-routing.md §"middleware.ts"
  */
@@ -30,3 +30,30 @@ export async function runMiddleware(
   }
   return undefined;
 }
+
+/**
+ * Run all middleware functions in the segment chain, root to leaf.
+ *
+ * Execution is top-down: root middleware runs first, leaf middleware runs last.
+ * All middleware share the same MiddlewareContext — a parent that sets
+ * ctx.requestHeaders makes it visible to child middleware and downstream components.
+ *
+ * Short-circuits on the first middleware that returns a Response.
+ * Remaining middleware in the chain do not execute.
+ *
+ * @param chain - Middleware functions ordered root-to-leaf
+ * @param ctx - Shared middleware context
+ * @returns A Response if any middleware short-circuited, or undefined to continue
+ */
+export async function runMiddlewareChain(
+  chain: MiddlewareFn[],
+  ctx: MiddlewareContext
+): Promise<Response | undefined> {
+  for (const fn of chain) {
+    const result = await fn(ctx);
+    if (result instanceof Response) {
+      return result;
+    }
+  }
+  return undefined;
+}