@arki/http 0.0.1

package/src/contract.ts

@@ -0,0 +1,152 @@
+/**
+ * Route contracts — the static half of an HTTP surface.
+ *
+ * A contract is pure data at module scope: method + path + zod schemas +
+ * a stable id. No handler, no services, no I/O. That split is what makes
+ * three things possible at once:
+ *
+ *  - `configure` can register it in the DOT manifest (configure is sync);
+ *  - OpenAPI generation is static — no boot required;
+ *  - the handler signature is fully inferred when the contract is bound
+ *    (see `routes().bind()` in `bundle.ts`).
+ */
+
+import type { z } from 'zod';
+
+/** Methods a {@link RouteContract} can declare. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * Path-parameter names extracted from a path literal at the type level:
+ * `'/orders/:id/items/:itemId'` → `'id' | 'itemId'`.
+ */
+export type PathParams<TPath extends string> = TPath extends `${string}:${infer Rest}`
+  ? Rest extends `${infer Param}/${infer Tail}`
+    ? Param | PathParams<`/${Tail}`>
+    : Rest
+  : never;
+
+/** Typed view of a path's parameters: every value is a string. */
+export type ParamsOf<TPath extends string> = Readonly<Record<PathParams<TPath>, string>>;
+
+/**
+ * The minimal schema surface the engine needs (`parse` only). Every zod
+ * schema satisfies it structurally, which lets mixed-generic contracts
+ * live in one array without variance fights. Values MUST be zod schemas —
+ * `toOpenApi` converts them via `z.toJSONSchema`.
+ */
+export type SchemaLike = {
+  parse(input: unknown): unknown;
+};
+
+/**
+ * A JSON route contract. Create via {@link route}. The generics carry the
+ * validated input/output types into the bound handler's signature.
+ */
+export type RouteContract<TPath extends string = string, TQuery = undefined, TBody = undefined, TOutput = undefined> = {
+  readonly kind: 'http';
+  /** Stable identifier — lands in the manifest and OpenAPI `operationId`. */
+  readonly id: string;
+  readonly method: HttpMethod;
+  readonly path: TPath;
+  readonly summary?: string;
+  readonly query?: z.ZodType<TQuery>;
+  readonly body?: z.ZodType<TBody>;
+  readonly output?: z.ZodType<TOutput>;
+};
+
+/**
+ * A typed server-sent-events contract. Create via {@link route.sse}. The
+ * bound handler is an async generator; every yielded value is validated
+ * against `event` and framed as an SSE `data:` message.
+ */
+export type SseContract<TPath extends string = string, TQuery = undefined, TEvent = unknown> = {
+  readonly kind: 'sse';
+  readonly id: string;
+  readonly method: 'GET';
+  readonly path: TPath;
+  readonly summary?: string;
+  readonly query?: z.ZodType<TQuery>;
+  /** Schema every yielded event is validated against. */
+  readonly event: z.ZodType<TEvent>;
+  /** Emit `:keepalive` comments at this interval. Off when omitted. */
+  readonly heartbeatMs?: number;
+};
+
+/**
+ * Generics-erased view of a contract — what bundles store and the engine,
+ * manifest registration, and OpenAPI generation consume. Both contract
+ * types are structurally assignable to it; no casts involved.
+ */
+export type ContractLike = {
+  readonly kind: 'http' | 'sse';
+  readonly id: string;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly summary?: string;
+  readonly query?: SchemaLike;
+  readonly body?: SchemaLike;
+  readonly output?: SchemaLike;
+  readonly event?: SchemaLike;
+  readonly heartbeatMs?: number;
+};
+
+type RouteDef<TQuery, TBody, TOutput> = {
+  readonly id: string;
+  readonly summary?: string;
+  readonly query?: z.ZodType<TQuery>;
+  readonly body?: z.ZodType<TBody>;
+  readonly output?: z.ZodType<TOutput>;
+};
+
+const makeRoute =
+  <TMethod extends HttpMethod>(method: TMethod) =>
+  <TPath extends string, TQuery = undefined, TBody = undefined, TOutput = undefined>(
+    path: TPath,
+    def: RouteDef<TQuery, TBody, TOutput>,
+  ): RouteContract<TPath, TQuery, TBody, TOutput> => ({
+    kind: 'http',
+    method,
+    path,
+    ...def,
+  });
+
+/**
+ * Contract factories, one per method, plus {@link route.sse} for typed
+ * event streams.
+ *
+ * ```ts
+ * export const listOrders = route.get('/orders', {
+ *   id: 'orders.list',
+ *   query: z.object({ status: z.enum(['open', 'shipped']).optional() }),
+ *   output: z.array(Order),
+ * });
+ *
+ * export const progress = route.sse('/orders/:id/progress', {
+ *   id: 'orders.progress',
+ *   event: z.discriminatedUnion('type', [Queued, Shipped]),
+ * });
+ * ```
+ */
+export const route = {
+  get: makeRoute('GET'),
+  post: makeRoute('POST'),
+  put: makeRoute('PUT'),
+  patch: makeRoute('PATCH'),
+  delete: makeRoute('DELETE'),
+  sse: <TPath extends string, TEvent, TQuery = undefined>(
+    path: TPath,
+    def: {
+      readonly id: string;
+      readonly summary?: string;
+      readonly query?: z.ZodType<TQuery>;
+      readonly event: z.ZodType<TEvent>;
+      readonly heartbeatMs?: number;
+    },
+  ): SseContract<TPath, TQuery, TEvent> => ({
+    kind: 'sse',
+    method: 'GET',
+    path,
+    ...def,
+  }),
+};

