@nanobpm/urban-agent-client 0.1.0

package/src/testkit.ts

@@ -0,0 +1,112 @@
+import { decodeFrame } from "./protocol.ts";
+import type { Frame } from "./protocol.ts";
+import type { Transport, TransportFactory, TransportHooks } from "./transport.ts";
+
+/**
+ * An in-memory transport double for exercising the client with no live hub. It
+ * records every frame the client sends, lets a test drive the connection
+ * lifecycle deterministically (open / deliver / drop / reopen), and can be
+ * pointed at by a {@link TransportFactory} so reconnects rebuild it.
+ */
+export class FakeTransport implements Transport {
+  readonly sent: Uint8Array[] = [];
+  open = false;
+  /**
+   * When true, {@link send} throws synchronously WITHOUT firing `onClose` — the
+   * minimum a transport is required to do per its contract. Models a channel
+   * that signals disconnect solely by throwing, which must still drive the
+   * client's reconnect path.
+   */
+  throwOnSend = false;
+  /**
+   * When true, {@link close} does NOT fire `onClose` — models a transport whose
+   * close is asynchronous (a real WebSocket fires its close event on a later
+   * tick) or one that never surfaces its own close. The client must still notify
+   * its own `onClose` subscribers on a caller-initiated shutdown.
+   */
+  silentClose = false;
+  private closedLocal = false;
+
+  private readonly hooks: TransportHooks;
+
+  constructor(hooks: TransportHooks) {
+    this.hooks = hooks;
+  }
+
+  /** Frames decoded from what the client sent, in send order. */
+  get sentFrames(): Frame[] {
+    return this.sent.map((bytes) => decodeFrame(bytes));
+  }
+
+  send(bytes: Uint8Array): void {
+    if (this.throwOnSend) {
+      throw new Error("fake transport send failure (no onClose)");
+    }
+    if (!this.open) {
+      throw new Error("fake transport not open");
+    }
+    this.sent.push(bytes);
+  }
+
+  close(): void {
+    this.closedLocal = true;
+    if (this.open) {
+      this.open = false;
+      if (!this.silentClose) {
+        this.hooks.onClose({ local: true });
+      }
+    }
+  }
+
+  /** Simulate the channel coming up. */
+  fireOpen(): void {
+    this.open = true;
+    this.hooks.onOpen();
+  }
+
+  /** Simulate a remote drop (hub outage / network loss). */
+  drop(info: { code?: number; reason?: string } = {}): void {
+    if (this.open) {
+      this.open = false;
+      this.hooks.onClose({ ...info, local: false });
+    }
+  }
+
+  /** Deliver a raw inbound frame to the client. */
+  deliver(bytes: Uint8Array): void {
+    this.hooks.onFrame(bytes);
+  }
+
+  wasClosedLocally(): boolean {
+    return this.closedLocal;
+  }
+}
+
+/**
+ * A {@link TransportFactory} that hands out {@link FakeTransport}s and records
+ * each one it builds, so a test can drive reconnects (the client calls the
+ * factory again on every reconnect attempt).
+ */
+export function fakeTransportFactory(): {
+  factory: TransportFactory;
+  transports: FakeTransport[];
+  last(): FakeTransport;
+} {
+  const transports: FakeTransport[] = [];
+  const factory: TransportFactory = (_url, hooks) => {
+    const transport = new FakeTransport(hooks);
+    transports.push(transport);
+    return transport;
+  };
+  return {
+    factory,
+    transports,
+    last: () => {
+      const transport = transports[transports.length - 1];
+      if (transport === undefined) {
+        throw new Error("fakeTransportFactory().last() called before any transport was created");
+      }
+      return transport;
+    },
+  };
+}

