@adhd/apigen-gateway 0.1.0

package/index.d.ts

@@ -0,0 +1,2 @@
+export declare const __apigen_pkg = "@adhd/apigen-gateway";
+export { createGateway, type Gateway, type GatewayOptions, type GatewayHealth, type HostHealth, type HostStatus, type HostAdapter, type HostRequest, type InProcessRuntime, createInProcessHostAdapter, type BackoffPolicy, defaultBackoff, GATEWAY_ERROR_CODES, type GatewayErrorCode, GATEWAY_HTTP_STATUS, GATEWAY_GRPC_CODE, type GatewayErrorDetail, makeUnavailableError, makeDeadlineExceededError, isGatewayError, } from './lib/gateway';

package/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class m extends Error{constructor(r,i,o){super(i),this.name="ApiError",this.code=r,this.details=o,Object.setPrototypeOf(this,new.target.prototype)}toJSON(){const r={code:this.code,message:this.message};return this.details!==void 0&&(r.details=this.details),r}}const S=["unavailable","deadline_exceeded"],v={unavailable:503,deadline_exceeded:504},g={unavailable:"UNAVAILABLE",deadline_exceeded:"DEADLINE_EXCEEDED"};function l(s,r,i){const o={gatewayCode:"unavailable",host:s,operationId:r,httpStatus:v.unavailable,grpcCode:g.unavailable};return new m("internal",`host '${s}' unavailable: ${i}`,o)}function T(s,r,i){const o={gatewayCode:"deadline_exceeded",host:s,operationId:r,httpStatus:v.deadline_exceeded,grpcCode:g.deadline_exceeded};return new m("internal",`op '${r}' on host '${s}' exceeded ${i}ms deadline`,o)}function C(s){if(!(s instanceof m)||s.details==null||typeof s.details!="object")return!1;const r=s.details;return r.gatewayCode==="unavailable"||r.gatewayCode==="deadline_exceeded"}function D(s,r,i={}){let o=!1;const n=i.readyWhenStarted??!0;return{host:s,hopCost:0,async start(){o=!0},async ready(){return o&&n},async invoke(c,w){if(!o)throw l(s,c.operation.id,"not started");return r.invoke(c,w)},onExit(){return()=>{}},async stop(){o=!1}}}const k={delayMs(s){return Math.min(50*2**(s-1),5e3)},maxRestarts:0};function P(s){const r=s.defaultDeadlineMs??3e4,i=s.backoff??k,o=s.timers??{setTimeout:(e,a)=>setTimeout(e,a),clearTimeout:e=>clearTimeout(e)},n=new Map;for(const e of s.adapters){if(n.has(e.host))throw new Error(`apigen-gateway: duplicate host adapter '${e.host}'`);n.set(e.host,{adapter:e,status:"down",restarts:0,unsubscribe:()=>{},retired:!1})}function c(e){return new Promise(a=>{if(e<=0){a();return}o.setTimeout(a,e)})}async function w(e){if(e.retired)return;e.unsubscribe(),e.unsubscribe=e.adapter.onExit(t=>{x(e)}),await e.adapter.start();let a=!1;try{a=await e.adapter.ready()}catch{a=!1}e.retired||(e.status=a?"ready":"degraded")}async function x(e,a){if(e.retired)return;e.status="down";let t=0;for(;!e.retired;){if(t+=1,e.restarts+=1,i.maxRestarts>0&&t>i.maxRestarts){e.status="down";return}if(await c(i.delayMs(t)),e.retired)return;try{await e.adapter.start();const d=await e.adapter.ready();if(e.retired)return;if(d){e.status="ready";return}e.status="degraded"}catch{e.status="down"}}}async function _(e){if(e.retired||e.status==="down")return;let a=!1;try{a=await e.adapter.ready()}catch{a=!1}e.status=a?"ready":"degraded"}function y(e,a,t,d){return new Promise((E,b)=>{let u=!1;const f=new AbortController,p=()=>f.abort(t.reason);t.aborted?f.abort(t.reason):t.addEventListener("abort",p,{once:!0});const A=o.setTimeout(()=>{u||(u=!0,t.removeEventListener("abort",p),f.abort("deadline"),b(T(e.adapter.host,a.operation.id,d)))},d);e.adapter.invoke(a,f.signal).then(h=>{u||(u=!0,o.clearTimeout(A),t.removeEventListener("abort",p),E(h))},h=>{u||(u=!0,o.clearTimeout(A),t.removeEventListener("abort",p),e.status!=="ready"&&!C(h)?b(l(e.adapter.host,a.operation.id,"host not serving")):b(h))})})}return{async start(){await Promise.all([...n.values()].map(e=>w(e)))},async route(e,a){const t=e.operation.host,d=n.get(t);if(d==null)throw l(t,e.operation.id,"no adapter registered for host");if(d.status==="degraded"&&await _(d),d.status!=="ready")throw l(t,e.operation.id,`host status '${d.status}'`);const E=a??new AbortController().signal;return y(d,e,E,r)},async health(){const e={};let a=!1;return await Promise.all([...n.values()].map(async t=>{t.status==="degraded"&&await _(t),t.status==="ready"&&(a=!0),e[t.adapter.host]={host:t.adapter.host,status:t.status,hopCost:t.adapter.hopCost,restarts:t.restarts}})),{hosts:e,serving:a}},topologyCost(){let e=0;for(const a of n.values())e+=a.adapter.hopCost;return e},async stop(){await Promise.all([...n.values()].map(async e=>{e.retired=!0,e.unsubscribe(),e.status="down",await e.adapter.stop()}))}}}const R="@adhd/apigen-gateway";exports.GATEWAY_ERROR_CODES=S;exports.GATEWAY_GRPC_CODE=g;exports.GATEWAY_HTTP_STATUS=v;exports.__apigen_pkg=R;exports.createGateway=P;exports.createInProcessHostAdapter=D;exports.defaultBackoff=k;exports.isGatewayError=C;exports.makeDeadlineExceededError=T;exports.makeUnavailableError=l;