package/src/derive.ts

@@ -0,0 +1,67 @@
+/**
+ * Request-scope derivers — "scope is data, not containers."
+ *
+ * A deriver is a named function from `(req, ctx)` to a value; each one
+ * adds a typed key to the per-request context handlers receive. Derivers
+ * run in declaration order, later derivers see earlier keys typed, and a
+ * deriver that throws {@link HttpError} short-circuits into the wire
+ * envelope — which is the entire "guard" story:
+ *
+ * ```ts
+ * const withPrincipal = derive('principal', async req => {
+ *   const p = await auth.verify(req.headers.get('authorization'));
+ *   if (!p) throw new HttpError(401, HTTP_ERROR_CODES.unauthorized, 'missing or invalid credentials');
+ *   return p;
+ * });
+ * ```
+ *
+ * Because bundles are assembled inside a pip's `boot`, derivers close over
+ * injected singletons — request scope is function application over the
+ * compile-time-wired service graph, not per-request container resolution.
+ */
+
+/**
+ * The context every handler and deriver receives. Derivers extend it with
+ * their own typed keys; the base keys are reserved.
+ */
+export type BaseRequestCtx = {
+  readonly req: Request;
+  readonly url: URL;
+  /** Inbound `x-request-id` header, else a fresh UUID. */
+  readonly requestId: string;
+  /** Aborts when the client disconnects. */
+  readonly signal: AbortSignal;
+};
+
+/** Base context keys — derivers may not shadow these. */
+export const BASE_CTX_KEYS = ['req', 'url', 'requestId', 'signal'] as const;
+
+/**
+ * A named, typed context deriver. `TIn` is the context the deriver needs
+ * to see — a deriver written against {@link BaseRequestCtx} composes into
+ * any bundle; one written against a richer context can only be added
+ * after the derivers that provide it.
+ */
+export type Deriver<K extends string = string, V = unknown, TIn extends BaseRequestCtx = BaseRequestCtx> = {
+  readonly key: K;
+  readonly derive: (req: Request, ctx: TIn) => V | Promise<V>;
+};
+
+/** Create a reusable {@link Deriver}. */
+export function derive<K extends string, V, TIn extends BaseRequestCtx = BaseRequestCtx>(
+  key: K,
+  fn: (req: Request, ctx: TIn) => V | Promise<V>,
+): Deriver<K, V, TIn> {
+  return { key, derive: fn };
+}
+
+/**
+ * Generics-erased deriver view for bundle storage. Typed derivers are
+ * assignable via parameter contravariance from the bottom type; the
+ * engine crosses the erasure boundary at the call site (`ctx as never`),
+ * mirroring the DOT kernel's hook-storage pattern.
+ */
+export type ErasedDeriver = {
+  readonly key: string;
+  readonly derive: (req: Request, ctx: never) => unknown;
+};

package/src/dot.ts

