@arki/http 0.0.1

package/dist/engine.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { runWithRequestContext } from './context.js';
+import { describeInternalError, errorResponse, HTTP_ERROR_CODES, HttpConfigError, HttpError, toErrorResponse } from './error.js';
+import { sseResponse } from './sse.js';
+/**
+ * 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) {
+    const app = new Hono();
+    const claimed = new Map();
+    const routeIds = [];
+    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, claimed, mount) {
+    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, claimed, bundle, binding) {
+    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, binding, req, params) {
+    const base = {
+        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 = 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);
+                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(input, ctx);
+                return sseResponse(events, binding.contract, base.signal);
+            }
+            const result = await binding.handler(input, ctx);
+            if (result instanceof Response)
+                return result;
+            return serializeOutput(binding.contract, result);
+        }
+        catch (error) {
+            return toErrorResponse(error);
+        }
+    });
+}
+async function validateInput(contract, params, url, req) {
+    let query;
+    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;
+    if (contract.body !== undefined) {
+        let raw;
+        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, value, where) {
+    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) {
+    if (error instanceof z.ZodError) {
+        return error.issues.map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
+    }
+    return describeInternalError(error);
+}
+function serializeOutput(contract, result) {
+    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;
+    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);
+}
+/**
+ * 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, middleware) {
+    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);
+        }
+    };
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

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

package/dist/error.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 declare const HTTP_ERROR_CODES: {
+    /** `start` could not bind the port. */
+    readonly listenFailed: "ARKI_HTTP_E001";
+    /** Two bindings claim the same method + path. */
+    readonly duplicateRoute: "ARKI_HTTP_E002";
+    /** `stop` exceeded `drainTimeoutMs` with requests still in flight. */
+    readonly drainTimeout: "ARKI_HTTP_E005";
+    /** A mount path is malformed. */
+    readonly invalidMount: "ARKI_HTTP_E006";
+    /** A deriver key duplicates an earlier deriver or a base context key. */
+    readonly duplicateDeriverKey: "ARKI_HTTP_E007";
+    /** Request validation failed (query/body) or the body is not valid JSON. */
+    readonly badRequest: "ARKI_HTTP_E400";
+    /** A deriver rejected the request's credentials. */
+    readonly unauthorized: "ARKI_HTTP_E401";
+    /** A deriver rejected the request's permissions. */
+    readonly forbidden: "ARKI_HTTP_E403";
+    /** No route matches the request. */
+    readonly notFound: "ARKI_HTTP_E404";
+    /** Handler crash or output-schema violation. */
+    readonly internal: "ARKI_HTTP_E500";
+};
+/**
+ * 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 declare 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;
+    });
+}
+/**
+ * A composition or lifecycle failure. Carries the same code/remediation/
+ * docsUrl fields the DOT kernel propagates into diagnostics when a hook
+ * throws.
+ */
+export declare 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;
+    });
+}
+/** 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 declare function describeInternalError(error: unknown): string;
+/**
+ * Map any thrown value to its wire envelope: {@link HttpError} keeps its
+ * status and fields; everything else is a redacted-in-production 500.
+ */
+export declare function toErrorResponse(error: unknown): Response;
+/** Build the envelope `Response` for a coded failure. */
+export declare function errorResponse(status: number, code: string, message: string, options?: {
+    readonly remediation?: string;
+    readonly docsUrl?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}): Response;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;IAC3B,uCAAuC;;IAEvC,iDAAiD;;IAEjD,sEAAsE;;IAEtE,iCAAiC;;IAEjC,yEAAyE;;IAEzE,4EAA4E;;IAE5E,oDAAoD;;IAEpD,oDAAoD;;IAEpD,oCAAoC;;IAEpC,gDAAgD;;CAExC,CAAC;AAIX;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;gBAG7D,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;KACrB;CAUT;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;CAOjI;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CASxD;AAED,yDAAyD;AACzD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD,GACL,QAAQ,CAUV"}

package/dist/error.js