package/index.mjs

@@ -0,0 +1,229 @@
+class v extends Error {
+  constructor(r, i, o) {
+    super(i), this.name = "ApiError", this.code = r, this.details = o, Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** Serialise to a plain object suitable for JSON transport. */
+  toJSON() {
+    const r = {
+      code: this.code,
+      message: this.message
+    };
+    return this.details !== void 0 && (r.details = this.details), r;
+  }
+}
+const D = ["unavailable", "deadline_exceeded"], _ = {
+  unavailable: 503,
+  deadline_exceeded: 504
+}, A = {
+  unavailable: "UNAVAILABLE",
+  deadline_exceeded: "DEADLINE_EXCEEDED"
+};
+function h(s, r, i) {
+  const o = {
+    gatewayCode: "unavailable",
+    host: s,
+    operationId: r,
+    httpStatus: _.unavailable,
+    grpcCode: A.unavailable
+  };
+  return new v("internal", `host '${s}' unavailable: ${i}`, o);
+}
+function T(s, r, i) {
+  const o = {
+    gatewayCode: "deadline_exceeded",
+    host: s,
+    operationId: r,
+    httpStatus: _.deadline_exceeded,
+    grpcCode: A.deadline_exceeded
+  };
+  return new v("internal", `op '${r}' on host '${s}' exceeded ${i}ms deadline`, o);
+}
+function k(s) {
+  if (!(s instanceof v) || s.details == null || typeof s.details != "object")
+    return !1;
+  const r = s.details;
+  return r.gatewayCode === "unavailable" || r.gatewayCode === "deadline_exceeded";
+}
+function P(s, r, i = {}) {
+  let o = !1;
+  const n = i.readyWhenStarted ?? !0;
+  return {
+    host: s,
+    hopCost: 0,
+    async start() {
+      o = !0;
+    },
+    async ready() {
+      return o && n;
+    },
+    async invoke(l, w) {
+      if (!o)
+        throw h(s, l.operation.id, "not started");
+      return r.invoke(l, w);
+    },
+    onExit() {
+      return () => {
+      };
+    },
+    async stop() {
+      o = !1;
+    }
+  };
+}
+const y = {
+  delayMs(s) {
+    return Math.min(50 * 2 ** (s - 1), 5e3);
+  },
+  maxRestarts: 0
+};
+function R(s) {
+  const r = s.defaultDeadlineMs ?? 3e4, i = s.backoff ?? y, o = s.timers ?? {
+    setTimeout: (e, a) => setTimeout(e, a),
+    clearTimeout: (e) => clearTimeout(e)
+  }, n = /* @__PURE__ */ new Map();
+  for (const e of s.adapters) {
+    if (n.has(e.host))
+      throw new Error(`apigen-gateway: duplicate host adapter '${e.host}'`);
+    n.set(e.host, {
+      adapter: e,
+      status: "down",
+      restarts: 0,
+      unsubscribe: () => {
+      },
+      retired: !1
+    });
+  }
+  function l(e) {
+    return new Promise((a) => {
+      if (e <= 0) {
+        a();
+        return;
+      }
+      o.setTimeout(a, e);
+    });
+  }
+  async function w(e) {
+    if (e.retired)
+      return;
+    e.unsubscribe(), e.unsubscribe = e.adapter.onExit((t) => {
+      C(e);
+    }), await e.adapter.start();
+    let a = !1;
+    try {
+      a = await e.adapter.ready();
+    } catch {
+      a = !1;
+    }
+    e.retired || (e.status = a ? "ready" : "degraded");
+  }
+  async function C(e, a) {
+    if (e.retired)
+      return;
+    e.status = "down";
+    let t = 0;
+    for (; !e.retired; ) {
+      if (t += 1, e.restarts += 1, i.maxRestarts > 0 && t > i.maxRestarts) {
+        e.status = "down";
+        return;
+      }
+      if (await l(i.delayMs(t)), e.retired)
+        return;
+      try {
+        await e.adapter.start();
+        const d = await e.adapter.ready();
+        if (e.retired)
+          return;
+        if (d) {
+          e.status = "ready";
+          return;
+        }
+        e.status = "degraded";
+      } catch {
+        e.status = "down";
+      }
+    }
+  }
+  async function E(e) {
+    if (e.retired || e.status === "down")
+      return;
+    let a = !1;
+    try {
+      a = await e.adapter.ready();
+    } catch {
+      a = !1;
+    }
+    e.status = a ? "ready" : "degraded";
+  }
+  function x(e, a, t, d) {
+    return new Promise((b, m) => {
+      let u = !1;
+      const c = new AbortController(), f = () => c.abort(t.reason);
+      t.aborted ? c.abort(t.reason) : t.addEventListener("abort", f, { once: !0 });
+      const g = o.setTimeout(() => {
+        u || (u = !0, t.removeEventListener("abort", f), c.abort("deadline"), m(T(e.adapter.host, a.operation.id, d)));
+      }, d);
+      e.adapter.invoke(a, c.signal).then(
+        (p) => {
+          u || (u = !0, o.clearTimeout(g), t.removeEventListener("abort", f), b(p));
+        },
+        (p) => {
+          u || (u = !0, o.clearTimeout(g), t.removeEventListener("abort", f), e.status !== "ready" && !k(p) ? m(h(e.adapter.host, a.operation.id, "host not serving")) : m(p));
+        }
+      );
+    });
+  }
+  return {
+    async start() {
+      await Promise.all([...n.values()].map((e) => w(e)));
+    },
+    async route(e, a) {
+      const t = e.operation.host, d = n.get(t);
+      if (d == null)
+        throw h(t, e.operation.id, "no adapter registered for host");
+      if (d.status === "degraded" && await E(d), d.status !== "ready")
+        throw h(t, e.operation.id, `host status '${d.status}'`);
+      const b = a ?? new AbortController().signal;
+      return x(d, e, b, r);
+    },
+    async health() {
+      const e = {};
+      let a = !1;
+      return await Promise.all(
+        [...n.values()].map(async (t) => {
+          t.status === "degraded" && await E(t), t.status === "ready" && (a = !0), e[t.adapter.host] = {
+            host: t.adapter.host,
+            status: t.status,
+            hopCost: t.adapter.hopCost,
+            restarts: t.restarts
+          };
+        })
+      ), { hosts: e, serving: a };
+    },
+    topologyCost() {
+      let e = 0;
+      for (const a of n.values())
+        e += a.adapter.hopCost;
+      return e;
+    },
+    async stop() {
+      await Promise.all(
+        [...n.values()].map(async (e) => {
+          e.retired = !0, e.unsubscribe(), e.status = "down", await e.adapter.stop();
+        })
+      );
+    }
+  };
+}
+const S = "@adhd/apigen-gateway";
+export {
+  D as GATEWAY_ERROR_CODES,
+  A as GATEWAY_GRPC_CODE,
+  _ as GATEWAY_HTTP_STATUS,
+  S as __apigen_pkg,
+  R as createGateway,
+  P as createInProcessHostAdapter,
+  y as defaultBackoff,
+  k as isGatewayError,
+  T as makeDeadlineExceededError,
+  h as makeUnavailableError
+};

package/lib/gateway.d.ts

@@ -0,0 +1,219 @@
+import { Operation, Transport } from '@adhd/apigen-core';
+import { ApiError } from '@adhd/apigen-errors';
+
+/** The distributed-system error codes the gateway raises (SPEC §13.1). */
+export declare const GATEWAY_ERROR_CODES: readonly ["unavailable", "deadline_exceeded"];
+/** String-union type for the gateway error codes. */
+export type GatewayErrorCode = (typeof GATEWAY_ERROR_CODES)[number];
+/** code → HTTP status (SPEC §9.1: unavailable = 503, deadline_exceeded = 504). */
+export declare const GATEWAY_HTTP_STATUS: Record<GatewayErrorCode, number>;
+/** code → gRPC status name (SPEC §9.1). */
+export declare const GATEWAY_GRPC_CODE: Record<GatewayErrorCode, string>;
+/**
+ * Structured detail attached to a gateway `ApiError` so transport adapters can read
+ * the distributed-system code and host without string-matching the message.
+ */
+export interface GatewayErrorDetail {
+    /** The §13.1 code: `unavailable` or `deadline_exceeded`. */
+    gatewayCode: GatewayErrorCode;
+    /** The host whose op failed. */
+    host: string;
+    /** The operation id that was being routed. */
+    operationId: string;
+    /** Suggested HTTP status for the transport adapter. */
+    httpStatus: number;
+    /** Suggested gRPC status name for the transport adapter. */
+    grpcCode: string;
+}
+/**
+ * Build the `ApiError` raised when a host is not serving (down / not-ready / restarting).
+ * Maps to the core `internal` taxonomy slot but carries the real §13.1 `unavailable`
+ * code in `details.gatewayCode` (and a 503 hint) — the shared `ApiError` type has no
+ * `unavailable` member, so the gateway code travels in `details`.
+ */
+export declare function makeUnavailableError(host: string, operationId: string, reason: string): ApiError;
+/**
+ * Build the `ApiError` raised when a cross-host op exceeds its deadline (SPEC §13.1).
+ * Carries the real `deadline_exceeded` code + a 504 hint in `details`.
+ */
+export declare function makeDeadlineExceededError(host: string, operationId: string, deadlineMs: number): ApiError;
+/** Type guard: was this `ApiError` raised by the gateway failure model? */
+export declare function isGatewayError(err: unknown): err is ApiError & {
+    details: GatewayErrorDetail;
+};
+/**
+ * A host's status as reported by the gateway's aggregate `_meta/health` (SPEC §13.1):
+ *
+ *  - `ready`    — the sidecar reported ready via its `_meta/health` mount; ops route.
+ *  - `degraded` — the host is up but its readiness probe is failing (ops do NOT route).
+ *  - `down`     — the host crashed / is not spawned / is restarting; ops do NOT route.
+ */
+export type HostStatus = 'ready' | 'degraded' | 'down';
+/**
+ * The single request the gateway forwards to a host runtime over its IPC.
+ *
+ * Mirrors the cross-host-portable subset of a core `Call`: the operation, the bare domain
+ * `data`, the metadata `envelope`, and the transport tag. `signal` and the deadline are
+ * handled by the gateway around the adapter call — they do not cross the IPC boundary as
+ * part of this struct (the adapter receives `signal` as a separate argument so it can
+ * propagate cancellation natively).
+ */
+export interface HostRequest {
+    /** The operation being invoked (carries `operation.host` → routing key). */
+    operation: Operation;
+    /** Bare domain params (the `data`-wrapper dissolved; ctx excluded). */
+    data: Record<string, unknown>;
+    /** Transport-native side-channel metadata (session, auth, …). */
+    envelope: Record<string, unknown>;
+    /** Which transport delivered the original call. */
+    transport: Transport;
+}
+/**
+ * A host runtime as seen by the gateway (SPEC §14.4 "gateway adapter").
+ *
+ * This is the ONE seam every host language plugs into. The in-process TS adapter
+ * ({@link createInProcessHostAdapter}) calls the runtime directly (zero hop); the
+ * out-of-process Python adapter (the `python-host` state) spawns a subprocess and speaks
+ * the IPC (one round-trip); the in-memory fake (tests) closes over a map. The gateway is
+ * written ONLY against this interface — it never knows which kind it routes to.
+ */
+export interface HostAdapter {
+    /** The host tag this adapter serves (matches `operation.host`). */
+    readonly host: string;
+    /**
+     * Routing cost of this host, in IPC round-trips per op (SPEC §13.1 cost function):
+     *  - `0` — in-process (zero hop; the TS fast path).
+     *  - `1` — out-of-process sidecar (serialize → IPC → deserialize).
+     * The CLI's "simplest viable topology" selector minimises the sum of these.
+     */
+    readonly hopCost: 0 | 1;
+    /**
+     * Bring the host up (spawn the sidecar / initialise the in-process runtime). Resolves
+     * when the process exists — NOT when it is ready. Readiness is reported separately via
+     * {@link ready}. Idempotent: calling `start()` on an already-started adapter is a no-op.
+     */
+    start(): Promise<void>;
+    /**
+     * Readiness probe — the gateway calls this to learn whether the host's `_meta/health`
+     * mount reports ready (SPEC §13.1). The gateway routes the host's ops ONLY when this
+     * resolves `true`. Must not throw; a failed probe resolves `false`.
+     */
+    ready(): Promise<boolean>;
+    /**
+     * Forward a single operation to the host runtime and return its result.
+     *
+     * The gateway wraps this in the deadline timer and cancellation wiring — the adapter
+     * receives `signal` so it can abort native work (HTTP abort / kill the in-flight IPC).
+     * The adapter MUST reject if the host process has died mid-call (the gateway maps that
+     * to `unavailable` and triggers supervision/restart).
+     */
+    invoke(req: HostRequest, signal: AbortSignal): Promise<unknown>;
+    /**
+     * Register a one-shot listener fired when the host process exits unexpectedly (crash).
+     * The gateway uses this to drive supervision/restart (SPEC §13.1). In-process adapters
+     * that cannot crash may install a no-op. Returns an unsubscribe function.
+     */
+    onExit(listener: (reason: unknown) => void): () => void;
+    /** Tear the host down gracefully (kill the sidecar / release resources). */
+    stop(): Promise<void>;
+}
+/**
+ * The runtime contract the in-process adapter calls — the TS harness's `invoke`, reduced
+ * to the cross-host-portable shape. The real `@adhd/apigen-ts-runtime` harness satisfies
+ * this; tests pass a plain function.
+ */
+export interface InProcessRuntime {
+    invoke(req: HostRequest, signal: AbortSignal): Promise<unknown>;
+}
+/**
+ * Create the in-process host adapter (SPEC §13.1 single-host fast path / zero hop).
+ *
+ * Wraps a same-process runtime so the gateway can treat the local TS host identically to
+ * a remote sidecar — but every call is a direct function invocation (`hopCost: 0`). An
+ * in-process runtime cannot "crash" the way a subprocess can, so `onExit` is a no-op and
+ * `ready()` returns the supplied readiness flag (default: ready once started).
+ */
+export declare function createInProcessHostAdapter(host: string, runtime: InProcessRuntime, opts?: {
+    readyWhenStarted?: boolean;
+}): HostAdapter;
+/**
+ * Backoff policy for restarting a crashed sidecar (SPEC §13.1 supervision).
+ * Exponential with a cap; the gateway sleeps `delayMs(attempt)` between restart attempts.
+ */
+export interface BackoffPolicy {
+    /** Delay before restart attempt `n` (1-based). */
+    delayMs(attempt: number): number;
+    /** Max consecutive restart attempts before the host is parked `down` (0 = unlimited). */
+    maxRestarts: number;
+}
+/** Default exponential backoff: 50ms · 2^(n-1), capped at 5s, unlimited restarts. */
+export declare const defaultBackoff: BackoffPolicy;
+/** Construction options for {@link createGateway}. */
+export interface GatewayOptions {
+    /** The host adapters to route to, keyed by `operation.host`. */
+    adapters: HostAdapter[];
+    /** Default per-call deadline in ms when the call carries no signal-derived deadline. */
+    defaultDeadlineMs?: number;
+    /** Restart-with-backoff policy for crashed sidecars (default: {@link defaultBackoff}). */
+    backoff?: BackoffPolicy;
+    /**
+     * Injectable timer hooks — let tests drive deadlines deterministically without wall
+     * clock. Defaults to real `setTimeout`/`clearTimeout`. (CLAUDE.md §6: deterministic,
+     * no `sleep`.)
+     */
+    timers?: {
+        setTimeout: (fn: () => void, ms: number) => unknown;
+        clearTimeout: (handle: unknown) => void;
+    };
+}
+/** Per-host snapshot in the aggregate `_meta/health` report (SPEC §13.1). */
+export interface HostHealth {
+    host: string;
+    status: HostStatus;
+    /** Routing cost in IPC hops (SPEC §13.1 cost function). */
+    hopCost: 0 | 1;
+    /** Consecutive crash-restart attempts since last healthy (supervision telemetry). */
+    restarts: number;
+}
+/** The gateway's aggregate `_meta/health` payload (SPEC §13.1: per-host status). */
+export interface GatewayHealth {
+    /** Per-host status, keyed by host tag. */
+    hosts: Record<string, HostHealth>;
+    /** True when at least one host is `ready` (the surface can serve something). */
+    serving: boolean;
+}
+/**
+ * The gateway surface presented to a transport adapter. The transport calls `route()`
+ * once per inbound request; the gateway picks the owning host and applies the full §13.1
+ * failure model around the adapter call.
+ */
+export interface Gateway {
+    /** Spawn + begin supervising every host. Resolves once all `start()` calls settle. */
+    start(): Promise<void>;
+    /**
+     * Route one operation to its owning host and return the result (SPEC §13).
+     * Applies readiness gating, deadline, cancellation and partial-availability mapping.
+     * @throws ApiError(`unavailable`) when the host is not serving.
+     * @throws ApiError(`deadline_exceeded`) when the deadline elapses.
+     */
+    route(req: HostRequest, signal?: AbortSignal): Promise<unknown>;
+    /** The aggregate `_meta/health` report (SPEC §13.1 per-host status). */
+    health(): Promise<GatewayHealth>;
+    /** The total routing cost (sum of hop costs) — drives topology selection (SPEC §13.1). */
+    topologyCost(): number;
+    /** Shut every host down and stop supervision. */
+    stop(): Promise<void>;
+}
+/**
+ * Create the sidecar gateway (SPEC §13 / §13.1).
+ *
+ * The gateway routes every operation to the host named by `operation.host`, applying the
+ * normative failure model:
+ *  - **partial availability** — an op for a `down`/`degraded` host throws `unavailable`;
+ *    other hosts keep serving (one host's failure never affects another's route).
+ *  - **readiness gating** — an op routes only when its host's `ready()` probe passed.
+ *  - **deadline** — each route is raced against its deadline → `deadline_exceeded`.
+ *  - **supervision** — a host's `onExit` triggers a restart-with-backoff loop; the
+ *    gateway process stays up and the host returns to `ready` after a successful restart.
+ */
+export declare function createGateway(opts: GatewayOptions): Gateway;

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@adhd/apigen-gateway",
+  "version": "0.1.0",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "dependencies": {
+    "@adhd/apigen-core": "^0.1.0",
+    "@adhd/apigen-errors": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}