@ontrails/http 1.0.0-beta.16 → 1.0.0-beta.18

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @ontrails/http
 
+## 1.0.0-beta.18
+
+### Minor Changes
+
+- c0b2948: Add `@ontrails/http/fetch`, a shared Web Fetch request/response kernel for HTTP
+  surface materializers.
+- fc3219c: Add `@ontrails/http/bun`, a Bun-native HTTP surface materializer backed by the
+  shared Web Fetch kernel.
+
+### Patch Changes
+
+- bc2d327: Close HTTP package documentation around the shared `@ontrails/http/fetch` kernel, Bun-native `@ontrails/http/bun` subpath, and Hono adapter boundary before versioning.
+  - @ontrails/core@1.0.0-beta.18
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- 61497c5: Add v1-minimum public API examples for shipped surface entrypoints.
+- Updated dependencies [3dc8254]
+  - @ontrails/core@1.0.0-beta.17
+
 ## 1.0.0-beta.16
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @ontrails/http
 
-Framework-agnostic HTTP route derivation for Trails. Pair this package with `@ontrails/hono` when you want the Hono surface adapter.
+Framework-agnostic HTTP route derivation and Web Fetch request handling for Trails. Pair this package with `@ontrails/hono` when you want Hono portability, or use `@ontrails/http/bun` when you want Bun-native serving without a third-party framework.
 
 ## Usage
 
@@ -22,6 +22,36 @@ await surface(graph, { port: 3000 });
 
 This starts a Hono-based HTTP server. The `greet` trail becomes `GET /greet?name=...` because its `intent` is `'read'`.
 
+For Bun-native HTTP without Hono, use the Bun runtime materializer subpath:
+
+```typescript
+import { surface } from '@ontrails/http/bun';
+
+await surface(graph, { port: 3000 });
+```
+
+`@ontrails/http/bun` uses Bun's native `Bun.serve({ routes })` fast path and
+keeps the shared Web Fetch handler as the fallback. It requires Bun `>=1.2.3`
+and does not add a third-party runtime dependency.
+
+## Projection and materialization
+
+The HTTP package follows the surface API naming split:
+
+- `derive*` exports are pure projections from the topo. Use
+  `deriveHttpRoutes()` for route definitions and `deriveOpenApiSpec()` for the
+  OpenAPI contract.
+- `create*` exports materialize runtime objects without opening a network
+  boundary. `@ontrails/http/fetch` exports `createRouteHandler()` for one
+  route and `createFetchHandler()` for a full topo dispatcher.
+- `surface()` opens the runtime boundary. `@ontrails/hono` opens a Hono server;
+  `@ontrails/http/bun` opens Bun's native HTTP server.
+
+The shared `@ontrails/http/fetch` kernel owns query/body parsing,
+content-length validation, public error projection, diagnostics, request IDs,
+headers, abort propagation, and webhook verification/parsing behavior. Hono and
+Bun both consume that kernel so route semantics stay aligned.
+
 For more control, build the routes yourself:
 
 ```typescript
@@ -53,6 +83,8 @@ contracts used by `deriveHttpRoutes()`.
 | --- | --- |
 | `deriveHttpRoutes(graph, options?)` | Build framework-agnostic route definitions from a topo |
 | `deriveOpenApiSpec(graph, options?)` | Generate an OpenAPI 3.1 document for the HTTP surface |
+| `@ontrails/http/fetch` | Shared Web Fetch `createRouteHandler()` and `createFetchHandler()` kernel |
+| `@ontrails/http/bun` | Bun-native `createApp()` and `surface()` materializer |
 
 ## Route derivation
 
@@ -114,6 +146,8 @@ values into arrays.
 
 ```bash
 bun add @ontrails/http @ontrails/hono
