@nanobpm/agentic 0.1.0

package/src/channel/registry.ts

@@ -0,0 +1,137 @@
+/**
+ * The connection registry with liveness.
+ *
+ * S1 tracks every authenticated connection and its last-seen time; a connection
+ * not seen within the liveness TTL ages out on {@link ConnectionRegistry.sweep}.
+ * Presence detail (instance / declared capability / host / family) is left blank
+ * by S1 and filled in by the S2 register/heartbeat family module through
+ * {@link ConnectionRegistry.setPresence} — S1 owns liveness, S2 owns presence.
+ */
+import type { Capability } from "../protocol/index.ts";
+import { systemClock } from "./clock.ts";
+import type { Clock } from "./clock.ts";
+
+/** Presence attributes a family module (S2) attaches to a live connection. */
+export interface Presence {
+  /** The worker instance id declared on `register`. */
+  instance?: string;
+  /** The enrolment capability declared on `register` (never a routing token). */
+  capability?: Capability;
+}
+
+/** A tracked, authenticated connection. */
+export interface RegisteredConnection {
+  /** The connection id (matches {@link ChannelConnection.id}). */
+  readonly id: string;
+  /** The authenticated principal (ADR 0028 identity) from the handshake. */
+  readonly identity: string;
+  /** When the connection was accepted, in epoch ms. */
+  readonly connectedAt: number;
+  /** Last time any inbound frame or keepalive pong was seen, in epoch ms. */
+  lastSeen: number;
+  /** Presence detail, populated by the S2 family module (blank until then). */
+  presence: Presence;
+}
+
+export interface ConnectionRegistryOptions {
+  /** Liveness TTL in ms; a connection unseen for longer ages out. Default 30000. */
+  ttlMs?: number;
+  /** Injectable clock (deterministic tests). Default {@link systemClock}. */
+  clock?: Clock;
+}
+
+const DEFAULT_TTL_MS = 30_000;
+
+export class ConnectionRegistry {
+  readonly #byId = new Map<string, RegisteredConnection>();
+  readonly #ttlMs: number;
+  readonly #clock: Clock;
+
+  constructor(options: ConnectionRegistryOptions = {}) {
+    this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.#clock = options.clock ?? systemClock;
+  }
+
+  /** The liveness TTL in ms. */
+  get ttlMs(): number {
+    return this.#ttlMs;
+  }
+
+  /** Number of tracked connections. */
+  get size(): number {
+    return this.#byId.size;
+  }
+
+  /**
+   * Start tracking a newly authenticated connection. `connectedAt` and
+   * `lastSeen` are set to now; presence starts blank.
+   */
+  add(id: string, identity: string): RegisteredConnection {
+    const now = this.#clock.now();
+    const entry: RegisteredConnection = {
+      id,
+      identity,
+      connectedAt: now,
+      lastSeen: now,
+      presence: {},
+    };
+    this.#byId.set(id, entry);
+    return entry;
+  }
+
+  /** Update a connection's liveness to now. No-op if unknown. */
+  touch(id: string): void {
+    const entry = this.#byId.get(id);
+    if (entry !== undefined) {
+      entry.lastSeen = this.#clock.now();
+    }
+  }
+
+  /** Merge presence detail onto a tracked connection (used by S2). No-op if unknown. */
+  setPresence(id: string, patch: Presence): void {
+    const entry = this.#byId.get(id);
+    if (entry !== undefined) {
+      entry.presence = { ...entry.presence, ...patch };
+    }
+  }
+
+  /** Look up a tracked connection. */
+  get(id: string): RegisteredConnection | undefined {
+    return this.#byId.get(id);
+  }
+
+  /** Whether a connection is tracked. */
+  has(id: string): boolean {
+    return this.#byId.has(id);
+  }
+
+  /** Stop tracking a connection, returning the removed entry if present. */
+  remove(id: string): RegisteredConnection | undefined {
+    const entry = this.#byId.get(id);
+    this.#byId.delete(id);
+    return entry;
+  }
+
+  /** All tracked connections, in insertion order. */
+  list(): RegisteredConnection[] {
+    return [...this.#byId.values()];
+  }
+
+  /**
+   * Age out every connection whose last-seen time is older than the TTL and
+   * return the removed entries, so the hub can close their sockets. `now`
+   * defaults to the clock; pass an explicit value for deterministic tests.
+   */
+  sweep(now: number = this.#clock.now()): RegisteredConnection[] {
+    const stale: RegisteredConnection[] = [];
+    for (const entry of this.#byId.values()) {
+      if (now - entry.lastSeen > this.#ttlMs) {
+        stale.push(entry);
+      }
+    }
+    for (const entry of stale) {
+      this.#byId.delete(entry.id);
+    }
+    return stale;
+  }
+}

package/src/channel/ws-transport.test.ts

@@ -0,0 +1,234 @@
+import assert from "node:assert/strict";
+import { once } from "node:events";
+import { createServer } from "node:http";
+import { test } from "node:test";
+import { encodeFrame } from "../protocol/index.ts";
+import type { Frame } from "../protocol/index.ts";
+import { WebSocket } from "ws";
+import { AUTH_UNAUTHORIZED, sharedSecretAuthenticator } from "./auth.ts";
+import { AgenticHub } from "./hub.ts";
+import type { HubConnection } from "./hub.ts";
+import { WebSocketChannelTransport } from "./ws-transport.ts";
+
+const SECRET = "s3cret";
+
+function registerBytes(instance: string): Uint8Array {
+  const frame: Frame = {
+    lane: "control",
+    family: "register",
+    seq: 1,
+    payload: { instance, capability: { cognition: "opus" } },
+  };
+  return encodeFrame(frame);
+}
+
+test("a client connects, authenticates, is tracked, and its frame routes to a family handler", async (t) => {
+  const transport = new WebSocketChannelTransport({ port: 0 });
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: SECRET }),
+    sweepIntervalMs: 0,
+  });
+  t.after(() => hub.close());
+
+  let resolveRouted: (conn: HubConnection) => void = () => {};
+  const routed = new Promise<HubConnection>((resolve) => {
+    resolveRouted = resolve;
+  });
+  hub.registerFamilyHandler("register", (_frame, ctx) => {
+    ctx.registry.setPresence(ctx.id, { instance: "w-1" });
+    resolveRouted(ctx);
+  });
+
+  await transport.ready();
+  const port = transport.address?.port;
+  assert.ok(port !== undefined && port > 0);
+
+  const client = new WebSocket(`ws://127.0.0.1:${port}/agentic?token=${SECRET}&capability=cap-1`);
+  client.on("error", () => {});
+  t.after(() => client.close());
+  await once(client, "open");
+  client.send(registerBytes("w-1"), { binary: true });
+
+  const ctx = await routed;
+  assert.ok(ctx.identity.length > 0); // resolved from the peer's remote address
+  assert.equal(hub.connectionCount, 1);
+  assert.equal(hub.registry.get(ctx.id)?.presence.instance, "w-1");
+});
+
+test("a client may present its capability credential via a mixed-case header", async (t) => {
+  const transport = new WebSocketChannelTransport({ port: 0 });
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: SECRET }),
+    sweepIntervalMs: 0,
+  });
+  t.after(() => hub.close());
+
+  let resolveRouted: (conn: HubConnection) => void = () => {};
+  const routed = new Promise<HubConnection>((resolve) => {
+    resolveRouted = resolve;
+  });
+  hub.registerFamilyHandler("register", (_frame, ctx) => resolveRouted(ctx));
+
+  await transport.ready();
+  const port = transport.address?.port;
+  assert.ok(port !== undefined && port > 0);
+
+  // Credential arrives only in a mixed-case header (no `capability` query param);
+  // header lookup must be case-insensitive for the handshake to grant.
+  const client = new WebSocket(`ws://127.0.0.1:${port}/agentic?token=${SECRET}`, {
+    headers: { "X-Capability-Credential": "cap-1" },
+  });
+  client.on("error", () => {});
+  t.after(() => client.close());
+  await once(client, "open");
+  client.send(registerBytes("w-1"), { binary: true });
+
+  const ctx = await routed;
+  // Reaching the family handler proves the required credential was found via the
+  // header (a case-sensitive lookup would have rejected with AUTH_FORBIDDEN).
+  assert.ok(ctx.identity.length > 0);
+  assert.equal(hub.connectionCount, 1);
+});
+
+test("an unauthenticated client is closed with the unauthorized code and never tracked", async (t) => {
+  const transport = new WebSocketChannelTransport({ port: 0 });
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: SECRET }),
+    sweepIntervalMs: 0,
+  });
+  t.after(() => hub.close());
+
+  await transport.ready();
+  const port = transport.address?.port;
+  const client = new WebSocket(`ws://127.0.0.1:${port}/agentic?token=wrong&capability=cap-1`);
+  client.on("error", () => {});
+
+  const [code] = await once(client, "close");
+  assert.equal(code, AUTH_UNAUTHORIZED);
+  assert.equal(hub.connectionCount, 0);
+});
+
+test("the hub replies on the same connection", async (t) => {
+  const transport = new WebSocketChannelTransport({ port: 0 });
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: SECRET }),
+    sweepIntervalMs: 0,
+  });
+  t.after(() => hub.close());
+
+  hub.registerFamilyHandler("register", (_frame, ctx) => {
+    ctx.send({ lane: "control", family: "serve", seq: 1, payload: { instance: "w-1", tokens: [] } });
+  });
+
+  await transport.ready();
+  const port = transport.address?.port;
+  const client = new WebSocket(`ws://127.0.0.1:${port}/agentic?token=${SECRET}&capability=cap-1`);
+  client.on("error", () => {});
+  t.after(() => client.close());
+  await once(client, "open");
+  client.send(registerBytes("w-1"), { binary: true });
+
+  const [data] = await once(client, "message");
+  assert.ok(data instanceof Buffer);
+  assert.ok(data.length > 0);
+});
+
+test("a text frame is rejected with 1003 and never reaches the codec", async (t) => {
+  // The protocol is binary-only. Pre-fix, `onMessage` called `toBytes` on the
+  // string payload of a text frame — which throws (no `.buffer`) and breaks the
+  // connection handler. The transport must instead close the socket with 1003.
+  const transport = new WebSocketChannelTransport({ port: 0 });
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: SECRET }),
+    sweepIntervalMs: 0,
+  });
+  t.after(() => hub.close());
+
+  let sawFrame = false;
+  hub.registerFamilyHandler("register", () => {
+    sawFrame = true;
+  });
+
+  await transport.ready();
+  const port = transport.address?.port;
+  const client = new WebSocket(`ws://127.0.0.1:${port}/agentic?token=${SECRET}&capability=cap-1`);
+  client.on("error", () => {});
+  t.after(() => client.close());
+  await once(client, "open");
+
+  // Send a TEXT frame (binary:false) — the transport must reject it.
+  client.send("not-a-binary-frame", { binary: false });
+
+  const [code] = await once(client, "close");
+  assert.equal(code, 1003);
+  assert.equal(sawFrame, false); // no text payload ever reached a family handler
+});
+
+test("ready() resolves in shared-port mode when attached to an app HTTP server", async (t) => {
+  // `ws` never emits `listening` on the WebSocketServer when it shares an
+  // existing HTTP server, so ready() must observe the HTTP server instead —
+  // otherwise it hangs forever. This test would time out without that fix.
+  const server = createServer();
+  const transport = new WebSocketChannelTransport({ server });
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: SECRET }),
+    sweepIntervalMs: 0,
+  });
+  t.after(() => hub.close());
+  t.after(() => new Promise<void>((resolve) => server.close(() => resolve())));
+
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+
+  // ready() must resolve now that the shared HTTP server is listening.
+  await transport.ready();
+
+  const addr = server.address();
+  assert.ok(addr !== null && typeof addr === "object");
+  const port = addr.port;
+
+  hub.registerFamilyHandler("register", (_frame, ctx) => {
+    ctx.send({ lane: "control", family: "serve", seq: 1, payload: { instance: "w-1", tokens: [] } });
+  });
+
+  const client = new WebSocket(`ws://127.0.0.1:${port}/agentic?token=${SECRET}&capability=cap-1`);
+  client.on("error", () => {});
+  t.after(() => client.close());
+  await once(client, "open");
+  client.send(registerBytes("w-1"), { binary: true });
+
+  const [data] = await once(client, "message");
+  assert.ok(data instanceof Buffer);
+  assert.ok(data.length > 0);
+});
+test("close() shuts a connected peer down with a clean close handshake, not an abnormal 1006", async (t) => {
+  // terminate() aborts without a handshake, so peers observe 1006 (abnormal) and
+  // lose any application close code/reason. A graceful close lets them observe a
+  // normal closure during shutdown.
+  const transport = new WebSocketChannelTransport({ port: 0 });
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: SECRET }),
+    sweepIntervalMs: 0,
+  });
+
+  await transport.ready();
+  const port = transport.address?.port;
+  assert.ok(port !== undefined && port > 0);
+
+  const client = new WebSocket(`ws://127.0.0.1:${port}/agentic?token=${SECRET}&capability=cap-1`);
+  client.on("error", () => {});
+  t.after(() => client.close());
+  await once(client, "open");
+
+  const closed = once(client, "close");
+  await transport.close();
+  const [code] = await closed;
+  assert.notEqual(code, 1006); // not an abnormal closure
+});