@@ -0,0 +1,282 @@
+/**
+ * DOT adapter for `@arki/http` — the `http()` pip.
+ *
+ * Mount it LAST. Feature pips publish {@link RouteBundle}s as token
+ * services in their `boot`; `http()` derives its `needs` from the tokens
+ * you pass, so the app builder's wiring guard enforces — at compile time —
+ * that every listed bundle is provided by an earlier pip:
+ *
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ * import { http } from '@arki/http/dot';
+ *
+ * const app = await defineApp('shop-api')
+ *   .use(db({ url }))
+ *   .use(ordersPip)          // publishes OrdersRoutes
+ *   .use(billingPip)         // publishes BillingRoutes
+ *   .use(http({ port: 3000, bundles: [OrdersRoutes, BillingRoutes] }))
+ *   .start();
+ * ```
+ *
+ * Lifecycle mapping — mounting last is what makes the drain order right:
+ *
+ *  - `boot`    — collect bundles, build the router, publish `httpServer`.
+ *                NOT listening yet; all feature boots finish first.
+ *  - `start`   — listen (first among starts — the route table is final).
+ *  - `stop`    — stop accepting, drain in-flight handlers
+ *                (`drainTimeoutMs`). Reverse order puts this FIRST:
+ *                ingress stops before feature pips tear down.
+ *  - `dispose` — sever remaining connections (open SSE streams end here)
+ *                and release the port.
+ *
+ * `@arki/dot` is an OPTIONAL peer of `@arki/http`. Importing this adapter
+ * without `@arki/dot` installed fails at module load — intentional: the
+ * adapter only makes sense inside a DOT app.
+ */
+
+import type { DotConfigureContext, EmptyShape, Pip, Token } from '@arki/dot/pip';
+import { DotPipError, pip } from '@arki/dot/pip';
+
+import type { RouteBundle } from './bundle.js';
+import type { ContractLike } from './contract.js';
+import type { HttpMiddleware } from './engine.js';
+import type { ListenHandle } from './listen.js';
+import { buildEngine, composeMiddleware } from './engine.js';
+import { HTTP_ERROR_CODES, HttpConfigError } from './error.js';
+import { listen } from './listen.js';
+import { contractMeta } from './openapi.js';
+
+/** A token publishing a {@link RouteBundle} — what `options.bundles` lists. */
+export type BundleToken = Token<RouteBundle, string>;
+
+/**
+ * The service the `http()` pip publishes. `fetch` is the composed handler
+ * — also the unit-test seam: call the app without a socket. `port`/`url`
+ * are defined once the app has started.
+ */
+export type HttpServer = {
+  readonly fetch: (req: Request) => Promise<Response>;
+  port(): number | undefined;
+  url(): string | undefined;
+  /** Requests currently being handled (streams count until their handler returns). */
+  inflight(): number;
+};
+
+/** Services published by the http adapter. */
+export type HttpServices = {
+  readonly httpServer: HttpServer;
+};
+
+export type HttpOptions<TBundles extends readonly BundleToken[]> = {
+  /** Port to listen on in `start`. `0` picks an ephemeral port. */
+  readonly port: number;
+  readonly hostname?: string;
+  /**
+   * Bundle tokens to serve, in route-table order. Each becomes a `needs`
+   * entry — the wiring guard rejects the composition unless an earlier
+   * pip publishes it.
+   */
+  readonly bundles: TBundles;
+  /**
+   * App-wide fetch-shaped middleware (first = outermost): CORS, request
+   * logging, compression. For per-request values use bundle derivers —
+   * they are typed into handler contexts; middleware is not.
+   */
+  readonly middleware?: readonly HttpMiddleware[];
+  /** Milliseconds `stop` waits for in-flight requests. Default 10 000. */
+  readonly drainTimeoutMs?: number;
+};
+
+/** Wire-needs record derived from the bundle tokens. */
+export type BundleNeeds<TBundles extends readonly BundleToken[]> = {
+  readonly [Tok in TBundles[number] as Tok extends Token<RouteBundle, infer K> ? K : never]: RouteBundle;
+};
+
+/**
+ * Stable error codes thrown by the http pip beyond the engine's own.
+ * Exported so consumers and coding agents can match against them.
+ */
+export const HTTP_PIP_ERROR_CODES = {
+  /** A bundle token's service was missing from the boot context (erased composition only). */
+  bundleMissing: 'ARKI_HTTP_E008',
+} as const;
+
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+
+type PipState = {
+  tracked: ((req: Request) => Promise<Response>) | undefined;
+  handle: ListenHandle | undefined;
+};
+
+type InflightGauge = {
+  count: number;
+  waiters: (() => void)[];
+};
+
+function drained(gauge: InflightGauge, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (gauge.count === 0) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      reject(new Error(`drain timeout after ${String(timeoutMs)}ms`));
+    }, timeoutMs);
+    timer.unref();
+    gauge.waiters.push(() => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+function displayHost(hostname: string): string {
+  return hostname === '0.0.0.0' || hostname === '::' ? 'localhost' : hostname;
+}
+
+/**
+ * Build the DOT pip that serves the given bundles. See the module docs
+ * for the composition pattern and lifecycle mapping.
+ */
+export function http<const TBundles extends readonly BundleToken[]>(
+  options: HttpOptions<TBundles>,
+): Pip<BundleNeeds<TBundles>, HttpServices> {
+  const needs: Record<string, BundleToken> = {};
+  for (const tok of options.bundles) {
+    if (needs[tok.key] !== undefined) {
+      throw new HttpConfigError({
+        code: HTTP_ERROR_CODES.duplicateRoute,
+        message: `[http] bundle token "${tok.key}" is listed twice in options.bundles.`,
+        remediation: 'List each bundle token once. To mount one bundle at two places, rename the publishing pip.',
+      });
+    }
+    needs[tok.key] = tok;
+  }
+
+  const state: PipState = { tracked: undefined, handle: undefined };
+  const gauge: InflightGauge = { count: 0, waiters: [] };
+
+  const inner = pip<EmptyShape, HttpServices>({
+    name: 'http',
+    version: '0.0.1',
+    // Compile-time/runtime seam: the precise needs shape is derived from
+    // `options.bundles` in the return-type cast below; here the runtime
+    // record rides in under the EmptyShape default. The kernel re-checks
+    // satisfaction at boot (DOT_LIFECYCLE_E012) for erased composition.
+    needs,
+    configure(ctx) {
+      ctx.registerService('httpServer', 'custom');
+    },
+    boot(ctx) {
+      // Erasure boundary: needs were declared dynamically above, so the
+      // typed hook context can't know the bundle keys — the tokens do.
+      const record = ctx as unknown as Readonly<Record<string, RouteBundle | undefined>>;
+      const bundles: RouteBundle[] = [];
+      for (const tok of options.bundles) {
+        const bundle = record[tok.key];
+        if (bundle === undefined) {
+          throw new DotPipError({
+            code: HTTP_PIP_ERROR_CODES.bundleMissing,
+            message: `[http] bundle "${tok.key}" was not provided by any earlier pip.`,
+            remediation:
+              'Mount the pip that publishes this bundle before http(...). The typed builder enforces this; erased composition reaches this check.',
+            docsUrl: 'https://arki.dev/http/errors/arki-http-e008',
+          });
+        }
+        bundles.push(bundle);
+      }
+
+      const engine = buildEngine(bundles);
+      const composed = composeMiddleware(engine.fetch, options.middleware ?? []);
+      const tracked = async (req: Request): Promise<Response> => {
+        gauge.count += 1;
+        try {
+          return await composed(req);
+        } finally {
+          gauge.count -= 1;
+          if (gauge.count === 0) {
+            const waiters = gauge.waiters.splice(0);
+            for (const waiter of waiters) waiter();
+          }
+        }
+      };
+      state.tracked = tracked;
+
+      const httpServer: HttpServer = {
+        fetch: tracked,
+        port: () => state.handle?.port,
+        url: () => {
+          const handle = state.handle;
+          return handle === undefined
+            ? undefined
+            : `http://${displayHost(handle.hostname)}:${String(handle.port)}`;
+        },
+        inflight: () => gauge.count,
+      };
+      return { httpServer };
+    },
+    async start() {
+      const tracked = state.tracked;
+      if (tracked === undefined) {
+        throw new DotPipError({
+          code: HTTP_PIP_ERROR_CODES.bundleMissing,
+          message: '[http] start ran without a booted engine — kernel contract violation.',
+          remediation: 'This should be unreachable; boot always precedes start. Report it.',
+          docsUrl: 'https://arki.dev/http/errors/arki-http-e008',
+        });
+      }
+      state.handle = await listen(tracked, {
+        port: options.port,
+        ...(options.hostname === undefined ? {} : { hostname: options.hostname }),
+      });
+    },
+    async stop() {
+      const handle = state.handle;
+      if (handle === undefined) return;
+      handle.stopAccepting();
+      const timeoutMs = options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+      try {
+        await drained(gauge, timeoutMs);
+        state.handle = undefined;
+      } catch {
+        const remaining = gauge.count;
+        handle.forceClose();
+        state.handle = undefined;
+        throw new DotPipError({
+          code: HTTP_ERROR_CODES.drainTimeout,
+          message: `[http] ${String(remaining)} request(s) still in flight after the ${String(timeoutMs)}ms drain budget — connections were severed.`,
+          remediation:
+            'Long-running handlers or streams outlived the drain budget. Raise drainTimeoutMs on http(...), or make handlers respect ctx.signal.',
+          docsUrl: 'https://arki.dev/http/errors/arki-http-e005',
+        });
+      }
+    },
+    dispose() {
+      if (state.handle !== undefined) {
+        state.handle.forceClose();
+        state.handle = undefined;
+      }
+    },
+  });
+
+  // Erasure seam: `inner` is Pip<{}, HttpServices> because the needs shape
+  // was runtime-built; the cast re-attaches the token-derived needs so the
+  // app builder's guard checks bundle provision. Same seam as rename()/
+  // testPip() in the kernel.
+  return inner as unknown as Pip<BundleNeeds<TBundles>, HttpServices>;
+}
+
+/**
+ * Register contracts in the DOT manifest from a feature pip's `configure`
+ * hook. Converts zod schemas to JSON Schema once, at configure time, so
+ * `dot explain --openapi` renders without booting:
+ *
+ * ```ts
+ * configure(ctx) {
+ *   registerRoutes(ctx, [listOrders, createOrder, progress]);
+ * }
+ * ```
+ */
+export function registerRoutes(ctx: DotConfigureContext, contracts: readonly ContractLike[]): void {
+  for (const contract of contracts) ctx.registerRoute(contractMeta(contract));
+}