@arki/http 0.0.1

package/dist/contract.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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>;
+};
+/**
+ * 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 declare const route: {
+    get: <TPath extends string, TQuery = undefined, TBody = undefined, TOutput = undefined>(path: TPath, def: RouteDef<TQuery, TBody, TOutput>) => RouteContract<TPath, TQuery, TBody, TOutput>;
+    post: <TPath extends string, TQuery = undefined, TBody = undefined, TOutput = undefined>(path: TPath, def: RouteDef<TQuery, TBody, TOutput>) => RouteContract<TPath, TQuery, TBody, TOutput>;
+    put: <TPath extends string, TQuery = undefined, TBody = undefined, TOutput = undefined>(path: TPath, def: RouteDef<TQuery, TBody, TOutput>) => RouteContract<TPath, TQuery, TBody, TOutput>;
+    patch: <TPath extends string, TQuery = undefined, TBody = undefined, TOutput = undefined>(path: TPath, def: RouteDef<TQuery, TBody, TOutput>) => RouteContract<TPath, TQuery, TBody, TOutput>;
+    delete: <TPath extends string, TQuery = undefined, TBody = undefined, TOutput = undefined>(path: TPath, def: RouteDef<TQuery, TBody, TOutput>) => RouteContract<TPath, TQuery, TBody, TOutput>;
+    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>;
+};
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -0,0 +1,49 @@
+/**
+ * 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`).
+ */
+const makeRoute = (method) => (path, def) => ({
+    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: (path, def) => ({
+        kind: 'sse',
+        method: 'GET',
+        path,
+        ...def,
+    }),
+};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0FH,MAAM,SAAS,GACb,CAA6B,MAAe,EAAE,EAAE,CAChD,CACE,IAAW,EACX,GAAqC,EACS,EAAE,CAAC,CAAC;IAClD,IAAI,EAAE,MAAM;IACZ,MAAM;IACN,IAAI;IACJ,GAAG,GAAG;CACP,CAAC,CAAC;AAEL;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC;IACrB,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC;IACzB,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC;IAC3B,GAAG,EAAE,CACH,IAAW,EACX,GAMC,EACmC,EAAE,CAAC,CAAC;QACxC,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,KAAK;QACb,IAAI;QACJ,GAAG,GAAG;KACP,CAAC;CACH,CAAC"}

package/dist/derive.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare const BASE_CTX_KEYS: readonly ["req", "url", "requestId", "signal"];
+/**
+ * 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 declare function derive<K extends string, V, TIn extends BaseRequestCtx = BaseRequestCtx>(key: K, fn: (req: Request, ctx: TIn) => V | Promise<V>): Deriver<K, V, TIn>;
+/**
+ * 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;
+};
+//# sourceMappingURL=derive.d.ts.map

package/dist/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,aAAa,gDAAiD,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,SAAS,cAAc,GAAG,cAAc,IAAI;IACzG,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAChB,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF,yCAAyC;AACzC,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,SAAS,cAAc,GAAG,cAAc,EACrF,GAAG,EAAE,CAAC,EACN,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAEpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC;CACxD,CAAC"}

package/dist/derive.js

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+/** Base context keys — derivers may not shadow these. */
+export const BASE_CTX_KEYS = ['req', 'url', 'requestId', 'signal'];
+/** Create a reusable {@link Deriver}. */
+export function derive(key, fn) {
+    return { key, derive: fn };
+}
+//# sourceMappingURL=derive.js.map

package/dist/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,yDAAyD;AACzD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAa5E,yCAAyC;AACzC,MAAM,UAAU,MAAM,CACpB,GAAM,EACN,EAA8C;IAE9C,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC7B,CAAC"}

package/dist/dot.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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, Pip, Token } from '@arki/dot/pip';
+import type { RouteBundle } from './bundle.js';
+import type { ContractLike } from './contract.js';
+import type { HttpMiddleware } from './engine.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 declare const HTTP_PIP_ERROR_CODES: {
+    /** A bundle token's service was missing from the boot context (erased composition only). */
+    readonly bundleMissing: "ARKI_HTTP_E008";
+};
+/**
+ * Build the DOT pip that serves the given bundles. See the module docs
+ * for the composition pattern and lifecycle mapping.
+ */
+export declare function http<const TBundles extends readonly BundleToken[]>(options: HttpOptions<TBundles>): 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 declare function registerRoutes(ctx: DotConfigureContext, contracts: readonly ContractLike[]): void;
+//# sourceMappingURL=dot.d.ts.map

package/dist/dot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAc,GAAG,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAGjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAOlD,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,IAAI,MAAM,GAAG,SAAS,CAAC;IAC3B,GAAG,IAAI,MAAM,GAAG,SAAS,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,IAAI,MAAM,CAAC;CACpB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,QAAQ,SAAS,SAAS,WAAW,EAAE,IAAI;IACjE,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,WAAW,CAAC,QAAQ,SAAS,SAAS,WAAW,EAAE,IAAI;IACjE,QAAQ,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,GAAG,SAAS,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,WAAW;CACvG,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB;IAC/B,4FAA4F;;CAEpF,CAAC;AAmCX;;;GAGG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,QAAQ,SAAS,SAAS,WAAW,EAAE,EAChE,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,GAC7B,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,CA4H1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAEjG"}

package/dist/dot.js

@@ -0,0 +1,210 @@
+/**
+ * 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 { DotPipError, pip } from '@arki/dot/pip';
+import { buildEngine, composeMiddleware } from './engine.js';
+import { HTTP_ERROR_CODES, HttpConfigError } from './error.js';
+import { listen } from './listen.js';
+import { contractMeta } from './openapi.js';
+/**
+ * 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',
+};
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+function drained(gauge, timeoutMs) {
+    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) {
+    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(options) {
+    const needs = {};
+    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 = { tracked: undefined, handle: undefined };
+    const gauge = { count: 0, waiters: [] };
+    const inner = pip({
+        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;
+            const bundles = [];
+            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) => {
+                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 = {
+                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;
+}
+/**
+ * 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, contracts) {
+    for (const contract of contracts)
+        ctx.registerRoute(contractMeta(contract));
+}
+//# sourceMappingURL=dot.js.map

package/dist/dot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { RouteBundle } from './bundle.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 declare function buildEngine(bundles: readonly RouteBundle[]): Engine;
+/**
+ * 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 declare function composeMiddleware(fetch: (req: Request) => Promise<Response>, middleware: readonly HttpMiddleware[]): (req: Request) => Promise<Response>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAA8B,WAAW,EAAE,MAAM,aAAa,CAAC;AAO3E,2EAA2E;AAC3E,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAyBnE;AAuJD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAC1C,UAAU,EAAE,SAAS,cAAc,EAAE,GACpC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAcrC"}