@arki/http 0.0.1

package/dist/openapi.js

@@ -0,0 +1,140 @@
+/**
+ * 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 { z } from 'zod';
+import { HTTP_ERROR_CODES, HttpConfigError } from './error.js';
+/**
+ * Convert a contract schema to JSON Schema. Schema erasure seam:
+ * {@link ContractLike} types schemas as `parse`-only, but contracts built
+ * via `route.*` always hold zod schemas (see `SchemaLike` docs) — the
+ * cast re-attaches what the erased view dropped.
+ */
+function toJsonSchema(schema) {
+    const json = z.toJSONSchema(schema);
+    // The dialect header is noise when embedding into OpenAPI 3.1.
+    const { $schema: _dialect, ...rest } = json;
+    return rest;
+}
+function pathParamNames(path) {
+    return [...path.matchAll(/:(\w+)/g)]
+        .map(match => match[1])
+        .filter((name) => name !== undefined);
+}
+function openApiPath(path) {
+    return path.replaceAll(/:(\w+)/g, '{$1}');
+}
+function queryParameters(schema) {
+    const json = toJsonSchema(schema);
+    const properties = (json['properties'] ?? {});
+    const required = new Set(json['required']);
+    return Object.entries(properties).map(([name, propertySchema]) => ({
+        name,
+        in: 'query',
+        required: required.has(name),
+        schema: propertySchema,
+    }));
+}
+function buildOperation(contract) {
+    const parameters = pathParamNames(contract.path).map(name => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+    }));
+    if (contract.query !== undefined)
+        parameters.push(...queryParameters(contract.query));
+    const operation = { operationId: contract.id };
+    if (contract.summary !== undefined)
+        operation['summary'] = contract.summary;
+    if (parameters.length > 0)
+        operation['parameters'] = parameters;
+    if (contract.body !== undefined) {
+        operation['requestBody'] = {
+            required: true,
+            content: { 'application/json': { schema: toJsonSchema(contract.body) } },
+        };
+    }
+    if (contract.kind === 'sse') {
+        operation['responses'] = {
+            '200': {
+                description: 'event stream',
+                content: {
+                    'text/event-stream': contract.event === undefined ? {} : { schema: toJsonSchema(contract.event) },
+                },
+            },
+        };
+    }
+    else if (contract.output === undefined) {
+        operation['responses'] = { '200': { description: 'success' } };
+    }
+    else {
+        operation['responses'] = {
+            '200': {
+                description: 'success',
+                content: { 'application/json': { schema: toJsonSchema(contract.output) } },
+            },
+        };
+    }
+    return operation;
+}
+/**
+ * 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 function toOpenApi(contracts, info) {
+    const paths = {};
+    for (const contract of contracts) {
+        const path = openApiPath(contract.path);
+        const entry = (paths[path] ??= {});
+        const method = contract.method.toLowerCase();
+        if (entry[method] !== undefined) {
+            throw new HttpConfigError({
+                code: HTTP_ERROR_CODES.duplicateRoute,
+                message: `[http] duplicate route ${contract.method} ${contract.path}: "${contract.id}" collides with an earlier contract.`,
+                remediation: 'Two contracts claim the same method and path. Change one path, or drop the duplicate.',
+            });
+        }
+        entry[method] = buildOperation(contract);
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: info.title,
+            version: info.version,
+            ...(info.description === undefined ? {} : { description: info.description }),
+        },
+        paths,
+    };
+}
+/**
+ * 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 function contractMeta(contract) {
+    const input = {};
+    if (contract.query !== undefined)
+        input.query = toJsonSchema(contract.query);
+    if (contract.body !== undefined)
+        input.body = toJsonSchema(contract.body);
+    const outputSchema = contract.kind === 'sse' ? contract.event : contract.output;
+    return {
+        id: contract.id,
+        method: contract.method,
+        path: contract.path,
+        transport: 'http',
+        ...(contract.summary === undefined ? {} : { description: contract.summary }),
+        ...(Object.keys(input).length === 0 ? {} : { input }),
+        ...(outputSchema === undefined ? {} : { output: toJsonSchema(outputSchema) }),
+        ...(contract.kind === 'sse' ? { streaming: true } : {}),
+    };
+}
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

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

package/dist/sse.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Server-sent-events serialization for {@link SseContract} bindings.
+ *
+ * The bound handler is an async iterable; every yielded value is validated
+ * against the contract's event schema and framed as `data: <json>\n\n`.
+ * Client disconnect terminates the iterator (its `finally` blocks run);
+ * a yielded value that violates the schema — or a generator crash — emits
+ * a terminal `event: error` frame with the coded envelope, then closes.
+ */
+import type { ContractLike } from './contract.js';
+export declare function sseResponse(iterable: AsyncIterable<unknown>, contract: ContractLike, signal: AbortSignal): Response;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAUlD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,QAAQ,CAuEnH"}

