@arki/http 0.0.1

package/src/engine.ts

@@ -0,0 +1,239 @@
+/**
+ * The request engine — builds one fetch handler from a list of bundles.
+ *
+ * Hono does the routing internally; no Hono type appears in the public
+ * API, so the engine stays a swappable implementation detail. The route
+ * table order is bundle order then binding order — declaration order,
+ * deterministically, per DOT principle 3.
+ */
+
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import type { MountBinding, RouteBinding, RouteBundle } from './bundle.js';
+import type { ContractLike } from './contract.js';
+import { runWithRequestContext } from './context.js';
+import type { BaseRequestCtx } from './derive.js';
+import { describeInternalError, errorResponse, HTTP_ERROR_CODES, HttpConfigError, HttpError, toErrorResponse } from './error.js';
+import { sseResponse } from './sse.js';
+
+/** A built engine: the composed fetch handler plus its route inventory. */
+export type Engine = {
+  readonly fetch: (req: Request) => Promise<Response>;
+  /** Contract ids + mount ids, in registration order. */
+  readonly routeIds: readonly string[];
+};
+
+/**
+ * Compose bundles into a single fetch handler. Throws
+ * `ARKI_HTTP_E002`/`E006` on route collisions and malformed mounts —
+ * callers (the `http()` pip's `boot`) let these bubble as boot failures.
+ */
+export function buildEngine(bundles: readonly RouteBundle[]): Engine {
+  const app = new Hono();
+  const claimed = new Map<string, string>();
+  const routeIds: string[] = [];
+
+  for (const bundle of bundles) {
+    for (const mount of bundle.mounts) {
+      registerMount(app, claimed, mount);
+      routeIds.push(mount.id);
+    }
+    for (const binding of bundle.bindings) {
+      registerBinding(app, claimed, bundle, binding);
+      routeIds.push(binding.contract.id);
+    }
+  }
+
+  app.notFound(c =>
+    errorResponse(404, HTTP_ERROR_CODES.notFound, `no route for ${c.req.method} ${new URL(c.req.url).pathname}`),
+  );
+  app.onError((error, _c) => toErrorResponse(error));
+
+  return {
+    fetch: req => Promise.resolve(app.fetch(req)),
+    routeIds,
+  };
+}
+
+function registerMount(app: Hono, claimed: Map<string, string>, mount: MountBinding): void {
+  const key = `MOUNT ${mount.path}`;
+  const prior = claimed.get(key);
+  if (prior !== undefined) {
+    throw new HttpConfigError({
+      code: HTTP_ERROR_CODES.duplicateRoute,
+      message: `[http] duplicate mount at "${mount.path}": "${mount.id}" collides with "${prior}".`,
+      remediation: 'Give each mounted handler a distinct path prefix.',
+    });
+  }
+  claimed.set(key, mount.id);
+  app.mount(mount.path, mount.handler);
+}
+
+function registerBinding(app: Hono, claimed: Map<string, string>, bundle: RouteBundle, binding: RouteBinding): void {
+  const { contract } = binding;
+  const key = `${contract.method} ${contract.path}`;
+  const prior = claimed.get(key);
+  if (prior !== undefined) {
+    throw new HttpConfigError({
+      code: HTTP_ERROR_CODES.duplicateRoute,
+      message: `[http] duplicate route ${key}: "${contract.id}" collides with "${prior}".`,
+      remediation:
+        'Two bindings (possibly from different bundles) claim the same method and path. Change one path, or drop the duplicate binding.',
+    });
+  }
+  claimed.set(key, contract.id);
+  app.on(contract.method, contract.path, c => executeBinding(bundle, binding, c.req.raw, c.req.param()));
+}
+
+async function executeBinding(
+  bundle: RouteBundle,
+  binding: RouteBinding,
+  req: Request,
+  params: Record<string, string>,
+): Promise<Response> {
+  const base: BaseRequestCtx = {
+    req,
+    url: new URL(req.url),
+    requestId: req.headers.get('x-request-id') ?? crypto.randomUUID(),
+    signal: req.signal,
+  };
+  return runWithRequestContext(base, async () => {
+    try {
+      let ctx: BaseRequestCtx & Record<string, unknown> = base;
+      for (const deriver of bundle.derivers) {
+        // Erasure boundary: derivers were stored with `never` context (see
+        // ErasedDeriver); the accumulated ctx is the value they were typed
+        // against at composition time.
+        const value = await deriver.derive(req, ctx as never);
+        ctx = { ...ctx, [deriver.key]: value };
+      }
+
+      const input = await validateInput(binding.contract, params, base.url, req);
+
+      if (binding.contract.kind === 'sse') {
+        // Erasure boundary, same as above — input/ctx match the handler's
+        // composition-time types.
+        const events = (binding.handler as (input: never, ctx: never) => AsyncIterable<unknown>)(
+          input as never,
+          ctx as never,
+        );
+        return sseResponse(events, binding.contract, base.signal);
+      }
+
+      const result = await (binding.handler as (input: never, ctx: never) => unknown)(input as never, ctx as never);
+      if (result instanceof Response) return result;
+      return serializeOutput(binding.contract, result);
+    } catch (error) {
+      return toErrorResponse(error);
+    }
+  });
+}
+
+type ValidatedInput = {
+  readonly params: Record<string, string>;
+  readonly query: unknown;
+  readonly body: unknown;
+};
+
+async function validateInput(
+  contract: ContractLike,
+  params: Record<string, string>,
+  url: URL,
+  req: Request,
+): Promise<ValidatedInput> {
+  let query: unknown;
+  if (contract.query !== undefined) {
+    // Multi-valued query params collapse to their last value here; declare
+    // arrays via a transform on the contract schema if you need them.
+    query = parseWith(contract.query, Object.fromEntries(url.searchParams), 'query');
+  }
+
+  let body: unknown;
+  if (contract.body !== undefined) {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      throw new HttpError(400, HTTP_ERROR_CODES.badRequest, 'request body is not valid JSON', {
+        remediation: 'Send a JSON body with content-type: application/json.',
+      });
+    }
+    body = parseWith(contract.body, raw, 'body');
+  }
+
+  return { params, query, body };
+}
+
+function parseWith(schema: { parse(input: unknown): unknown }, value: unknown, where: 'query' | 'body'): unknown {
+  try {
+    return schema.parse(value);
+  } catch (error) {
+    throw new HttpError(400, HTTP_ERROR_CODES.badRequest, `${where} validation failed: ${zodMessage(error)}`, {
+      cause: error,
+    });
+  }
+}
+
+function zodMessage(error: unknown): string {
+  if (error instanceof z.ZodError) {
+    return error.issues.map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
+  }
+  return describeInternalError(error);
+}
+
+function serializeOutput(contract: ContractLike, result: unknown): Response {
+  if (contract.output === undefined) {
+    throw new HttpError(
+      500,
+      HTTP_ERROR_CODES.internal,
+      `handler for "${contract.id}" returned a value but the contract declares no output schema`,
+      { remediation: 'Return a Response, or declare an output schema on the contract.' },
+    );
+  }
+  let validated: unknown;
+  try {
+    validated = contract.output.parse(result);
+  } catch (error) {
+    throw new HttpError(
+      500,
+      HTTP_ERROR_CODES.internal,
+      `handler output for "${contract.id}" violates the contract's output schema: ${zodMessage(error)}`,
+      { cause: error },
+    );
+  }
+  return Response.json(validated);
+}
+
+/**
+ * App-wide middleware: a fetch-shaped wrapper. The first middleware in a
+ * list runs outermost. Use for cross-cutting concerns that must see or
+ * touch the raw request/response — CORS, request logging, compression.
+ * For per-request *values* (auth principals, tenant handles), use
+ * derivers — they are typed into handler contexts; middleware is not.
+ */
+export type HttpMiddleware = (req: Request, next: (req: Request) => Promise<Response>) => Response | Promise<Response>;
+
+/**
+ * Wrap a fetch handler in middleware (first = outermost). A middleware
+ * that throws resolves to the coded error envelope — `HttpError` keeps
+ * its status, anything else is a 500.
+ */
+export function composeMiddleware(
+  fetch: (req: Request) => Promise<Response>,
+  middleware: readonly HttpMiddleware[],
+): (req: Request) => Promise<Response> {
+  let composed = fetch;
+  for (const layer of middleware.toReversed()) {
+    const next = composed;
+    composed = async req => await layer(req, next);
+  }
+  const outermost = composed;
+  return async req => {
+    try {
+      return await outermost(req);
+    } catch (error) {
+      return toErrorResponse(error);
+    }
+  };
+}