+# or, for Bun-native serving:
+bun add @ontrails/http
 ```
 
 ## Migration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.18",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -12,6 +12,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./bun": "./src/bun.ts",
+    "./fetch": "./src/fetch.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -22,7 +24,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.15"
+    "@ontrails/core": "^1.0.0-beta.17"
   },
   "peerDependencies": {
     "zod": "^4.3.5"

package/src/build.ts

@@ -1279,6 +1279,18 @@ const accumulateRoutes = (
  *
  * Returns `Result.err(ValidationError)` if two trails derive the same
  * (method, path) pair. Returns `Result.ok(routes)` on success.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpRoutes } from '@ontrails/http';
+ *
+ * const routes = deriveHttpRoutes(graph, { basePath: '/api' });
+ * if (routes.isErr()) throw routes.error;
+ *
+ * for (const route of routes.value) {
+ *   console.log(`${route.method} ${route.path}`);
+ * }
+ * ```
  */
 export const deriveHttpRoutes = (
   graph: Topo,

package/src/bun.ts

@@ -0,0 +1,270 @@
+import {
+  InternalError,
+  NotFoundError,
+  Result,
+  projectPublicSurfaceError,
+  trail,
+} from '@ontrails/core';
+import type {
+  BaseSurfaceOptions,
+  Layer,
+  ResourceOverrideMap,
+  Topo,
+  Trail,
+  TrailContextInit,
+} from '@ontrails/core';
+import { z } from 'zod';
+
+import { deriveHttpRoutes } from './build.js';
+import type {
+  HttpMethod,
+  HttpRouteDefinition,
+  ResolveHttpPermit,
+} from './build.js';
+import { createRouteHandler } from './fetch.js';
+import type { CreateRouteHandlerOptions } from './fetch.js';
+
+export interface CreateAppOptions extends BaseSurfaceOptions {
+  readonly basePath?: string | undefined;
+  readonly createContext?:
+    | (() => TrailContextInit | Promise<TrailContextInit>)
+    | undefined;
+  readonly hostname?: string | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  /** Maximum JSON request body size in bytes. Defaults to 1 MiB. */
+  readonly maxJsonBodyBytes?: number | undefined;
+  readonly port?: number | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  readonly resolvePermit?: ResolveHttpPermit | undefined;
+}
+
+export interface SurfaceHttpResult {
+  readonly close: () => Promise<void>;
+  readonly url: string;
+}
+
+type RouteHandler = (request: Request) => Promise<Response>;
+
+type BunRouteMethod = HttpMethod | 'HEAD';
+type BunRouteRecord = Record<
+  string,
+  Partial<Record<BunRouteMethod, RouteHandler>>
+>;
+
+export interface BunHttpApp {
+  readonly fetch: RouteHandler;
+  readonly onError: (error: Error) => Promise<Response>;
+  readonly routes: BunRouteRecord;
+}
+
+const json = (body: Record<string, unknown>, status: number): Response =>
+  Response.json(body, { status });
+
+const mapErrorResponse = (error: Error): Response => {
+  const projection = projectPublicSurfaceError('http', error);
+  return json(
+    {
+      error: {
+        category: projection.category,
+        code: projection.name,
+        message: projection.message,
+      },
+    },
+    projection.code
+  );
+};
+
+const notFoundResponse = (request: Request): Response => {
+  const path = new URL(request.url).pathname;
+  return mapErrorResponse(new NotFoundError(`HTTP route not found: ${path}`));
+};
+
+const methodNotAllowedResponse = (
+  request: Request,
+  route: Partial<Record<BunRouteMethod, RouteHandler>>
+): Response => {
+  const path = new URL(request.url).pathname;
+  return Response.json(
+    {
+      error: {
+        category: 'validation',
+        code: 'MethodNotAllowed',
+        message: `HTTP method not allowed: ${request.method.toUpperCase()} ${path}`,
+      },
+    },
+    {
+      headers: { Allow: Object.keys(route).toSorted().join(', ') },
+      status: 405,
+    }
+  );
+};
+
+const bodylessHeadResponse = (response: Response): Response =>
+  new Response(null, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+
+const caughtErrors = new Map<string, Error>();
+const caughtErrorInput = z.object({ errorId: z.string() });
+const caughtErrorTrail = trail('__ontrails.http.bun.error', {
+  blaze: () =>
+    Result.err(new InternalError('Bun error fallback executed directly')),
+  input: caughtErrorInput,
+  intent: 'read',
+  output: z.object({}),
+}) as Trail<unknown, unknown, unknown>;
+
+const caughtErrorRoute: HttpRouteDefinition = {
+  execute: async (input) => {
+    const parsed = caughtErrorInput.safeParse(input);
+    if (!parsed.success) {
+      return Result.err(
+        new InternalError('Bun error fallback missing error id')
+      );
+    }
+    const error =
+      caughtErrors.get(parsed.data.errorId) ??
+      new Error('Bun error fallback missing caught error');
+    return Result.err(error);
+  },
+  inputSource: 'query',
+  method: 'GET',
+  path: '/__ontrails/http/bun/error',
+  trail: caughtErrorTrail,
+  trailId: '__ontrails.http.bun.error',
+};
+const caughtErrorHandler = createRouteHandler(caughtErrorRoute);
+
+const materializeCaughtErrorRequest = (errorId: string): Request => {
+  const url = new URL('/__ontrails/http/bun/error', 'http://localhost');
+  url.searchParams.set('errorId', errorId);
+  return new Request(url);
+};
+
+const deriveOptions = (options: CreateAppOptions) => ({
+  basePath: options.basePath,
+  configValues: options.configValues,
+  createContext: options.createContext,
+  exclude: options.exclude,
+  include: options.include,
+  intent: options.intent,
+  layers: options.layers,
+  resolvePermit: options.resolvePermit,
+  resources: options.resources,
+  validate: options.validate,
+});
+
+const routeHandlerOptions = (
+  options: CreateAppOptions
+): CreateRouteHandlerOptions => ({
+  maxJsonBodyBytes: options.maxJsonBodyBytes,
+});
+
+const registerRoute = (
+  routes: BunRouteRecord,
+  route: HttpRouteDefinition,
+  options: CreateRouteHandlerOptions
+): void => {
+  const methods = routes[route.path] ?? {};
+  const handler = createRouteHandler(route, options);
+  methods[route.method] = handler;
+  if (route.method === 'GET') {
+    methods.HEAD = async (request) => {
+      const response = await handler(request);
+      return bodylessHeadResponse(response);
+    };
+  }
+  routes[route.path] = methods;
+};
+
+const routeForRequest = (
+  routes: BunRouteRecord,
+  request: Request
+): Partial<Record<BunRouteMethod, RouteHandler>> | undefined => {
+  const path = new URL(request.url).pathname;
+  return routes[path];
+};
+
+/**
+ * Build Bun-compatible HTTP route handlers from a topo.
+ *
+ * @remarks This materializes `deriveHttpRoutes` onto Bun's native `routes`
+ * table while preserving `fetch` as the fallback path for unmatched requests.
+ */
+export const createApp = (
+  graph: Topo,
+  options: CreateAppOptions = {}
+): BunHttpApp => {
+  const routesResult = deriveHttpRoutes(graph, deriveOptions(options));
+
+  if (routesResult.isErr()) {
+    throw routesResult.error;
+  }
+
+  const handlerOptions = routeHandlerOptions(options);
+  const routes: BunRouteRecord = {};
+  for (const route of routesResult.value) {
+    registerRoute(routes, route, handlerOptions);
+  }
+
+  return {
+    fetch: async (request) => {
+      const method = request.method.toUpperCase() as BunRouteMethod;
+      const route = routeForRequest(routes, request);
+      if (route === undefined) {
+        const response = notFoundResponse(request);
+        return method === 'HEAD' ? bodylessHeadResponse(response) : response;
+      }
+      const methodHandler = route[method];
+      const response =
+        methodHandler === undefined
+          ? methodNotAllowedResponse(request, route)
+          : await methodHandler(request);
+      return method === 'HEAD' ? bodylessHeadResponse(response) : response;
+    },
+    onError: async (error) => {
+      const errorId = crypto.randomUUID();
+      caughtErrors.set(errorId, error);
+      try {
+        return await caughtErrorHandler(materializeCaughtErrorRequest(errorId));
+      } finally {
+        caughtErrors.delete(errorId);
+      }
+    },
+    routes,
+  };
+};
+
+const startServer = (
+  app: BunHttpApp,
+  options: CreateAppOptions
+): SurfaceHttpResult => {
+  const server = Bun.serve({
+    error: app.onError,
+    fetch: app.fetch,
+    hostname: options.hostname ?? '0.0.0.0',
+    port: options.port ?? 3000,
+    routes: app.routes,
+  });
+
+  return {
+    close: async () => {
+      await server.stop(true);
+    },
+    url: String(server.url),
+  };
+};
+
+/**
+ * Build a Bun-native HTTP app from a topo and start serving it.
+ */
+export const surface = async (
+  graph: Topo,
+  options: CreateAppOptions = {}
+): Promise<SurfaceHttpResult> => {
+  // oxlint-disable-next-line require-await -- async ensures createApp() throws become rejected promises, not uncaught exceptions
+  const app = createApp(graph, options);
+  return startServer(app, options);
+};

package/src/fetch.ts

@@ -0,0 +1,577 @@
+import {
+  CancelledError,
+  isTrailsError,
+  NotFoundError,
+  projectErrorDiagnostics,
+  projectPublicSurfaceError,
+  ValidationError,
+} from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+
+import { deriveHttpRoutes } from './build.js';
+import type { DeriveHttpRoutesOptions, HttpRouteDefinition } from './build.js';
+
+export interface CreateRouteHandlerOptions {
+  /** Maximum JSON request body size in bytes. Defaults to 1 MiB. */
+  readonly maxJsonBodyBytes?: number | undefined;
+}
+
+export interface CreateFetchHandlerOptions
+  extends DeriveHttpRoutesOptions, CreateRouteHandlerOptions {}
+
+interface RuntimeOptions {
+  readonly maxJsonBodyBytes: number;
+}
+
+interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+
+type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | JsonObject;
+type JsonBodyReadResult =
+  | JsonValue
+  | typeof JSON_BODY_INVALID_CONTENT_LENGTH
+  | typeof JSON_BODY_TOO_LARGE
+  | typeof JSON_PARSE_ERROR;
+type JsonBodyTextReadResult = string | typeof JSON_BODY_TOO_LARGE;
+type InputReadResult = Record<string, unknown> | JsonBodyReadResult;
+type ParsedContentLength =
+  | number
+  | typeof JSON_BODY_INVALID_CONTENT_LENGTH
+  | undefined;
+
+const DEFAULT_MAX_JSON_BODY_BYTES = 1024 * 1024;
+const CONTENT_LENGTH_DECIMAL_PATTERN = /^\d+$/;
+
+const JSON_PARSE_ERROR = Symbol('JSON_PARSE_ERROR');
+const JSON_BODY_TOO_LARGE = Symbol('JSON_BODY_TOO_LARGE');
+const JSON_BODY_INVALID_CONTENT_LENGTH = Symbol(
+  'JSON_BODY_INVALID_CONTENT_LENGTH'
+);
+
+const LOG_UNSAFE_LABEL_CHARACTERS = /[^\w:.-]/g;
+const MAX_DIAGNOSTIC_LABEL_VALUE_LENGTH = 128;
+
+const routeKey = (method: string, path: string): `${string} ${string}` =>
+  `${method.toUpperCase()} ${path}`;
+
+const parseQueryParams = (request: Request): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+  const url = new URL(request.url);
+  const seenKeys = new Set<string>();
+
+  for (const key of url.searchParams.keys()) {
+    if (seenKeys.has(key)) {
+      continue;
+    }
+    seenKeys.add(key);
+    const all = url.searchParams.getAll(key);
+    result[key] = all.length > 1 ? all : all[0];
+  }
+
+  return result;
+};
+
+const parseContentLength = (
+  contentLength: string | null | undefined
+): ParsedContentLength => {
+  if (contentLength === null || contentLength === undefined) {
+    return undefined;
+  }
+  if (!CONTENT_LENGTH_DECIMAL_PATTERN.test(contentLength)) {
+    return JSON_BODY_INVALID_CONTENT_LENGTH;
+  }
+  const size = Number(contentLength);
+  return Number.isSafeInteger(size) ? size : Number.MAX_SAFE_INTEGER;
+};
+
+const isEmptyBody = (request: Request): boolean => {
+  const contentLength = parseContentLength(
+    request.headers.get('Content-Length')
+  );
+  if (contentLength === JSON_BODY_INVALID_CONTENT_LENGTH) {
+    return false;
+  }
+  if (contentLength !== undefined) {
+    return contentLength === 0;
+  }
+  return request.headers.get('Content-Type') === null;
+};
+
+const resolveMaxJsonBodyBytes = (value: number | undefined): number => {
+  const maxJsonBodyBytes = value ?? DEFAULT_MAX_JSON_BODY_BYTES;
+
+  if (!Number.isFinite(maxJsonBodyBytes) || maxJsonBodyBytes < 1) {
+    throw new ValidationError(
+      'maxJsonBodyBytes must be a positive finite number'
+    );
+  }
+
+  return maxJsonBodyBytes;
+};
+
+const hasOversizedContentLength = (
+  request: Request,
+  maxJsonBodyBytes: number
+): boolean => {
+  const contentLength = request.headers.get('Content-Length');
+  if (contentLength === null) {
+    return false;
+  }
+  const size = parseContentLength(contentLength);
+  if (size === JSON_BODY_INVALID_CONTENT_LENGTH) {
+    return false;
+  }
+  return size !== undefined && size > maxJsonBodyBytes;
+};
+
+const measureBodyTextBytes = (text: string): number => new Blob([text]).size;
+
+const validateBodyText = (
+  text: string,
+  maxJsonBodyBytes: number
+): JsonBodyTextReadResult =>
+  measureBodyTextBytes(text) > maxJsonBodyBytes ? JSON_BODY_TOO_LARGE : text;
+
+const cancelBodyReader = async (
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  reason?: unknown
+): Promise<void> => {
+  try {
+    await reader.cancel(reason);
+  } catch {
+    // The request is already being cancelled; preserve the surface-level
+    // cancelled response instead of replacing it with a reader cleanup error.
+  }
+};
+
+const assertRequestNotAborted = async (
+  request: Request,
+  reader: ReadableStreamDefaultReader<Uint8Array>
+): Promise<void> => {
+  if (!request.signal.aborted) {
+    return;
+  }
+  await cancelBodyReader(reader, request.signal.reason);
+  throw new CancelledError('Request aborted');
+};
+
+const readBodyText = async (
+  request: Request,
+  maxJsonBodyBytes: number
+): Promise<JsonBodyTextReadResult> => {
+  const { body } = request;
+  if (body === null) {
+    return '';
+  }
+
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+
+  try {
+    while (true) {
+      await assertRequestNotAborted(request, reader);
+      let read: Awaited<ReturnType<typeof reader.read>>;
+      try {
+        read = await reader.read();
+      } catch (error) {
+        await assertRequestNotAborted(request, reader);
+        throw error;
+      }
+      await assertRequestNotAborted(request, reader);
+      const { done, value } = read;
+      if (done) {
+        break;
+      }
+      if (value === undefined) {
+        continue;
+      }
+      totalBytes += value.byteLength;
+      if (totalBytes > maxJsonBodyBytes) {
+        await cancelBodyReader(reader);
+        return JSON_BODY_TOO_LARGE;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return new TextDecoder().decode(bytes);
+};
+
+const readJsonBody = async (
+  request: Request,
+  maxJsonBodyBytes: number
+): Promise<JsonBodyReadResult> => {
+  if (
+    parseContentLength(request.headers.get('Content-Length')) ===
+    JSON_BODY_INVALID_CONTENT_LENGTH
+  ) {
+    return JSON_BODY_INVALID_CONTENT_LENGTH;
+  }
+
+  if (hasOversizedContentLength(request, maxJsonBodyBytes)) {
+    return JSON_BODY_TOO_LARGE;
+  }
+
+  const text = await readBodyText(request, maxJsonBodyBytes);
+  if (text === JSON_BODY_TOO_LARGE) {
+    return JSON_BODY_TOO_LARGE;
+  }
+
+  const validated = validateBodyText(text, maxJsonBodyBytes);
+  if (validated === JSON_BODY_TOO_LARGE) {
+    return JSON_BODY_TOO_LARGE;
+  }
+
+  try {
+    return JSON.parse(validated) as JsonValue;
+  } catch {
+    return JSON_PARSE_ERROR;
+  }
+};
+
+const parseJsonBodyText = (text: string): JsonBodyReadResult => {
+  try {
+    return JSON.parse(text) as JsonValue;
+  } catch {
+    return JSON_PARSE_ERROR;
+  }
+};
+
+const parseWebhookBodyText = (
+  request: Request,
+  text: string
+): JsonBodyReadResult =>
+  isEmptyBody(request) || text.length === 0 ? {} : parseJsonBodyText(text);
+
+const readWebhookBodyText = async (
+  request: Request,
+  maxJsonBodyBytes: number
+): Promise<
+  string | typeof JSON_BODY_INVALID_CONTENT_LENGTH | typeof JSON_BODY_TOO_LARGE
+> => {
+  if (
+    parseContentLength(request.headers.get('Content-Length')) ===
+    JSON_BODY_INVALID_CONTENT_LENGTH
+  ) {
+    return JSON_BODY_INVALID_CONTENT_LENGTH;
+  }
+  if (hasOversizedContentLength(request, maxJsonBodyBytes)) {
+    return JSON_BODY_TOO_LARGE;
+  }
+  return await readBodyText(request, maxJsonBodyBytes);
+};
+
+const readInput = async (
+  request: Request,
+  inputSource: 'body' | 'query',
+  options: RuntimeOptions
+): Promise<InputReadResult> => {
+  if (inputSource === 'query') {
+    return parseQueryParams(request);
+  }
+  if (isEmptyBody(request)) {
+    return {};
+  }
+  return await readJsonBody(request, options.maxJsonBodyBytes);
+};
+
+const json = (body: Record<string, unknown>, status: number): Response =>
+  Response.json(body, { status });
+
+const mapErrorResponse = (error: Error): Response => {
+  const projection = projectPublicSurfaceError('http', error);
+  return json(
+    {
+      error: {
+        category: projection.category,
+        code: projection.name,
+        message: projection.message,
+      },
+    },
+    projection.code
+  );
+};
+
+const sanitizeDiagnosticLabelValue = (value: string): string =>
+  value
+    .replace(LOG_UNSAFE_LABEL_CHARACTERS, '_')
+    .slice(0, MAX_DIAGNOSTIC_LABEL_VALUE_LENGTH);
+
+const reportInternalDiagnostics = (error: Error, request: Request): void => {
+  if (isTrailsError(error)) {
+    return;
+  }
+
+  const requestId = request.headers.get('X-Request-ID') ?? undefined;
+  const safeRequestId =
+    requestId === undefined
+      ? undefined
+      : sanitizeDiagnosticLabelValue(requestId);
+  const label =
+    safeRequestId === undefined
+      ? '[ontrails:http/fetch] Internal error'
+      : `[ontrails:http/fetch] Internal error (${safeRequestId})`;
+  console.error(label, projectErrorDiagnostics(error));
+};
+
+interface ResultLike {
+  readonly error?: Error | undefined;
+  isOk(): boolean;
+  readonly value?: unknown;
+}
+
+const mapResultToResponse = (
+  result: ResultLike,
+  request: Request
+): Response => {
+  if (result.isOk()) {
+    return json({ data: result.value }, 200);
+  }
+  const error = result.error ?? new Error('Unknown error');
+  reportInternalDiagnostics(error, request);
+  return mapErrorResponse(error);
+};
+
+const handleCaughtError = (error: unknown, request: Request): Response => {
+  const err = error instanceof Error ? error : new Error(String(error));
+  reportInternalDiagnostics(err, request);
+  return mapErrorResponse(err);
+};
+
+const invalidJsonResponse = (): Response =>
+  json(
+    {
+      error: {
+        category: 'validation',
+        code: 'ValidationError',
+        message: 'Invalid JSON in request body',
+      },
+    },
+    400
+  );
+
+const invalidContentLengthResponse = (): Response =>
+  json(
+    {
+      error: {
+        category: 'validation',
+        code: 'ValidationError',
+        message: 'Invalid Content-Length header',
+      },
+    },
+    400
+  );
+
+const oversizedJsonBodyResponse = (options: RuntimeOptions): Response =>
+  json(
+    {
+      error: {
+        category: 'validation',
+        code: 'ValidationError',
+        message: `JSON request body exceeds ${options.maxJsonBodyBytes} bytes`,
+      },
+    },
+    413
+  );
+
+const notFoundResponse = (request: Request): Response => {
+  const path = new URL(request.url).pathname;
+  return mapErrorResponse(new NotFoundError(`HTTP route not found: ${path}`));
+};
+
+const collectHeaders = (request: Request): Record<string, string> => {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of request.headers) {
+    headers[key] = value;
+  }
+  return headers;
+};
+
+const createWebhookVerifyRequest = (
+  request: Request,
+  body: string
+): {
+  readonly body: string;
+  readonly headers: Record<string, string>;
+  readonly method: string;
+  readonly path: string;
+} => ({
+  body,
+  headers: collectHeaders(request),
+  method: request.method,
+  path: new URL(request.url).pathname,
+});
+
+const recordInvalidWebhook = async (
+  route: HttpRouteDefinition,
+  errorCategory = 'validation'
+): Promise<void> => {
+  await route.recordWebhookInvalid?.(errorCategory);
+};
+
+const errorCategoryForWebhookFailure = (error: Error | undefined): string =>
+  error !== undefined && isTrailsError(error) ? error.category : 'internal';
+
+const handleWebhookRoute = async (
+  route: HttpRouteDefinition,
+  options: RuntimeOptions,
+  request: Request
+): Promise<Response> => {
+  const rawBody = await readWebhookBodyText(request, options.maxJsonBodyBytes);
+
+  if (rawBody === JSON_BODY_INVALID_CONTENT_LENGTH) {
+    await recordInvalidWebhook(route);
+    return invalidContentLengthResponse();
+  }
+
+  if (rawBody === JSON_BODY_TOO_LARGE) {
+    await recordInvalidWebhook(route);
+    return oversizedJsonBodyResponse(options);
+  }
+
+  const verified = await route.verifyWebhook?.(
+    createWebhookVerifyRequest(request, rawBody)
+  );
+  if (verified?.isErr()) {
+    await recordInvalidWebhook(
+      route,
+      errorCategoryForWebhookFailure(verified.error)
+    );
+    return mapResultToResponse(verified, request);
+  }
+
+  const jsonBody = parseWebhookBodyText(request, rawBody);
+  if (jsonBody === JSON_PARSE_ERROR) {
+    await recordInvalidWebhook(route);
+    return invalidJsonResponse();
+  }
+
+  const parsed = route.parseWebhookInput?.(jsonBody);
+  if (parsed === undefined) {
+    await recordInvalidWebhook(route, 'internal');
+    return mapResultToResponse(
+      {
+        error: new Error('Webhook route is missing parse handler'),
+        isOk: () => false,
+      },
+      request
+    );
+  }
+  if (parsed.isErr()) {
+    await recordInvalidWebhook(route);
+    return mapResultToResponse(parsed, request);
+  }
+
+  const requestId = request.headers.get('X-Request-ID') ?? undefined;
+  const result = await route.execute(parsed.value, requestId, request.signal, {
+    headers: request.headers,
+  });
+  return mapResultToResponse(result, request);
+};
+
+/**
+ * Build a Web Fetch handler for one framework-agnostic HTTP route.
+ */
+export const createRouteHandler = (
+  route: HttpRouteDefinition,
+  options: CreateRouteHandlerOptions = {}
+): ((request: Request) => Promise<Response>) => {
+  const runtimeOptions = {
+    maxJsonBodyBytes: resolveMaxJsonBodyBytes(options.maxJsonBodyBytes),
+  };
+
+  return async (request) => {
+    try {
+      if (route.inputSource === 'webhook') {
+        return await handleWebhookRoute(route, runtimeOptions, request);
+      }
+
+      const rawInput = await readInput(
+        request,
+        route.inputSource,
+        runtimeOptions
+      );
+
+      if (rawInput === JSON_PARSE_ERROR) {
+        return invalidJsonResponse();
+      }
+
+      if (rawInput === JSON_BODY_INVALID_CONTENT_LENGTH) {
+        return invalidContentLengthResponse();
+      }
+
+      if (rawInput === JSON_BODY_TOO_LARGE) {
+        return oversizedJsonBodyResponse(runtimeOptions);
+      }
+
+      const requestId = request.headers.get('X-Request-ID') ?? undefined;
+      const result = await route.execute(rawInput, requestId, request.signal, {
+        headers: request.headers,
+      });
+      return mapResultToResponse(result, request);
+    } catch (error: unknown) {
+      return handleCaughtError(error, request);
+    }
+  };
+};
+
+/**
+ * Build a Web Fetch dispatcher for all HTTP routes in a topo.
+ */
+export const createFetchHandler = (
+  graph: Topo,
+  options: CreateFetchHandlerOptions = {}
+): ((request: Request) => Promise<Response>) => {
+  const routesResult = deriveHttpRoutes(graph, {
+    basePath: options.basePath,
+    configValues: options.configValues,
+    createContext: options.createContext,
+    exclude: options.exclude,
+    include: options.include,
+    intent: options.intent,
+    layers: options.layers,
+    resolvePermit: options.resolvePermit,
+    resources: options.resources,
+    validate: options.validate,
+  });
+
+  if (routesResult.isErr()) {
+    throw routesResult.error;
+  }
+
+  const routeHandlers = new Map<
+    string,
+    (request: Request) => Promise<Response>
+  >();
+  for (const route of routesResult.value) {
+    routeHandlers.set(
+      routeKey(route.method, route.path),
+      createRouteHandler(route, {
+        maxJsonBodyBytes: options.maxJsonBodyBytes,
+      })
+    );
+  }
+
+  return async (request) => {
+    const path = new URL(request.url).pathname;
+    const handler = routeHandlers.get(routeKey(request.method, path));
+    return handler === undefined ? notFoundResponse(request) : handler(request);
+  };
+};

package/src/index.ts

@@ -16,6 +16,12 @@ export {
   httpMethodByIntent,
 } from './method.js';
 export type { HttpMethod, HttpOperationMethod, InputSource } from './method.js';
+export {
+  createFetchHandler,
+  createRouteHandler,
+  type CreateFetchHandlerOptions,
+  type CreateRouteHandlerOptions,
+} from './fetch.js';
 
 // OpenAPI
 export { deriveOpenApiSpec } from './openapi.js';

package/src/method.ts

@@ -12,13 +12,46 @@ export const httpMethodByIntent = {
   write: 'POST',
 } as const satisfies Record<Intent, HttpMethod>;
 
+/**
+ * Derive the HTTP method used for a trail intent.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpMethod } from '@ontrails/http';
+ *
+ * const method = deriveHttpMethod('read');
+ * // method === 'GET'
+ * ```
+ */
 export const deriveHttpMethod = (intent: Intent): HttpMethod =>
   (httpMethodByIntent as Partial<Record<string, HttpMethod>>)[intent] ?? 'POST';
 
+/**
+ * Derive the lowercase OpenAPI operation method for a trail intent.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpOperationMethod } from '@ontrails/http';
+ *
+ * const operationMethod = deriveHttpOperationMethod('destroy');
+ * // operationMethod === 'delete'
+ * ```
+ */
 export const deriveHttpOperationMethod = (
   intent: Intent
 ): HttpOperationMethod =>
   deriveHttpMethod(intent).toLowerCase() as HttpOperationMethod;
 
+/**
+ * Derive where request input should be read from for an HTTP method.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpInputSource } from '@ontrails/http';
+ *
+ * const source = deriveHttpInputSource('GET');
+ * // source === 'query'
+ * ```
+ */
 export const deriveHttpInputSource = (method: HttpMethod): InputSource =>
   method === 'GET' ? 'query' : 'body';

package/src/openapi.ts

@@ -331,6 +331,16 @@ const buildInfo = (
  * Iterates all trails, skipping signals and internal trails, and produces
  * paths, operations, parameters, and response schemas derived from
  * the trail contract.
+ *
+ * @example
+ * ```ts
+ * import { deriveOpenApiSpec } from '@ontrails/http';
+ *
+ * const spec = deriveOpenApiSpec(graph, {
+ *   basePath: '/api',
+ *   title: 'Demo API',
+ * });
+ * ```
  */
 export const deriveOpenApiSpec = (
   graph: Topo,