agent-comms 8.15.8 → 8.15.10

package/src/core/wire-protocol.ts

@@ -0,0 +1,153 @@
+/**
+ * Wire protocol — framing, encoding, and message types for the TCP mesh.
+ *
+ * Transport-agnostic: carries the protocol contract between peers without depending on net.Socket or any specific transport implementation. Any MeshTransport implementation (WireMeshTransport is the one production transport today) uses these types.
+ */
+
+import type {
+  AgentIdentity,
+  DeliveryEvent,
+  DmMessage,
+  Room,
+  RoomMessage,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Peer info
+// ---------------------------------------------------------------------------
+
+export interface PeerInfo {
+  id: string;
+  port: number;
+  startedAt: string;
+  /** The host this peer's data port listens on. Absent means the machine-local default (localhost): every peer a coordinator introduction or a same-machine first contact names needs no host, while a peer discovered on another machine (first-contact beacons, agent-comms#341) carries the address its beacon came from. */
+  host?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Serialised mesh state
+// ---------------------------------------------------------------------------
+
+export interface SerialisedState {
+  agents: Record<string, AgentIdentity>;
+  rooms: Record<string, Room>;
+  messages: Record<string, RoomMessage[]>;
+  dms: Record<string, DmMessage[]>;
+  /**
+   * Pending delivery events per target agent, replicated on every peer. A returning peer replays its own queue from the first snapshot it receives, so events pushed while its process was down still fire onDelivery (#28).
+   */
+  deliveryQueues: Record<string, DeliveryEvent[]>;
+}
+
+// ---------------------------------------------------------------------------
+// State patches (incremental updates)
+// ---------------------------------------------------------------------------
+
+export type MeshStatePatch =
+  | { type: "agent_upsert"; agent: AgentIdentity }
+  | { type: "agent_offline"; agentId: string }
+  | { type: "room_upsert"; room: Room }
+  | { type: "room_delete"; roomId: string }
+  | { type: "message_add"; roomId: string; message: RoomMessage }
+  | { type: "dm_add"; key: string; message: DmMessage }
+  | { type: "delivery"; agentId: string; event: DeliveryEvent };
+
+// ---------------------------------------------------------------------------
+// Wire message union
+// ---------------------------------------------------------------------------
+
+export type MeshMessage =
+  | { method: "state_sync"; state: SerialisedState }
+  | { method: "state_update"; patch: MeshStatePatch }
+  | { method: "introduce"; peerId: string; dataPort: number }
+  | {
+      method: "connect_request";
+      peerId: string;
+      dataPort: number;
+      name: string;
+      fingerprint: string;
+    }
+  | { method: "peer_list"; peers: PeerInfo[] }
+  | { method: "peer_joined"; peer: PeerInfo }
+  | { method: "peer_left"; peerId: string }
+  | { method: "become_coordinator"; peerList: PeerInfo[] };
+
+// ---------------------------------------------------------------------------
+// Framing — newline-delimited JSON
+// ---------------------------------------------------------------------------
+
+export function encode(msg: MeshMessage): string {
+  return JSON.stringify(msg) + "\n";
+}
+
+export class MessageBuffer {
+  private buffer = "";
+
+  append(data: string): unknown[] {
+    this.buffer += data;
+    const results: unknown[] = [];
+    let idx = this.buffer.indexOf("\n");
+    while (idx !== -1) {
+      const line = this.buffer.slice(0, idx);
+      this.buffer = this.buffer.slice(idx + 1);
+      if (line.length > 0) {
+        try {
+          results.push(JSON.parse(line));
+        } catch {
+          /* skip malformed lines */
+        }
+      }
+      idx = this.buffer.indexOf("\n");
+    }
+    return results;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Type guard
+// ---------------------------------------------------------------------------
+
+export function isMeshMessage(value: unknown): value is MeshMessage {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("method" in value)) return false;
+  return typeof value.method === "string";
+}
+
+// ---------------------------------------------------------------------------
+// Wire evolution tolerance (#31 direction 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * The shape a state_sync payload actually has on the wire: `SerialisedState` with every field that predates #29/#30 -- and each entity's `version` within those fields -- optional, since nothing validates this JSON.parse'd message beyond `isMeshMessage`'s bare `method` check. `SerialisedState` itself stays the fully-populated type domain logic works with elsewhere; this is deliberately narrower than `Partial<SerialisedState>` so it models only the specific absences an older build can actually produce.
+ */
+export interface WireStateInput {
+  agents?: Record<
+    string,
+    Omit<AgentIdentity, "version"> & { version?: number }
+  >;
+  rooms?: Record<string, Omit<Room, "version"> & { version?: number }>;
+  messages?: SerialisedState["messages"];
+  dms?: SerialisedState["dms"];
+  deliveryQueues?: SerialisedState["deliveryQueues"];
+}
+
+/**
+ * Normalises a state_sync payload at the wire boundary so a snapshot from an older build — one predating the entity `version` fields (#29) or `deliveryQueues` (#30) — parses to a complete state instead of throwing in `applyStateSync`. Missing collections default to empty; missing entity versions default to 1 (a pre-versioning sender's records are treated as fresh, which is what they were when written — there was no older format). The handshake (handshake.ts) is the loud, forward-looking half of the #31 fix; this is the tolerant half for peers that never negotiate.
+ */
+export function normaliseWireState(state: WireStateInput): SerialisedState {
+  const agents: Record<string, AgentIdentity> = {};
+  for (const [id, agent] of Object.entries(state.agents ?? {})) {
+    agents[id] = { ...agent, version: agent.version ?? 1 };
+  }
+  const rooms: Record<string, Room> = {};
+  for (const [id, room] of Object.entries(state.rooms ?? {})) {
+    rooms[id] = { ...room, version: room.version ?? 1 };
+  }
+  return {
+    agents,
+    rooms,
+    messages: state.messages ?? {},
+    dms: state.dms ?? {},
+    deliveryQueues: state.deliveryQueues ?? {},
+  };
+}

package/src/core/ws-dial.ts

@@ -0,0 +1,191 @@
+// A ws-library dial adapter for outbound remote connections to a WebSocket-served hub (e.g. the mesh.exadev.io cloudflare-hub, which answers wss:// only): one CBOR frame per binary WebSocket message, the identical framing wire-mesh-node's own WebSocket transport uses, so a hub sees the same bytes from this client as from any other. Agent-comms' own edge adapter rather than a wire-mesh-node dependency because wire-mesh-node is not published to npm as a consumable package (a placeholder 0.0.0), while the dial is genuinely this app's concern at its own edge -- the same layering its TLS transport adapter already occupies.
+
+import { WebSocket as WsSocket } from "ws";
+import { cdeDecodeOptions, cdeEncodeOptions, decode, encode } from "cbor2";
+import { frameSchema, type Frame } from "wire-mesh-core/generated/protocol";
+import type { Connection, Transport } from "wire-mesh-core/ports/transport";
+
+const CONNECT_TIMEOUT_MS = 10_000;
+// RFC 6455 close codes, named rather than bare: 1000 normal closure, 1002 protocol error.
+const CLOSE_NORMAL = 1000;
+const CLOSE_PROTOCOL_ERROR = 1002;
+
+/** Rejects addresses that are neither ws:// nor wss:// URLs -- a wrong-scheme dial would otherwise surface as an opaque socket error. */
+function assertWsUrl(url: string): void {
+  if (!/^wss?:\/\/./.test(url)) {
+    throw new Error(`expected a ws:// or wss:// URL, got "${url}"`);
+  }
+}
+
+export async function connectWsUrl(url: string): Promise<Connection> {
+  assertWsUrl(url);
+  return new Promise<Connection>((resolve, reject) => {
+    const socket = new WsSocket(url);
+    socket.binaryType = "arraybuffer";
+    const timer = setTimeout(() => {
+      socket.terminate();
+      reject(
+        new Error(
+          `ws dial timed out after ${String(CONNECT_TIMEOUT_MS)}ms: ${url}`,
+        ),
+      );
+    }, CONNECT_TIMEOUT_MS);
+    socket.once("open", () => {
+      clearTimeout(timer);
+      resolve(wrapWsSocket(socket));
+    });
+    socket.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error instanceof Error ? error : new Error(String(error)));
+    });
+  });
+}
+
+/** Wraps an open ws socket (dialled here, or accepted by a relay server with binaryType "arraybuffer") as a wire-mesh Connection: one canonical-CBOR frame per binary message. */
+export function wrapWsSocket(socket: WsSocket): Connection {
+  const pending: Frame[] = [];
+  const waiters: {
+    resolve: (result: IteratorResult<Frame>) => void;
+    reject: (error: unknown) => void;
+  }[] = [];
+  let ended = false;
+  let failure: Error | null = null;
+  // Set synchronously the instant close() is called, well before the socket's own readyState transitions are visible to a concurrent caller. Unlike `ended` (only true once the "close" event actually arrives, which a real close handshake delays), this flag exists purely so a send() invoked after close() has started is rejected with a clean, expected error immediately, rather than reaching socket.send() and hitting ws's own "WebSocket is not open: readyState 2 (CLOSING)" (agent-comms#304).
+  let closing = false;
+  // Every send() call still awaiting its own socket-level callback, so close() can let them settle before tearing the socket down instead of racing a send that was already under way when close() was called.
+  const pendingSends = new Set<Promise<void>>();
+
+  function endAll(): void {
+    ended = true;
+    for (const waiter of waiters.splice(0)) {
+      waiter.resolve({ value: undefined, done: true });
+    }
+  }
+
+  function failAll(error: Error): void {
+    failure = error;
+    ended = true;
+    for (const waiter of waiters.splice(0)) {
+      waiter.reject(error);
+    }
+  }
+
+  socket.on("message", (data) => {
+    if (!(data instanceof ArrayBuffer)) {
+      failAll(new Error("expected a binary WebSocket message"));
+      socket.close(CLOSE_PROTOCOL_ERROR, "protocol error");
+      return;
+    }
+    let frame: Frame;
+    try {
+      const decoded: unknown = decode(new Uint8Array(data), cdeDecodeOptions);
+      const parsed = frameSchema.safeParse(decoded);
+      if (!parsed.success) {
+        // A decodable-but-unrecognised frame is dropped, keeping the connection -- version negotiation exists to tolerate it.
+        return;
+      }
+      frame = parsed.data;
+    } catch (error) {
+      failAll(
+        error instanceof Error
+          ? error
+          : new Error(`frame body failed to decode: ${String(error)}`),
+      );
+      socket.close(CLOSE_PROTOCOL_ERROR, "protocol error");
+      return;
+    }
+    const waiter = waiters.shift();
+    if (waiter) {
+      waiter.resolve({ value: frame, done: false });
+    } else {
+      pending.push(frame);
+    }
+  });
+  socket.on("close", endAll);
+  socket.on("error", () => {
+    // The receive stream's failure signal; the raw error is not otherwise actionable here.
+  });
+
+  const receiveStream: AsyncIterable<Frame> = {
+    [Symbol.asyncIterator]() {
+      return {
+        async next(): Promise<IteratorResult<Frame>> {
+          const next = pending.shift();
+          if (next !== undefined) {
+            return { value: next, done: false };
+          }
+          if (failure !== null) {
+            throw failure;
+          }
+          if (ended) {
+            return { value: undefined, done: true };
+          }
+          return new Promise<IteratorResult<Frame>>((resolve, reject) => {
+            waiters.push({ resolve, reject });
+          });
+        },
+      };
+    },
+  };
+
+  return {
+    async send(frame: Frame): Promise<void> {
+      if (ended || closing) {
+        throw new Error("connection is closed");
+      }
+      const sent = new Promise<void>((resolve, reject) => {
+        socket.send(
+          new Uint8Array(encode(frame, cdeEncodeOptions)),
+          (error) => {
+            if (error) {
+              reject(error);
+            } else {
+              resolve();
+            }
+          },
+        );
+      });
+      // Tracked from the same synchronous tick socket.send() was actually called in, so a close() that starts a moment later always sees this send if it was genuinely already under way.
+      const tracked = sent.finally(() => {
+        pendingSends.delete(tracked);
+      });
+      pendingSends.add(tracked);
+      return tracked;
+    },
+    receive: () => receiveStream,
+    close: async () => {
+      // Reject anything sent from here on before it ever reaches the socket (the send() guard above), and let every send already in flight resolve or reject on its own terms first. Closing the socket out from under an in-flight send is what turns its own ordinary completion into a spurious "WebSocket is not open: readyState 2 (CLOSING)" (agent-comms#304).
+      closing = true;
+      await Promise.allSettled([...pendingSends]);
+      if (ended) return;
+      await new Promise<void>((resolve) => {
+        socket.once("close", () => {
+          resolve();
+        });
+        socket.close(CLOSE_NORMAL);
+      });
+    },
+  };
+}
+
+/** Dials a remote for connectToRemote: a ws:// or wss:// URL through connectWsUrl, anything else as host:port over the given transport. Split out of wire-mesh-transport.ts to keep it under the repo's max-lines cap. */
+export async function dialRemote(
+  wireTransport: Readonly<Transport>,
+  host: string,
+  port: number,
+): Promise<Connection> {
+  // A ws:// or wss:// URL in the host position dials a WebSocket-served
+  // hub (e.g. the mesh.exadev.io cloudflare-hub) instead of raw TLS --
+  // the port is meaningless in URL form, so callers pass 0. Any other URL
+  // scheme is refused here rather than surfacing as an opaque DNS error
+  // from the TLS dial treating the whole URL as a hostname.
+  const isWsUrl = /^wss?:\/\//.test(host);
+  if (!isWsUrl && host.includes("://")) {
+    throw new Error(
+      `expected a hostname or a ws:// / wss:// URL, got "${host}"`,
+    );
+  }
+  return isWsUrl
+    ? connectWsUrl(host)
+    : wireTransport.connect(`${host}:${String(port)}`);
+}