package/src/error.ts

@@ -0,0 +1,158 @@
+/**
+ * Error surface for `@arki/http`.
+ *
+ * Two families, mirroring the DOT diagnostics doctrine:
+ *
+ *  - {@link HttpConfigError} — composition/lifecycle failures (duplicate
+ *    routes, listen failures, drain timeouts). Thrown from `boot`/`start`/
+ *    `stop`; the kernel wraps them and their `code`/`remediation`/`docsUrl`
+ *    propagate into `app.diagnostics.issues`.
+ *  - {@link HttpError} — per-request failures. Thrown from handlers,
+ *    derivers, or validation; serialized onto the wire as the coded
+ *    envelope `{ error: { code, message, remediation?, docsUrl? } }`.
+ *
+ * Every code is stable API. Match on codes, never parse messages.
+ */
+
+/**
+ * Stable error codes for `@arki/http`. `E0NN` codes surface through the
+ * DOT lifecycle (boot/start/stop failures); `E4xx`/`E5xx` codes surface
+ * on the wire in the error envelope.
+ */
+export const HTTP_ERROR_CODES = {
+  /** `start` could not bind the port. */
+  listenFailed: 'ARKI_HTTP_E001',
+  /** Two bindings claim the same method + path. */
+  duplicateRoute: 'ARKI_HTTP_E002',
+  /** `stop` exceeded `drainTimeoutMs` with requests still in flight. */
+  drainTimeout: 'ARKI_HTTP_E005',
+  /** A mount path is malformed. */
+  invalidMount: 'ARKI_HTTP_E006',
+  /** A deriver key duplicates an earlier deriver or a base context key. */
+  duplicateDeriverKey: 'ARKI_HTTP_E007',
+  /** Request validation failed (query/body) or the body is not valid JSON. */
+  badRequest: 'ARKI_HTTP_E400',
+  /** A deriver rejected the request's credentials. */
+  unauthorized: 'ARKI_HTTP_E401',
+  /** A deriver rejected the request's permissions. */
+  forbidden: 'ARKI_HTTP_E403',
+  /** No route matches the request. */
+  notFound: 'ARKI_HTTP_E404',
+  /** Handler crash or output-schema violation. */
+  internal: 'ARKI_HTTP_E500',
+} as const;
+
+const docsUrlFor = (code: string): string => `https://arki.dev/http/errors/${code.toLowerCase().replaceAll('_', '-')}`;
+
+/**
+ * A per-request failure with an HTTP status and a stable code. Throw from
+ * a handler or deriver to short-circuit into the wire envelope:
+ *
+ * ```ts
+ * throw new HttpError(401, HTTP_ERROR_CODES.unauthorized, 'missing or invalid credentials');
+ * ```
+ */
+export class HttpError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly remediation: string | undefined;
+  readonly docsUrl: string | undefined;
+  /** Extra response headers — e.g. `www-authenticate` on a 401, `retry-after` on a 429. */
+  readonly headers: Readonly<Record<string, string>> | undefined;
+
+  constructor(
+    status: number,
+    code: string,
+    message: string,
+    options: {
+      readonly remediation?: string;
+      readonly docsUrl?: string;
+      readonly headers?: Readonly<Record<string, string>>;
+      readonly cause?: unknown;
+    } = {},
+  ) {
+    super(message, options.cause === undefined ? {} : { cause: options.cause });
+    this.name = 'HttpError';
+    this.status = status;
+    this.code = code;
+    this.remediation = options.remediation;
+    this.docsUrl = options.docsUrl ?? docsUrlFor(code);
+    this.headers = options.headers;
+  }
+}
+
+/**
+ * A composition or lifecycle failure. Carries the same code/remediation/
+ * docsUrl fields the DOT kernel propagates into diagnostics when a hook
+ * throws.
+ */
+export class HttpConfigError extends Error {
+  readonly code: string;
+  readonly remediation: string;
+  readonly docsUrl: string;
+
+  constructor(fields: { readonly code: string; readonly message: string; readonly remediation: string; readonly docsUrl?: string }) {
+    super(fields.message);
+    this.name = 'HttpConfigError';
+    this.code = fields.code;
+    this.remediation = fields.remediation;
+    this.docsUrl = fields.docsUrl ?? docsUrlFor(fields.code);
+  }
+}
+
+/** The wire error envelope. Stable shape — agents parse this. */
+export type HttpErrorEnvelope = {
+  readonly error: {
+    readonly code: string;
+    readonly message: string;
+    readonly remediation?: string;
+    readonly docsUrl?: string;
+  };
+};
+
+/**
+ * Message for an unexpected (non-{@link HttpError}) failure: full detail
+ * in development, redacted in production — internals never leak onto the
+ * wire of a deployed app.
+ */
+export function describeInternalError(error: unknown): string {
+  if (process.env.NODE_ENV === 'production') return 'internal error';
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Map any thrown value to its wire envelope: {@link HttpError} keeps its
+ * status and fields; everything else is a redacted-in-production 500.
+ */
+export function toErrorResponse(error: unknown): Response {
+  if (error instanceof HttpError) {
+    return errorResponse(error.status, error.code, error.message, {
+      ...(error.remediation === undefined ? {} : { remediation: error.remediation }),
+      ...(error.docsUrl === undefined ? {} : { docsUrl: error.docsUrl }),
+      ...(error.headers === undefined ? {} : { headers: error.headers }),
+    });
+  }
+  return errorResponse(500, HTTP_ERROR_CODES.internal, describeInternalError(error));
+}
+
+/** Build the envelope `Response` for a coded failure. */
+export function errorResponse(
+  status: number,
+  code: string,
+  message: string,
+  options: {
+    readonly remediation?: string;
+    readonly docsUrl?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+  } = {},
+): Response {
+  const envelope: HttpErrorEnvelope = {
+    error: {
+      code,
+      message,
+      ...(options.remediation === undefined ? {} : { remediation: options.remediation }),
+      ...(options.docsUrl === undefined ? {} : { docsUrl: options.docsUrl }),
+    },
+  };
+  return Response.json(envelope, { status, ...(options.headers === undefined ? {} : { headers: options.headers }) });
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `@arki/http` — typed HTTP for ARKI.
+ *
+ * Route contracts as data ({@link route}), zod-validated handlers bound in
+ * a typed bundle builder ({@link routes}), request-scope derivers
+ * ({@link derive}), SSE streaming, and deterministic OpenAPI generation
+ * ({@link toOpenApi}).
+ *
+ * The framework-agnostic core lives here — {@link buildEngine} +
+ * {@link listen} run a server without any framework. The DOT adapter (the
+ * `http()` pip) lives at `@arki/http/dot`; the ambient request context —
+ * a deliberate last resort — at `@arki/http/context`.
+ */
+
+export { route } from './contract.js';
+export type {
+  ContractLike,
+  HttpMethod,
+  ParamsOf,
+  PathParams,
+  RouteContract,
+  SchemaLike,
+  SseContract,
+} from './contract.js';
+
+export { routes } from './bundle.js';
+export type {
+  HandlerResult,
+  MountBinding,
+  MountMeta,
+  MountTransport,
+  RouteBinding,
+  RouteBundle,
+  RouteBundleBuilder,
+  RouteHandler,
+  RouteInput,
+  SseHandler,
+} from './bundle.js';
+
+export { BASE_CTX_KEYS, derive } from './derive.js';
+export type { BaseRequestCtx, Deriver, ErasedDeriver } from './derive.js';
+
+export { describeInternalError, errorResponse, HTTP_ERROR_CODES, HttpConfigError, HttpError, toErrorResponse } from './error.js';
+export type { HttpErrorEnvelope } from './error.js';
+
+export { contractMeta, toOpenApi } from './openapi.js';
+export type { OpenApiInfo, RouteMeta } from './openapi.js';
+
+export { buildEngine, composeMiddleware } from './engine.js';
+export type { Engine, HttpMiddleware } from './engine.js';
+
+export { listen } from './listen.js';
+export type { ListenHandle, ListenOptions } from './listen.js';

package/src/listen.ts

@@ -0,0 +1,100 @@
+/**
+ * The socket layer — runtime-adaptive listening.
+ *
+ * `Bun.serve` when the Bun global is present, `@hono/node-server`
+ * otherwise. Neither runtime's types leak into the public surface; the
+ * handle exposes exactly what the `http()` pip's lifecycle needs.
+ */
+
+import { HTTP_ERROR_CODES, HttpConfigError } from './error.js';
+
+export type ListenOptions = {
+  readonly port: number;
+  readonly hostname?: string;
+};
+
+export type ListenHandle = {
+  readonly port: number;
+  readonly hostname: string;
+  /** Stop accepting new connections; in-flight requests continue. */
+  stopAccepting(): void;
+  /** Sever remaining connections and release the port. */
+  forceClose(): void;
+};
+
+type FetchLike = (req: Request) => Response | Promise<Response>;
+
+type BunServerLike = {
+  readonly port: number;
+  readonly hostname: string;
+  stop(closeActiveConnections?: boolean): void;
+};
+
+type BunGlobalLike = {
+  serve(options: { readonly port: number; readonly hostname?: string; readonly fetch: FetchLike }): BunServerLike;
+};
+
+/** Narrow structural view of the Bun global — `@types/node` has no Bun. */
+function bunGlobal(): BunGlobalLike | undefined {
+  return (globalThis as { Bun?: BunGlobalLike }).Bun;
+}
+
+function listenFailure(port: number, cause: unknown): HttpConfigError {
+  return new HttpConfigError({
+    code: HTTP_ERROR_CODES.listenFailed,
+    message: `[http] failed to listen on port ${port}: ${cause instanceof Error ? cause.message : String(cause)}`,
+    remediation: 'Is the port already in use? Change options.port on http(...) or stop the other process.',
+  });
+}
+
+export async function listen(fetch: FetchLike, options: ListenOptions): Promise<ListenHandle> {
+  const bun = bunGlobal();
+  if (bun !== undefined) return listenBun(bun, fetch, options);
+  return listenNode(fetch, options);
+}
+
+function listenBun(bun: BunGlobalLike, fetch: FetchLike, options: ListenOptions): ListenHandle {
+  let server: BunServerLike;
+  try {
+    server = bun.serve({
+      port: options.port,
+      fetch,
+      ...(options.hostname === undefined ? {} : { hostname: options.hostname }),
+    });
+  } catch (error) {
+    throw listenFailure(options.port, error);
+  }
+  return {
+    port: server.port,
+    hostname: server.hostname,
+    stopAccepting: () => {
+      server.stop(false);
+    },
+    forceClose: () => {
+      server.stop(true);
+    },
+  };
+}
+
+async function listenNode(fetch: FetchLike, options: ListenOptions): Promise<ListenHandle> {
+  const { serve } = await import('@hono/node-server');
+  return await new Promise<ListenHandle>((resolve, reject) => {
+    const server = serve({ fetch, port: options.port, hostname: options.hostname ?? '0.0.0.0' }, info => {
+      resolve({
+        port: info.port,
+        hostname: info.address,
+        stopAccepting: () => {
+          server.close();
+        },
+        forceClose: () => {
+          const closable = server as { close(): unknown; closeAllConnections?(): void };
+          closable.closeAllConnections?.();
+          closable.close();
+        },
+      });
+    });
+    server.on('error', (error: unknown) => {
+      reject(listenFailure(options.port, error));
+    });
+  });
+}