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

package/src/server/index.ts

@@ -1,130 +1,40 @@
 // @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';
+// 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 +44,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 ────────────────────────────────────────────────
 
@@ -29,11 +29,18 @@ export interface InstrumentationRequestInfo {
 }
 
 export interface InstrumentationErrorContext {
-  /** Which pipeline phase the error occurred in. */
-  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route';
+  /**
+   * Which pipeline phase the error occurred in. `'setup'` is route setup
+   * between `proxy.ts` and `middleware.ts`: route matching and segment-param
+   * coercion (e.g. an `app/schema.ts` codec returning a value a param cannot
+   * hold). `'handler'` is `middleware.ts`; `'route'` is a `route.ts` handler
+   * or its `access.ts`, or a metadata route handler. design/17 §"Which errors
+   * reach it" lists every error that is reported, and those that are not.
+   */
+  phase: 'proxy' | 'setup' | 'handler' | 'render' | 'action' | 'route';
   /** The route pattern: '/dashboard/projects/[id]' */
   routePath: string;
-  /** Type of route that was matched. */
+  /** Type of route that was matched. A metadata route reports as `'route'`. */
   routeType: 'page' | 'route' | 'action';
   /** Always set — OTEL trace ID or UUID fallback. */
   traceId: string;

package/src/server/internal.ts

@@ -0,0 +1,168 @@
+// #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 } 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';
+
+// ── 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/json-status-response.ts

@@ -0,0 +1,105 @@
+/**
+ * JSON status responses — the status-code chain for API consumers.
+ *
+ * `{status}.json` → `{category}.json`, leaf → root, then the bare
+ * `{"error": true, "status": N}` body. No React, so the route.ts path and
+ * the pipeline's fallback renderer can use it without loading the RSC
+ * runtime.
+ *
+ * See design/10-error-handling.md §"JSON Error Pages".
+ */
+
+import { isDebug } from './debug.ts';
+import { loadFallbackModule } from './pipeline-helpers.ts';
+import { resolveStatusFile } from './status-code-resolver.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+
+/**
+ * Render the JSON status chain for `status` — `{status}.json` →
+ * `{category}.json`, leaf → root — ending in the bare
+ * `{"error": true, "status": N}` body when no file resolves.
+ *
+ * This is the one API-route error format (design/10-error-handling.md
+ * §"Format Selection for deny()"). A deny from `access.ts` or a handler, and
+ * an error the pipeline answers for a route.ts match, all end here.
+ *
+ * `droppedData` is a deny()'s data. It is only read to warn that a static
+ * JSON file cannot carry it.
+ */
+export async function renderJsonStatusResponse(
+  req: Request,
+  status: number,
+  segments: ManifestSegmentNode[],
+  responseHeaders: Headers,
+  maxIndex?: number,
+  droppedData?: unknown
+): Promise<Response> {
+  return (
+    (await renderJsonStatusFile(req, status, segments, responseHeaders, maxIndex, droppedData)) ??
+    bareJsonResponse(status, responseHeaders)
+  );
+}
+
+/**
+ * Render a JSON status-code file for `status`.
+ *
+ * JSON status files are returned verbatim with Content-Type: application/json.
+ * No React rendering pipeline, no layout wrapping.
+ *
+ * Returns null if no JSON status file is found (caller should use bare JSON fallback).
+ */
+export async function renderJsonStatusFile(
+  req: Request,
+  status: number,
+  segments: ManifestSegmentNode[],
+  responseHeaders: Headers,
+  maxIndex?: number,
+  droppedData?: unknown
+): Promise<Response | null> {
+  const resolution = resolveStatusFile(status, segments, 'json', maxIndex);
+
+  if (!resolution) {
+    return null;
+  }
+
+  // JSON status files are loaded as modules that export the JSON content.
+  // The manifest's load() imports the .json file, which Vite handles as a
+  // default export of the parsed JSON object.
+  // A .json status file that fails to load (reported) is not a usable
+  // match — return null so the caller continues to the framework default
+  // rather than rejecting out of the chain.
+  // Dev warning: deny(status, { dangerouslyPassData }) carries data but JSON
+  // status files are static bodies — the data is silently dropped. The same
+  // deny() would deliver the data to a .tsx file's data prop. See
+  // design/10-error-handling.md §"Status-Code File Variants".
+  if (isDebug() && droppedData !== undefined) {
+    console.warn(
+      `[timber] deny(${status}, data) resolved to ${resolution.file.filePath}, ` +
+        `which is a static JSON file. The data argument is dropped — JSON status files ` +
+        `are returned verbatim with no interpolation. If you need the data in the ` +
+        `response, use a .tsx status file or a route handler (route.ts).`
+    );
+  }
+
+  const mod = await loadFallbackModule(resolution.file, req, segments);
+  if (!mod) return null;
+  const jsonContent = mod.default ?? mod;
+
+  responseHeaders.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(jsonContent), {
+    status,
+    headers: responseHeaders,
+  });
+}
+
+/**
+ * Return a bare JSON error response when no JSON status file exists.
+ * This is the framework default for JSON format requests.
+ */
+function bareJsonResponse(status: number, responseHeaders: Headers): Response {
+  responseHeaders.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify({ error: true, status }), {
+    status,
+    headers: responseHeaders,
+  });
+}