package/src/transport.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { deliverIncoming, normaliseIncoming, websocketTransport } from "./transport.ts";
+import type { TransportHooks } from "./transport.ts";
+
+test("normaliseIncoming accepts every binary shape a WebSocket may deliver", () => {
+  const bytes = new Uint8Array([1, 2, 3, 4]);
+
+  assert.deepEqual([...(normaliseIncoming(bytes) ?? [])], [1, 2, 3, 4]);
+  assert.deepEqual([...(normaliseIncoming(bytes.buffer) ?? [])], [1, 2, 3, 4]);
+
+  const view = new DataView(bytes.buffer, 1, 2);
+  assert.deepEqual([...(normaliseIncoming(view) ?? [])], [2, 3]);
+
+  const buffer = Buffer.from([9, 8, 7]);
+  assert.deepEqual([...(normaliseIncoming(buffer) ?? [])], [9, 8, 7]);
+});
+
+test("normaliseIncoming returns undefined for a text (non-binary) message", () => {
+  assert.equal(normaliseIncoming("hello"), undefined);
+  assert.equal(normaliseIncoming(42), undefined);
+  assert.equal(normaliseIncoming(null), undefined);
+});
+
+test("websocketTransport builds a Transport and refuses to send before the socket is open", () => {
+  const hooks: TransportHooks = {
+    onOpen: () => {},
+    onFrame: () => {},
+    onClose: () => {},
+    onError: () => {},
+  };
+
+  // Stub the global WebSocket with a socket that stays in CONNECTING, so the
+  // test is fully deterministic and performs no real network I/O (no dependency
+  // on the host stack / port timing). A send while CONNECTING must throw rather
+  // than silently drop the frame — that "throw, don't drop" contract is exactly
+  // what lets the client re-buffer instead of losing data.
+  class ConnectingWebSocket {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    readonly readyState = ConnectingWebSocket.CONNECTING;
+    binaryType = "blob";
+    addEventListener(): void {}
+    send(): void {}
+    close(): void {}
+  }
+  const original = Reflect.get(globalThis, "WebSocket");
+  Reflect.set(globalThis, "WebSocket", ConnectingWebSocket);
+  try {
+    const transport = websocketTransport("ws://stub/agentic", hooks);
+    assert.equal(typeof transport.send, "function");
+    assert.equal(typeof transport.close, "function");
+    assert.throws(() => transport.send(new Uint8Array([1])), /not open/);
+    transport.close();
+  } finally {
+    Reflect.set(globalThis, "WebSocket", original);
+  }
+});
+
+test("websocketTransport surfaces a non-binary inbound message via onError instead of dropping it", () => {
+  const frames: Uint8Array[] = [];
+  const errors: Error[] = [];
+  const hooks = {
+    onFrame: (bytes: Uint8Array) => frames.push(bytes),
+    onError: (error: Error) => errors.push(error),
+  };
+
+  // A binary frame is delivered to onFrame.
+  deliverIncoming(new Uint8Array([1, 2, 3]), hooks);
+  // A text frame is a protocol violation — surfaced via onError, not dropped.
+  deliverIncoming("not-binary", hooks);
+
+  assert.equal(frames.length, 1, "the binary frame reached onFrame");
+  assert.deepEqual([...(frames[0] ?? [])], [1, 2, 3]);
+  assert.equal(errors.length, 1, "the non-binary frame was surfaced via onError");
+  assert.match(errors[0]?.message ?? "", /non-binary message/);
+});

package/src/transport.ts