@@ -0,0 +1,122 @@
+/**
+ * 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',
+};
+const docsUrlFor = (code) => `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 {
+    status;
+    code;
+    remediation;
+    docsUrl;
+    /** Extra response headers — e.g. `www-authenticate` on a 401, `retry-after` on a 429. */
+    headers;
+    constructor(status, code, message, options = {}) {
+        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 {
+    code;
+    remediation;
+    docsUrl;
+    constructor(fields) {
+        super(fields.message);
+        this.name = 'HttpConfigError';
+        this.code = fields.code;
+        this.remediation = fields.remediation;
+        this.docsUrl = fields.docsUrl ?? docsUrlFor(fields.code);
+    }
+}
+/**
+ * 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) {
+    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) {
+    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, code, message, options = {}) {
+    const envelope = {
+        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 }) });
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,YAAY,EACV,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,UAAU,EACV,aAAa,EACb,UAAU,EACV,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EACV,aAAa,EACb,YAAY,EACZ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACjI,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@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 { routes } from './bundle.js';
+export { BASE_CTX_KEYS, derive } from './derive.js';
+export { describeInternalError, errorResponse, HTTP_ERROR_CODES, HttpConfigError, HttpError, toErrorResponse } from './error.js';
+export { contractMeta, toOpenApi } from './openapi.js';
+export { buildEngine, composeMiddleware } from './engine.js';
+export { listen } from './listen.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAWtC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAcrC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGjI,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGvD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG7D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/listen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+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>;
+export declare function listen(fetch: FetchLike, options: ListenOptions): Promise<ListenHandle>;
+export {};
+//# sourceMappingURL=listen.d.ts.map

package/dist/listen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen.d.ts","sourceRoot":"","sources":["../src/listen.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,aAAa,IAAI,IAAI,CAAC;IACtB,wDAAwD;IACxD,UAAU,IAAI,IAAI,CAAC;CACpB,CAAC;AAEF,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAyBhE,wBAAsB,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAI5F"}

package/dist/listen.js

@@ -0,0 +1,71 @@
+/**
+ * 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';
+/** Narrow structural view of the Bun global — `@types/node` has no Bun. */
+function bunGlobal() {
+    return globalThis.Bun;
+}
+function listenFailure(port, cause) {
+    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, options) {
+    const bun = bunGlobal();
+    if (bun !== undefined)
+        return listenBun(bun, fetch, options);
+    return listenNode(fetch, options);
+}
+function listenBun(bun, fetch, options) {
+    let server;
+    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, options) {
+    const { serve } = await import('@hono/node-server');
+    return await new Promise((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;
+                    closable.closeAllConnections?.();
+                    closable.close();
+                },
+            });
+        });
+        server.on('error', (error) => {
+            reject(listenFailure(options.port, error));
+        });
+    });
+}
+//# sourceMappingURL=listen.js.map

package/dist/listen.js.map

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

package/dist/openapi.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenAPI generation — falls out of the contracts, doesn't bolt on.
+ *
+ * Contracts are static data carrying zod schemas, so the document is
+ * produced without booting anything, deterministically: same contracts in
+ * the same order → byte-identical output (DOT principle 3). No decorator
+ * reconstruction, no annotations — the schema IS the validation IS the
+ * documentation.
+ */
+import type { ContractLike } from './contract.js';
+export type OpenApiInfo = {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+};
+type JsonObject = Record<string, unknown>;
+/**
+ * Render an OpenAPI 3.1 document from contracts. Paths and operations
+ * appear in contract order; duplicate method+path pairs fail loudly with
+ * `ARKI_HTTP_E002` (the same collision `buildEngine` rejects at boot).
+ */
+export declare function toOpenApi(contracts: readonly ContractLike[], info: OpenApiInfo): JsonObject;
+/** The DOT `registerRoute` argument derived from a contract. */
+export type RouteMeta = {
+    readonly id: string;
+    readonly method: string;
+    readonly path: string;
+    readonly transport: 'http';
+    readonly description?: string;
+    readonly input?: {
+        readonly query?: JsonObject;
+        readonly body?: JsonObject;
+    };
+    readonly output?: JsonObject;
+    readonly streaming?: boolean;
+};
+/**
+ * Manifest metadata for a contract — what `registerRoutes` (from
+ * `@arki/http/dot`) feeds into `ctx.registerRoute` so that
+ * `dot explain --openapi` can render without booting. SSE contracts mark
+ * `streaming` and carry the per-event schema as `output`.
+ */
+export declare function contractMeta(contract: ContractLike): RouteMeta;
+export {};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAgF1C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAwB3F;AAED,gEAAgE;AAChE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAiB9D"}