package/src/channel/ws-transport.ts

@@ -0,0 +1,212 @@
+/**
+ * The production WebSocket transport for the agentic hub.
+ *
+ * A thin adapter over the `ws` server that binds the app's OWN port (or attaches
+ * to an existing app HTTP server so it shares that port), captures the ADR 0028
+ * identity token + capability credential from the upgrade request, and hands the
+ * hub a transport-agnostic {@link ChannelConnection} per peer. The Camunda-8
+ * engine transport is a separate connection and is never touched here.
+ */
+import { randomUUID } from "node:crypto";
+import type { IncomingMessage, Server as HttpServer } from "node:http";
+import { WebSocketServer } from "ws";
+import type { RawData, WebSocket } from "ws";
+import type { ChannelConnection, ChannelTransport, CloseCode, HandshakeRequest } from "./connection.ts";
+
+export interface WebSocketChannelTransportOptions {
+  /** Port to bind (the app's own port). Use 0 for an ephemeral port. Ignored if `server` is set. */
+  port?: number;
+  /** Host/interface to bind. Ignored if `server` is set. */
+  host?: string;
+  /** Path the channel is served on. Default `/agentic`. */
+  path?: string;
+  /** Attach to an existing app HTTP server (share the app's port) instead of binding a new one. */
+  server?: HttpServer;
+}
+
+const DEFAULT_PATH = "/agentic";
+
+/** RFC 6455 close code for a frame whose type the endpoint cannot accept. */
+const CLOSE_UNSUPPORTED_DATA = 1003;
+
+/**
+ * Grace period for the shutdown close handshake before a still-open peer is
+ * force-terminated, so `close()` stays bounded even if a peer stalls.
+ */
+const GRACEFUL_CLOSE_TIMEOUT_MS = 250;
+
+/** Normalise Node's header map to a flat, lower-cased string record. */
+function flattenHeaders(req: IncomingMessage): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(req.headers)) {
+    const name = key.toLowerCase();
+    if (typeof value === "string") {
+      headers[name] = value;
+    } else if (Array.isArray(value)) {
+      headers[name] = value.join(", ");
+    }
+  }
+  return headers;
+}
+
+/** Parse the upgrade request into the handshake the authenticator reads. */
+function handshakeFrom(req: IncomingMessage): HandshakeRequest {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const query: Record<string, string> = {};
+  for (const [key, value] of url.searchParams) {
+    query[key] = value;
+  }
+  const headers = flattenHeaders(req);
+  return {
+    token: query.token,
+    credential: query.capability ?? headers["x-capability-credential"],
+    remote: req.socket.remoteAddress ?? undefined,
+    headers,
+    query,
+  };
+}
+
+/** Coerce `ws` RawData into a single contiguous byte view for the codec. */
+function toBytes(data: RawData): Uint8Array {
+  if (Array.isArray(data)) {
+    return Buffer.concat(data);
+  }
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+
+/** One `ws` socket wrapped as a {@link ChannelConnection}. */
+class WsConnection implements ChannelConnection {
+  readonly id: string;
+  readonly handshake: HandshakeRequest;
+  readonly #ws: WebSocket;
+
+  constructor(id: string, ws: WebSocket, handshake: HandshakeRequest) {
+    this.id = id;
+    this.#ws = ws;
+    this.handshake = handshake;
+  }
+
+  send(bytes: Uint8Array): void {
+    if (this.#ws.readyState === this.#ws.OPEN) {
+      this.#ws.send(bytes, { binary: true });
+    }
+  }
+
+  close(code?: CloseCode, reason?: string): void {
+    if (code === undefined) {
+      this.#ws.close();
+    } else {
+      this.#ws.close(code, reason);
+    }
+  }
+
+  onMessage(listener: (bytes: Uint8Array) => void): void {
+    this.#ws.on("message", (data: RawData, isBinary: boolean) => {
+      // The channel protocol is binary-only. A text frame (`isBinary === false`,
+      // which `ws` may deliver as a `string` with no `.buffer`) is a protocol
+      // violation: reject it with 1003 rather than letting `toBytes` throw.
+      if (!isBinary) {
+        this.#ws.close(CLOSE_UNSUPPORTED_DATA, "binary frames only");
+        return;
+      }
+      listener(toBytes(data));
+    });
+  }
+
+  onClose(listener: (code?: CloseCode, reason?: string) => void): void {
+    this.#ws.on("close", (code: number, reason: Buffer) => listener(code, reason.toString()));
+  }
+
+  onPong(listener: () => void): void {
+    this.#ws.on("pong", () => listener());
+  }
+
+  onPing(listener: () => void): void {
+    this.#ws.on("ping", () => listener());
+  }
+
+  ping(): void {
+    if (this.#ws.readyState === this.#ws.OPEN) {
+      this.#ws.ping();
+    }
+  }
+}
+
+export class WebSocketChannelTransport implements ChannelTransport {
+  readonly #wss: WebSocketServer;
+  readonly #server: HttpServer | undefined;
+  #listener: ((conn: ChannelConnection) => void) | undefined;
+
+  constructor(options: WebSocketChannelTransportOptions = {}) {
+    const path = options.path ?? DEFAULT_PATH;
+    this.#server = options.server;
+    this.#wss = options.server
+      ? new WebSocketServer({ server: options.server, path })
+      : new WebSocketServer({ port: options.port ?? 0, host: options.host, path });
+
+    this.#wss.on("connection", (ws: WebSocket, req: IncomingMessage) => {
+      const conn = new WsConnection(randomUUID(), ws, handshakeFrom(req));
+      this.#listener?.(conn);
+    });
+  }
+
+  onConnection(listener: (conn: ChannelConnection) => void): void {
+    this.#listener = listener;
+  }
+
+  /** Resolve once the server is listening on its port. */
+  ready(): Promise<void> {
+    // In shared-port mode the app owns the HTTP server: `ws` never emits
+    // `listening` on the WebSocketServer, so wait on the HTTP server instead
+    // (or resolve at once if it is already listening) to avoid hanging forever.
+    const source = this.#server ?? this.#wss;
+    if (this.#server ? this.#server.listening : this.#wss.address() !== null) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const onListening = () => {
+        source.off("error", onError);
+        resolve();
+      };
+      const onError = (err: Error) => {
+        source.off("listening", onListening);
+        reject(err);
+      };
+      source.once("listening", onListening);
+      source.once("error", onError);
+    });
+  }
+
+  get address(): { readonly port: number } | null {
+    const addr = this.#wss.address();
+    if (addr !== null && typeof addr === "object" && "port" in addr) {
+      return { port: addr.port };
+    }
+    return null;
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Prefer a graceful close handshake so peers observe a normal closure
+      // (with any application close code/reason) instead of an abnormal 1006.
+      // Fall back to terminate() for any peer that doesn't complete the
+      // handshake promptly, keeping shutdown bounded and deterministic.
+      for (const client of this.#wss.clients) {
+        client.close();
+      }
+      const fallback = setTimeout(() => {
+        for (const client of this.#wss.clients) {
+          client.terminate();
+        }
+      }, GRACEFUL_CLOSE_TIMEOUT_MS);
+      fallback.unref?.();
+      this.#wss.close((err) => {
+        clearTimeout(fallback);
+        err ? reject(err) : resolve();
+      });
+    });
+  }
+}