@@ -0,0 +1,123 @@
+/**
+ * The transport seam. The client is written against a minimal, injectable
+ * transport so it can be exercised without a live hub (hub-down tolerance is a
+ * first-class, unit-tested property) and so a host can supply any framing
+ * (a real WebSocket, an in-process pipe, a test double).
+ *
+ * A transport carries WHOLE encoded frames as binary messages — one
+ * {@link Uint8Array} in, one {@link Uint8Array} out. It never interprets the
+ * bytes; the client owns encode/decode via the S0 codec.
+ */
+
+export interface TransportHooks {
+  /** The channel is open and ready to send. */
+  onOpen(): void;
+  /** One binary frame arrived from the hub. */
+  onFrame(bytes: Uint8Array): void;
+  /** The channel closed (cleanly or otherwise). */
+  onClose(info: TransportCloseInfo): void;
+  /** A transport-level error occurred. Non-fatal on its own; a close follows. */
+  onError(error: Error): void;
+}
+
+export interface TransportCloseInfo {
+  readonly code?: number;
+  readonly reason?: string;
+  /** True when the close was requested by the client (a deregister / shutdown). */
+  readonly local?: boolean;
+}
+
+export interface Transport {
+  /**
+   * Send one encoded frame. Implementations MUST throw synchronously if the
+   * channel is not open, so the client can re-buffer the frame and stop
+   * draining until the next reconnect.
+   */
+  send(bytes: Uint8Array): void;
+  /** Close the channel. Idempotent. */
+  close(code?: number, reason?: string): void;
+}
+
+/**
+ * Builds a transport for a URL, wiring the hub's events into `hooks`. Called
+ * once per connection attempt (a reconnect calls it again).
+ */
+export type TransportFactory = (url: string, hooks: TransportHooks) => Transport;
+
+/**
+ * The default transport: a binary WebSocket over the app's bound port. Each
+ * agentic frame is one WebSocket binary message. Incoming messages are
+ * normalised to {@link Uint8Array} regardless of whether the runtime delivers
+ * an `ArrayBuffer`, a typed array, or a Node `Buffer`.
+ *
+ * Uses the global `WebSocket` (Node >= 22 provides one). A host on an older
+ * runtime, or one that wants a different framing, passes its own
+ * {@link TransportFactory} to `connectAgenticChannel`.
+ */
+export const websocketTransport: TransportFactory = (url, hooks) => {
+  if (typeof WebSocket !== "function") {
+    throw new Error(
+      "No global WebSocket is available. Run on Node >= 22.6 (which provides a global WebSocket) " +
+        "or pass a custom `transport` factory to connectAgenticChannel().",
+    );
+  }
+
+  const socket = new WebSocket(url);
+  socket.binaryType = "arraybuffer";
+  let localClose = false;
+
+  socket.addEventListener("open", () => hooks.onOpen());
+  socket.addEventListener("message", (event) => deliverIncoming(event.data, hooks));
+  socket.addEventListener("error", (event) => {
+    // Preserve the underlying error event as the cause so callers (tests,
+    // operational logs) can inspect the transport-level failure rather than
+    // only seeing a generic message.
+    hooks.onError(new Error("agentic channel transport error", { cause: event }));
+  });
+  socket.addEventListener("close", (event) => {
+    hooks.onClose({ code: event.code, reason: event.reason, local: localClose });
+  });
+
+  return {
+    send(bytes: Uint8Array): void {
+      if (socket.readyState !== WebSocket.OPEN) {
+        throw new Error("agentic channel is not open");
+      }
+      socket.send(bytes);
+    },
+    close(code?: number, reason?: string): void {
+      localClose = true;
+      socket.close(code, reason);
+    },
+  };
+};
+
+/**
+ * Route one inbound transport message: a binary frame goes to `onFrame`; a
+ * non-binary message (a protocol violation under the "one binary frame per
+ * message" contract) is surfaced via `onError` rather than silently dropped, so
+ * the client never hangs seeing no frames yet no error. This is the single
+ * source of truth for the transport's message-dispatch branch.
+ */
+export function deliverIncoming(data: unknown, hooks: Pick<TransportHooks, "onFrame" | "onError">): void {
+  const bytes = normaliseIncoming(data);
+  if (bytes !== undefined) {
+    hooks.onFrame(bytes);
+    return;
+  }
+  hooks.onError(new Error("agentic channel received a non-binary message; expected one binary frame per message"));
+}
+
+/** Normalise a WebSocket message payload to bytes, or `undefined` if it is text. */
+export function normaliseIncoming(data: unknown): Uint8Array | undefined {
+  if (data instanceof Uint8Array) {
+    return data;
+  }
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  return undefined;
+}