package/dist/sse.js

@@ -0,0 +1,86 @@
+/**
+ * Server-sent-events serialization for {@link SseContract} bindings.
+ *
+ * The bound handler is an async iterable; every yielded value is validated
+ * against the contract's event schema and framed as `data: <json>\n\n`.
+ * Client disconnect terminates the iterator (its `finally` blocks run);
+ * a yielded value that violates the schema — or a generator crash — emits
+ * a terminal `event: error` frame with the coded envelope, then closes.
+ */
+import { describeInternalError, HTTP_ERROR_CODES } from './error.js';
+const SSE_HEADERS = {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache',
+    // Disable proxy buffering (nginx and friends) — events must flush.
+    'x-accel-buffering': 'no',
+};
+export function sseResponse(iterable, contract, signal) {
+    const encoder = new TextEncoder();
+    const iterator = iterable[Symbol.asyncIterator]();
+    let heartbeat;
+    let finished = false;
+    const cleanup = () => {
+        finished = true;
+        if (heartbeat !== undefined)
+            clearInterval(heartbeat);
+    };
+    const stopIterator = async () => {
+        try {
+            await iterator.return?.();
+        }
+        catch {
+            // Generator cleanup failures have no caller to surface to here; the
+            // generator's own resources are the pip's responsibility.
+        }
+    };
+    const stream = new ReadableStream({
+        start(controller) {
+            if (contract.heartbeatMs !== undefined && contract.heartbeatMs > 0) {
+                heartbeat = setInterval(() => {
+                    if (!finished && (controller.desiredSize ?? 0) > 0) {
+                        controller.enqueue(encoder.encode(':keepalive\n\n'));
+                    }
+                }, contract.heartbeatMs);
+                heartbeat.unref();
+            }
+            signal.addEventListener('abort', () => {
+                cleanup();
+                void stopIterator();
+            }, { once: true });
+        },
+        async pull(controller) {
+            try {
+                const next = await iterator.next();
+                if (finished)
+                    return;
+                if (next.done === true) {
+                    cleanup();
+                    controller.close();
+                    return;
+                }
+                const value = contract.event === undefined ? next.value : contract.event.parse(next.value);
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`));
+            }
+            catch (error) {
+                if (finished)
+                    return;
+                cleanup();
+                const payload = {
+                    error: {
+                        code: HTTP_ERROR_CODES.internal,
+                        message: describeInternalError(error),
+                    },
+                };
+                controller.enqueue(encoder.encode(`event: error\ndata: ${JSON.stringify(payload)}\n\n`));
+                controller.close();
+                void stopIterator();
+            }
+        },
+        cancel() {
+            cleanup();
+            void stopIterator();
+        },
+    });
+    return new Response(stream, { status: 200, headers: SSE_HEADERS });
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@arki/http",
+  "version": "0.0.1",
+  "description": "Typed HTTP for ARKI — route contracts as data, zod-validated handlers, request-scope derivers, SSE streaming, OpenAPI generation, and the DOT http() pip.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arki-labs/arki.git"
+  },
+  "homepage": "https://arki.dev",
+  "bugs": {
+    "url": "https://github.com/arki-labs/arki/issues"
+  },
+  "keywords": [
+    "arki",
+    "typescript",
+    "http",
+    "hono",
+    "sse",
+    "streaming",
+    "openapi",
+    "dot"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./dot": {
+      "types": "./dist/dot.d.ts",
+      "import": "./dist/dot.js",
+      "default": "./dist/dot.js"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "import": "./dist/context.js",
+      "default": "./dist/context.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "src/**",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/tests/**",
+    "!src/**/test/**",
+    "!src/**/__tests__/**",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "dependencies": {
+    "@arki/log": "0.0.2",
+    "@hono/node-server": "^2.0.8",
+    "hono": "^4.12.25",
+    "zod": "4.3.5"
+  },
+  "peerDependencies": {
+    "@arki/dot": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@arki/dot": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bundle.ts

@@ -0,0 +1,221 @@
+/**
+ * Route bundles — the dynamic half of an HTTP surface.
+ *
+ * A bundle binds contracts to handlers. It is assembled inside a pip's
+ * `boot` hook — where the pip's `needs` are already injected — so handlers
+ * and derivers close over typed singletons:
+ *
+ * ```ts
+ * export const OrdersRoutes = token<RouteBundle>()('orders.routes');
+ *
+ * export const ordersPip = pip({
+ *   name: 'orders',
+ *   needs: { db: service<Db>() },
+ *   configure(ctx) {
+ *     registerRoutes(ctx, [listOrders, createOrder]); // from '@arki/http/dot'
+ *   },
+ *   async boot({ db }) {
+ *     return provide(
+ *       OrdersRoutes,
+ *       routes()
+ *         .bind(listOrders, async ({ query }) => db.orders.list(query))
+ *         .bind(createOrder, async ({ body }, ctx) => db.orders.create(body, ctx.requestId)),
+ *     );
+ *   },
+ * });
+ * ```
+ *
+ * The builder accumulates deriver-added context keys in its type — a
+ * handler bound after `.derive('principal', …)` sees `ctx.principal`
+ * typed. Same accumulation idiom as `defineApp().use()`.
+ */
+
+import type { ContractLike, ParamsOf, RouteContract, SseContract } from './contract.js';
+import type { BaseRequestCtx, Deriver, ErasedDeriver } from './derive.js';
+import { BASE_CTX_KEYS } from './derive.js';
+import { HTTP_ERROR_CODES, HttpConfigError } from './error.js';
+
+type MaybePromise<T> = T | Promise<T>;
+
+/** The validated inputs a bound handler receives. */
+export type RouteInput<TPath extends string, TQuery, TBody> = {
+  readonly params: ParamsOf<TPath>;
+  readonly query: TQuery;
+  readonly body: TBody;
+};
+
+/**
+ * What a JSON handler may return: the contract's output type (serialized
+ * and validated), or a raw `Response` as the escape hatch — redirects,
+ * files, custom streams. Contracts without an output schema must return
+ * a `Response`.
+ */
+export type HandlerResult<TOutput> = [TOutput] extends [undefined] ? Response : TOutput | Response;
+
+/** Handler signature inferred from a {@link RouteContract}. */
+export type RouteHandler<TPath extends string, TQuery, TBody, TOutput, TCtx extends BaseRequestCtx> = (
+  input: RouteInput<TPath, TQuery, TBody>,
+  ctx: TCtx,
+) => MaybePromise<HandlerResult<TOutput>>;
+
+/**
+ * Handler signature inferred from an {@link SseContract}: an async
+ * iterable (usually an async generator) of events. Each yielded value is
+ * validated against the contract's event schema and framed as an SSE
+ * `data:` message. Client disconnect aborts `ctx.signal` and terminates
+ * the iterator.
+ */
+export type SseHandler<TPath extends string, TQuery, TEvent, TCtx extends BaseRequestCtx> = (
+  input: RouteInput<TPath, TQuery, undefined>,
+  ctx: TCtx,
+) => AsyncIterable<TEvent>;
+
+/** Non-HTTP transports a {@link RouteBundleBuilder.mount} can declare. */
+export type MountTransport = 'orpc' | 'trpc' | 'rpc' | 'custom';
+
+export type MountMeta = {
+  /** Stable identifier — lands in the manifest like a contract id. */
+  readonly id: string;
+  /** Manifest transport tag. Defaults to `'custom'`. */
+  readonly transport?: MountTransport;
+};
+
+/** A contract bound to its (generics-erased) handler. */
+export type RouteBinding = {
+  readonly contract: ContractLike;
+  /**
+   * Stored erased (`never` parameters) — typed handlers are assignable
+   * via parameter contravariance from the bottom type; the engine crosses
+   * the erasure boundary at the call site. Mirrors the DOT kernel's
+   * hook-storage pattern.
+   */
+  readonly handler: (input: never, ctx: never) => unknown;
+};
+
+/** A mounted foreign fetch handler (oRPC/tRPC router, static files, …). */
+export type MountBinding = {
+  readonly id: string;
+  readonly path: string;
+  readonly transport: MountTransport;
+  readonly handler: (req: Request) => Response | Promise<Response>;
+};
+
+/**
+ * A plain value: derivers + bound contracts + mounts. Published as an
+ * ordinary DOT service under a token and collected by the `http()` pip —
+ * no new kernel concept.
+ */
+export type RouteBundle = {
+  readonly derivers: readonly ErasedDeriver[];
+  readonly bindings: readonly RouteBinding[];
+  readonly mounts: readonly MountBinding[];
+};
+
+/**
+ * Immutable bundle builder. Every method returns a new builder; deriver
+ * keys accumulate in `TCtx` so later `bind` handlers see them typed.
+ */
+export type RouteBundleBuilder<TCtx extends BaseRequestCtx = BaseRequestCtx> = RouteBundle & {
+  /** Add a reusable deriver (see {@link Deriver}). */
+  derive<K extends string, V>(deriver: Deriver<K, V, TCtx>): RouteBundleBuilder<TCtx & Readonly<Record<K, V>>>;
+  /** Add an inline deriver. */
+  derive<K extends string, V>(
+    key: K,
+    fn: (req: Request, ctx: TCtx) => V | Promise<V>,
+  ): RouteBundleBuilder<TCtx & Readonly<Record<K, V>>>;
+  /**
+   * Bind a JSON contract to its handler. `NoInfer` pins the input/output
+   * generics to the contract — without it, a handler returning the wrong
+   * shape would silently widen `TOutput` instead of failing to compile.
+   */
+  bind<TPath extends string, TQuery, TBody, TOutput>(
+    contract: RouteContract<TPath, TQuery, TBody, TOutput>,
+    handler: RouteHandler<TPath, NoInfer<TQuery>, NoInfer<TBody>, NoInfer<TOutput>, TCtx>,
+  ): RouteBundleBuilder<TCtx>;
+  /** Bind an SSE contract to its event generator. */
+  bind<TPath extends string, TQuery, TEvent>(
+    contract: SseContract<TPath, TQuery, TEvent>,
+    handler: SseHandler<TPath, NoInfer<TQuery>, NoInfer<TEvent>, TCtx>,
+  ): RouteBundleBuilder<TCtx>;
+  /**
+   * Mount a foreign fetch handler under a path prefix — an oRPC router, a
+   * tRPC fetch adapter, a static-file handler. One manifest route, no
+   * schemas, derivers do NOT run for mounted handlers.
+   */
+  mount(
+    path: string,
+    handler: (req: Request) => Response | Promise<Response>,
+    meta: MountMeta,
+  ): RouteBundleBuilder<TCtx>;
+};
+
+type BundleState = {
+  readonly derivers: readonly ErasedDeriver[];
+  readonly bindings: readonly RouteBinding[];
+  readonly mounts: readonly MountBinding[];
+};
+
+function assertFreshDeriverKey(key: string, existing: readonly ErasedDeriver[]): void {
+  const reserved = (BASE_CTX_KEYS as readonly string[]).includes(key);
+  const duplicate = existing.some(d => d.key === key);
+  if (!reserved && !duplicate) return;
+  throw new HttpConfigError({
+    code: HTTP_ERROR_CODES.duplicateDeriverKey,
+    message: reserved
+      ? `[http] deriver key "${key}" shadows a base request-context key.`
+      : `[http] deriver key "${key}" is already derived in this bundle.`,
+    remediation: `Pick a different key — base keys (${BASE_CTX_KEYS.join(', ')}) and earlier deriver keys are reserved.`,
+  });
+}
+
+function makeBuilder(state: BundleState): RouteBundleBuilder {
+  const impl = {
+    derivers: state.derivers,
+    bindings: state.bindings,
+    mounts: state.mounts,
+    derive(keyOrDeriver: string | ErasedDeriver, fn?: (req: Request, ctx: never) => unknown): RouteBundleBuilder {
+      let deriver: ErasedDeriver;
+      if (typeof keyOrDeriver === 'string') {
+        if (fn === undefined) {
+          throw new HttpConfigError({
+            code: HTTP_ERROR_CODES.duplicateDeriverKey,
+            message: `[http] derive("${keyOrDeriver}") is missing its deriver function.`,
+            remediation: 'Pass derive(key, fn) or derive(deriverObject).',
+          });
+        }
+        deriver = { key: keyOrDeriver, derive: fn };
+      } else {
+        deriver = keyOrDeriver;
+      }
+      assertFreshDeriverKey(deriver.key, state.derivers);
+      return makeBuilder({ ...state, derivers: [...state.derivers, deriver] });
+    },
+    bind(contract: ContractLike, handler: (input: never, ctx: never) => unknown): RouteBundleBuilder {
+      return makeBuilder({ ...state, bindings: [...state.bindings, { contract, handler }] });
+    },
+    mount(path: string, handler: (req: Request) => Response | Promise<Response>, meta: MountMeta): RouteBundleBuilder {
+      if (!path.startsWith('/') || path.includes(' ')) {
+        throw new HttpConfigError({
+          code: HTTP_ERROR_CODES.invalidMount,
+          message: `[http] mount path "${path}" is invalid — it must start with "/" and contain no spaces.`,
+          remediation: 'Mount under an absolute path prefix, e.g. mount("/rpc", handler, { id: "rpc" }).',
+        });
+      }
+      return makeBuilder({
+        ...state,
+        mounts: [...state.mounts, { id: meta.id, path, transport: meta.transport ?? 'custom', handler }],
+      });
+    },
+  };
+  // Erasure seam: the implementation works on erased contracts/handlers/
+  // derivers; the public builder type re-attaches the generics. The typed
+  // methods' arguments are structurally assignable to the erased
+  // parameters, so the only unsafe step is this widening of the return
+  // type — same seam as the DOT app builder's makeBuilder.
+  return impl as unknown as RouteBundleBuilder;
+}
+
+/** Start an empty bundle. See the module docs for the authoring pattern. */
+export function routes(): RouteBundleBuilder {
+  return makeBuilder({ derivers: [], bindings: [], mounts: [] });
+}

package/src/context.ts

@@ -0,0 +1,39 @@
+/**
+ * Ambient request context — the last resort.
+ *
+ * Explicit `ctx` threading fails in one honest case: code deep in a call
+ * stack whose signatures you don't control (log enrichment inside a
+ * shared library). For that, this entry exposes the current request's
+ * {@link BaseRequestCtx} via `AsyncLocalStorage`.
+ *
+ * Ambient context is a smell — prefer the explicit `ctx` parameter and
+ * derivers everywhere a signature is yours to change. Note that OTel
+ * trace context already propagates this way, so span/log correlation
+ * needs none of this.
+ *
+ * This module is deliberately NOT re-exported from the package root.
+ * Import it as `@arki/http/context`.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import type { BaseRequestCtx } from './derive.js';
+
+const storage = new AsyncLocalStorage<BaseRequestCtx>();
+
+/**
+ * The context of the request currently being handled, or `undefined`
+ * outside a request (startup, background jobs, tests that call handlers
+ * directly).
+ */
+export function requestContext(): BaseRequestCtx | undefined {
+  return storage.getStore();
+}
+
+/**
+ * Engine seam: run `fn` with `ctx` as the ambient request context. Called
+ * by the engine around every request — not part of the public surface.
+ */
+export function runWithRequestContext<T>(ctx: BaseRequestCtx, fn: () => T): T {
+  return storage.run(ctx, fn);
+}