agent-comms 1.28.0 → 1.29.0

package/dist/core/tcp-transport.js

@@ -1,659 +0,0 @@
-/**
- * TcpTransport — TCP localhost transport for the peer mesh.
- *
- * Owns all net.Server and net.Socket instances. Handles connection
- * establishment, framing, and message routing. Fires events via
- * TransportEvents for MeshStore to handle state management.
- *
- * Lifecycle mirrors the MeshTransport interface:
- *   1. startDataServer() — listen for incoming peer data connections
- *   2. connectToCoordinator() — join an existing mesh
- *      OR becomeCoordinator() — start a new mesh as coordinator
- *   3. connectToPeer() — establish data connection to a discovered peer
- *   4. send() / broadcast() — send wire messages
- *   5. shutdown() — close all connections and servers
- */
-import * as net from "node:net";
-import { encode, isMeshMessage, MessageBuffer } from "./wire-protocol.js";
-import { attachSocketHandshake } from "./handshake.js";
-import { nanoid } from "./nanoid.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/** Host all mesh servers bind to. */
-const COORDINATOR_HOST = "127.0.0.1";
-/** Timeout for connecting to the coordinator before giving up. */
-const CONNECT_TIMEOUT_MS = 1000;
-// ---------------------------------------------------------------------------
-// Async socket write helper (not exported)
-// ---------------------------------------------------------------------------
-/**
- * Safety valve so a dial that never completes cannot grow its outbound queue
- * unbounded; oldest entries are dropped first (#23).
- */
-const MAX_PENDING_PER_PEER = 100;
-function writeAsync(socket, data) {
-    return new Promise((resolve, reject) => {
-        if (socket.destroyed) {
-            resolve();
-            return;
-        }
-        socket.write(data, "utf-8", (err) => {
-            if (err)
-                reject(err);
-            else
-                resolve();
-        });
-    });
-}
-// ---------------------------------------------------------------------------
-// TcpTransport
-// ---------------------------------------------------------------------------
-export class TcpTransport {
-    // -- Data server (accepts incoming peer data connections) --
-    dataServer;
-    _dataPort = 0;
-    // -- Coordinator listeners (multiple adapters) --
-    coordinatorListeners = new Map();
-    /** The default localhost listener ID (set once during becomeCoordinator). */
-    defaultListenerId;
-    _isCoordinator = false;
-    // -- Coordinator client socket (connection to the coordinator) --
-    coordinatorSocket;
-    // -- Coordinator introduction handshake (resolved on the peer list) --
-    resolveCoordinatorHandshake;
-    coordinatorHandshakeTimer;
-    // -- Peer data connections (peer ID → socket + buffer) --
-    peerConnections = new Map();
-    // -- Messages queued for peers whose dial is still in flight (#23) --
-    pendingOutbound = new Map();
-    // -- All sockets accepted by the data server (for shutdown cleanup) --
-    dataServerSockets = new Set();
-    // -- All sockets accepted by coordinator servers (for shutdown cleanup) --
-    coordinatorServerSockets = new Set();
-    // -- Coordinator introduction connections (handle ID → socket) --
-    // Maps the introducing peer's ID to the coordinator server socket, so
-    // MeshStore can send the peer_list response via transport.send().
-    introConnections = new Map();
-    // -- Pending connections awaiting approval (handle ID → socket + request info) --
-    pendingConnections = new Map();
-    // -- Shutdown sentinel — prevents callbacks after shutdown() --
-    shutDown = false;
-    // -- This peer's ID (set during connectToCoordinator or becomeCoordinator) --
-    _peerId = "";
-    events;
-    constructor(events) {
-        this.events = events;
-    }
-    // -- Public getters for interface properties --
-    get dataPort() {
-        return this._dataPort;
-    }
-    get isCoordinator() {
-        return this._isCoordinator;
-    }
-    get hasCoordinatorConnection() {
-        return (this.coordinatorSocket !== undefined && !this.coordinatorSocket.destroyed);
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Data server
-    // -----------------------------------------------------------------------
-    async startDataServer() {
-        await new Promise((resolve, reject) => {
-            this.dataServer = net.createServer((socket) => {
-                this.handleIncomingDataConnection(socket);
-            });
-            this.dataServer.listen(0, COORDINATOR_HOST, () => {
-                const addr = this.dataServer?.address();
-                if (typeof addr === "object" && addr !== null) {
-                    this._dataPort = addr.port;
-                }
-                resolve();
-            });
-            this.dataServer.on("error", reject);
-        });
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Coordinator connection (client side)
-    // -----------------------------------------------------------------------
-    async connectToCoordinator(host, port, peerId, localDataPort) {
-        this._peerId = peerId;
-        await new Promise((resolve, reject) => {
-            const socket = net.createConnection({ port, host }, () => {
-                this.coordinatorSocket = socket;
-                // Wire up the protocol handshake first (client role: sends its frame immediately as the connection's very first bytes) so the introduction below lands after it on the wire, not before.
-                const buffer = new MessageBuffer();
-                attachSocketHandshake(socket, "client", (data) => {
-                    const items = buffer.append(data.toString());
-                    for (const item of items) {
-                        if (isMeshMessage(item)) {
-                            this.dispatchCoordinatorClientMessage(item);
-                        }
-                    }
-                }, (error) => this.events.onError?.(error));
-                // Send introduction
-                const intro = {
-                    method: "introduce",
-                    peerId,
-                    dataPort: localDataPort,
-                };
-                socket.write(encode(intro));
-                socket.on("error", () => {
-                    /* ignore late errors on coordinator connection */
-                });
-                clearTimeout(timer);
-                // Resolve on the coordinator's peer list rather than on sending the
-                // introduction: MeshStore.init() then returns only after the post-join
-                // peer dials have started, so the first broadcasts are queued for the
-                // dialling peers instead of dropped (#23). A timeout keeps today's
-                // degraded behaviour for a coordinator that never answers.
-                this.resolveCoordinatorHandshake = resolve;
-                this.coordinatorHandshakeTimer = setTimeout(() => {
-                    this.resolveCoordinatorHandshake = undefined;
-                    resolve();
-                }, CONNECT_TIMEOUT_MS);
-            });
-            const timer = setTimeout(() => {
-                socket.destroy();
-                reject(new Error("Coordinator connection timeout"));
-            }, CONNECT_TIMEOUT_MS);
-            socket.on("error", (err) => {
-                clearTimeout(timer);
-                socket.destroy();
-                reject(err);
-            });
-        });
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Connect to remote coordinator with approval
-    // -----------------------------------------------------------------------
-    async connectToRemote(host, port, peerId, localDataPort, name, fingerprint) {
-        this._peerId = peerId;
-        await new Promise((resolve, reject) => {
-            const socket = net.createConnection({ port, host }, () => {
-                this.coordinatorSocket = socket;
-                // Wire up the protocol handshake first (client role) so connect_request below lands after it on the wire, pending: wait for connect_accepted/rejected, then normal dispatch
-                const buffer = new MessageBuffer();
-                let approved = false;
-                attachSocketHandshake(socket, "client", (data) => {
-                    const items = buffer.append(data.toString());
-                    for (const item of items) {
-                        if (!isMeshMessage(item))
-                            continue;
-                        if (!approved) {
-                            if (item.method === "connect_accepted") {
-                                approved = true;
-                                resolve();
-                            }
-                            else if (item.method === "connect_rejected") {
-                                socket.destroy();
-                                reject(new Error(`Connection rejected: ${item.reason}`));
-                                return;
-                            }
-                        }
-                        else {
-                            this.dispatchCoordinatorClientMessage(item);
-                        }
-                    }
-                }, (error) => this.events.onError?.(error));
-                // Send connect_request instead of introduce
-                const req = {
-                    method: "connect_request",
-                    peerId,
-                    dataPort: localDataPort,
-                    name,
-                    fingerprint,
-                };
-                socket.write(encode(req));
-                socket.on("error", () => {
-                    /* ignore late errors on coordinator connection */
-                });
-            });
-            const timer = setTimeout(() => {
-                socket.destroy();
-                reject(new Error("Remote connection timeout"));
-            }, CONNECT_TIMEOUT_MS);
-            socket.on("error", (err) => {
-                clearTimeout(timer);
-                socket.destroy();
-                reject(err);
-            });
-        });
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Become coordinator (server side)
-    // -----------------------------------------------------------------------
-    async becomeCoordinator(host, port) {
-        const id = nanoid(8);
-        await new Promise((resolve, reject) => {
-            const server = net.createServer((socket) => {
-                this.handleCoordinatorServerConnection(socket, "full");
-            });
-            server.listen(port, host, () => {
-                const addr = server.address();
-                const actualPort = typeof addr === "object" && addr !== null ? addr.port : port;
-                this._isCoordinator = true;
-                this.coordinatorListeners.set(id, {
-                    server,
-                    policy: "full",
-                    host,
-                    port: actualPort,
-                    isDefault: true,
-                });
-                this.defaultListenerId = id;
-                resolve();
-            });
-            server.on("error", (err) => {
-                reject(err instanceof Error ? err : new Error(String(err)));
-            });
-        });
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Multi-listener management
-    // -----------------------------------------------------------------------
-    async addListener(host, port, policy) {
-        if (!this._isCoordinator) {
-            throw new Error("Only the coordinator can add listeners");
-        }
-        const id = nanoid(8);
-        await new Promise((resolve, reject) => {
-            const server = net.createServer((socket) => {
-                this.handleCoordinatorServerConnection(socket, policy);
-            });
-            server.listen(port, host, () => {
-                const addr = server.address();
-                const actualPort = typeof addr === "object" && addr !== null ? addr.port : port;
-                this.coordinatorListeners.set(id, {
-                    server,
-                    policy,
-                    host,
-                    port: actualPort,
-                    isDefault: false,
-                });
-                resolve();
-            });
-            server.on("error", (err) => {
-                reject(err instanceof Error ? err : new Error(String(err)));
-            });
-        });
-        return id;
-    }
-    removeListener(id) {
-        const listener = this.coordinatorListeners.get(id);
-        if (!listener) {
-            throw new Error(`Listener ${id} not found`);
-        }
-        if (listener.isDefault) {
-            throw new Error("Cannot remove the default localhost listener");
-        }
-        listener.server.unref();
-        listener.server.close();
-        this.coordinatorListeners.delete(id);
-        return Promise.resolve();
-    }
-    listListeners() {
-        const result = [];
-        for (const [id, listener] of this.coordinatorListeners) {
-            result.push({
-                id,
-                host: listener.host,
-                port: listener.port,
-                policy: listener.policy,
-                isDefault: listener.isDefault,
-            });
-        }
-        return result;
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Connect to a peer's data server
-    // -----------------------------------------------------------------------
-    async connectToPeer(peer, ownPeerId) {
-        if (this.peerConnections.has(peer.id))
-            return;
-        // Queue broadcasts until the connection registers: messages sent in the
-        // dial window previously had nowhere to go and were silently dropped.
-        this.pendingOutbound.set(peer.id, this.pendingOutbound.get(peer.id) ?? []);
-        await new Promise((resolve) => {
-            const socket = net.createConnection({ port: peer.port, host: COORDINATOR_HOST }, () => {
-                const buffer = new MessageBuffer();
-                this.peerConnections.set(peer.id, { socket, buffer });
-                // Wire up the protocol handshake first (client role) so everything below lands after it on the wire, not before.
-                attachSocketHandshake(socket, "client", (data) => {
-                    const items = buffer.append(data.toString());
-                    for (const item of items) {
-                        if (isMeshMessage(item)) {
-                            const handle = { id: peer.id };
-                            this.dispatchDataMessage(handle, item);
-                        }
-                    }
-                }, (error) => this.events.onError?.(error));
-                // Identify ourselves
-                const pong = { method: "pong", peerId: ownPeerId };
-                socket.write(encode(pong));
-                void this.flushPending(peer.id, socket);
-                resolve();
-            });
-            const handle = { id: peer.id };
-            let disconnected = false;
-            const onDisconnect = () => {
-                if (disconnected)
-                    return;
-                disconnected = true;
-                const wasConnected = this.peerConnections.has(peer.id);
-                this.peerConnections.delete(peer.id);
-                if (wasConnected && !this.shutDown) {
-                    this.events.onPeerDisconnected(handle);
-                }
-            };
-            socket.on("close", onDisconnect);
-            socket.on("error", () => {
-                this.pendingOutbound.delete(peer.id);
-                onDisconnect();
-                socket.destroy();
-                resolve();
-            });
-        });
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Send / broadcast
-    // -----------------------------------------------------------------------
-    async send(handle, message) {
-        // Check data connections first
-        const peerConn = this.peerConnections.get(handle.id);
-        if (peerConn) {
-            await writeAsync(peerConn.socket, encode(message));
-            return;
-        }
-        // Check coordinator introduction connections
-        const introSocket = this.introConnections.get(handle.id);
-        if (introSocket) {
-            await writeAsync(introSocket, encode(message));
-            return;
-        }
-        throw new Error(`No connection for handle ${handle.id}`);
-    }
-    async acceptConnection(handle) {
-        const pending = this.pendingConnections.get(handle.id);
-        if (!pending) {
-            throw new Error(`No pending connection for handle ${handle.id}`);
-        }
-        this.pendingConnections.delete(handle.id);
-        const { socket, peerId, dataPort, policy } = pending;
-        // Move to introConnections so send() can reach this peer
-        this.introConnections.set(peerId, socket);
-        // Send acceptance to the connecting peer
-        const accepted = {
-            method: "connect_accepted",
-            peerId: this._peerId,
-            dataPort: this._dataPort,
-        };
-        await writeAsync(socket, encode(accepted));
-        // Fire onIntroduction so MeshStore processes the new peer normally
-        const connHandle = { id: peerId, policy };
-        this.events.onIntroduction(connHandle, { peerId, dataPort });
-    }
-    async rejectConnection(handle, reason) {
-        const pending = this.pendingConnections.get(handle.id);
-        if (!pending) {
-            throw new Error(`No pending connection for handle ${handle.id}`);
-        }
-        this.pendingConnections.delete(handle.id);
-        const { socket } = pending;
-        const rejected = {
-            method: "connect_rejected",
-            peerId: handle.id,
-            reason,
-        };
-        await writeAsync(socket, encode(rejected));
-        socket.destroy();
-    }
-    async broadcast(message) {
-        const data = encode(message);
-        const writes = [];
-        for (const [, peer] of this.peerConnections) {
-            writes.push(writeAsync(peer.socket, data).catch(() => {
-                /* broken connection — cleanup handled by close/error listeners */
-            }));
-        }
-        for (const queue of this.pendingOutbound.values()) {
-            queue.push(message);
-            if (queue.length > MAX_PENDING_PER_PEER)
-                queue.shift();
-        }
-        await Promise.all(writes);
-    }
-    /** Send messages queued while the peer's connection was being dialled. */
-    async flushPending(peerId, socket) {
-        const queue = this.pendingOutbound.get(peerId);
-        this.pendingOutbound.delete(peerId);
-        if (queue === undefined)
-            return;
-        for (const message of queue) {
-            const sent = await writeAsync(socket, encode(message)).then(() => true, () => false);
-            if (!sent)
-                return; // connection is dying; close/error listeners clean up
-        }
-    }
-    // -----------------------------------------------------------------------
-    // MeshTransport — Shutdown / unref
-    // -----------------------------------------------------------------------
-    shutdown() {
-        this.shutDown = true;
-        if (this.coordinatorHandshakeTimer !== undefined) {
-            clearTimeout(this.coordinatorHandshakeTimer);
-            this.coordinatorHandshakeTimer = undefined;
-        }
-        this.resolveCoordinatorHandshake = undefined;
-        // Destroy the coordinator client socket
-        this.coordinatorSocket?.unref();
-        this.coordinatorSocket?.destroy();
-        this.coordinatorSocket = undefined;
-        // Destroy all identified peer connections
-        for (const [, peer] of this.peerConnections) {
-            peer.socket.unref();
-            peer.socket.destroy();
-        }
-        this.peerConnections.clear();
-        // Destroy all data server accepted sockets (including unidentified)
-        for (const socket of this.dataServerSockets) {
-            socket.unref();
-            socket.destroy();
-        }
-        this.dataServerSockets.clear();
-        // Destroy all coordinator server accepted sockets
-        for (const socket of this.coordinatorServerSockets) {
-            socket.unref();
-            socket.destroy();
-        }
-        this.coordinatorServerSockets.clear();
-        // Clear introduction connection tracking
-        this.introConnections.clear();
-        // Clear pending connections
-        for (const [, pending] of this.pendingConnections) {
-            pending.socket.unref();
-            pending.socket.destroy();
-        }
-        this.pendingConnections.clear();
-        // Close data server
-        this.dataServer?.unref();
-        this.dataServer?.close();
-        this.dataServer = undefined;
-        // Close coordinator listener servers — stop accepting new connections
-        for (const [, listener] of this.coordinatorListeners) {
-            listener.server.unref();
-            listener.server.close();
-        }
-        this.coordinatorListeners.clear();
-        this.defaultListenerId = undefined;
-        this._isCoordinator = false;
-        return Promise.resolve();
-    }
-    unref() {
-        this.dataServer?.unref();
-        for (const [, listener] of this.coordinatorListeners) {
-            listener.server.unref();
-        }
-        this.coordinatorSocket?.unref();
-    }
-    // -----------------------------------------------------------------------
-    // Internal — Coordinator client message dispatch
-    // -----------------------------------------------------------------------
-    /**
-     * Handles messages received on the coordinator client socket (the
-     * connection from this peer TO the coordinator). Fires the appropriate
-     * TransportEvents for peer_list, peer_joined, and become_coordinator.
-     */
-    dispatchCoordinatorClientMessage(msg) {
-        if (this.shutDown)
-            return;
-        if (msg.method === "peer_list") {
-            // Fire onPeerList first: it starts the post-join dials (and their
-            // broadcast queues) before init() resolves.
-            this.events.onPeerList(msg.peers);
-            this.completeCoordinatorHandshake();
-        }
-        else if (msg.method === "peer_joined") {
-            this.events.onPeerJoined(msg.peer);
-        }
-        else if (msg.method === "become_coordinator") {
-            this.events.onBecomeCoordinator(msg.peerList);
-        }
-    }
-    /** Complete connectToCoordinator's handshake after the peer list arrives. */
-    completeCoordinatorHandshake() {
-        if (this.coordinatorHandshakeTimer !== undefined) {
-            clearTimeout(this.coordinatorHandshakeTimer);
-            this.coordinatorHandshakeTimer = undefined;
-        }
-        this.resolveCoordinatorHandshake?.();
-        this.resolveCoordinatorHandshake = undefined;
-    }
-    // -----------------------------------------------------------------------
-    // Internal — Data message dispatch
-    // -----------------------------------------------------------------------
-    /**
-     * Routes a message received on a peer data connection to the
-     * appropriate event. become_coordinator has its own event; all
-     * other messages fire onMessage for MeshStore to handle.
-     */
-    dispatchDataMessage(handle, msg) {
-        if (this.shutDown)
-            return;
-        if (msg.method === "become_coordinator") {
-            this.events.onBecomeCoordinator(msg.peerList);
-        }
-        else {
-            this.events.onMessage(handle, msg);
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Internal — Coordinator server connection handling
-    // -----------------------------------------------------------------------
-    /**
-     * Accepts a new connection on a coordinator server. Reads
-     * introduce messages and fires onIntroduction so MeshStore can
-     * respond with the peer list and broadcast the arrival.
-     * The connection is tagged with the listener's policy.
-     */
-    handleCoordinatorServerConnection(socket, policy) {
-        if (this.shutDown) {
-            socket.destroy();
-            return;
-        }
-        this.coordinatorServerSockets.add(socket);
-        socket.on("close", () => this.coordinatorServerSockets.delete(socket));
-        socket.on("error", () => this.coordinatorServerSockets.delete(socket));
-        const buffer = new MessageBuffer();
-        attachSocketHandshake(socket, "server", (data) => {
-            const items = buffer.append(data.toString());
-            for (const item of items) {
-                if (!isMeshMessage(item))
-                    continue;
-                if (item.method === "introduce") {
-                    const handle = { id: item.peerId, policy };
-                    this.introConnections.set(handle.id, socket);
-                    this.events.onIntroduction(handle, {
-                        peerId: item.peerId,
-                        dataPort: item.dataPort,
-                    });
-                }
-                else if (item.method === "connect_request") {
-                    const handle = { id: item.peerId, policy };
-                    this.pendingConnections.set(handle.id, {
-                        socket,
-                        peerId: item.peerId,
-                        dataPort: item.dataPort,
-                        name: item.name,
-                        fingerprint: item.fingerprint,
-                        policy,
-                    });
-                    this.events.onConnectionRequest(handle, {
-                        peerId: item.peerId,
-                        dataPort: item.dataPort,
-                        name: item.name,
-                        fingerprint: item.fingerprint,
-                    });
-                }
-            }
-        }, (error) => this.events.onError?.(error));
-    }
-    // -----------------------------------------------------------------------
-    // Internal — Incoming data connection handling
-    // -----------------------------------------------------------------------
-    /**
-     * Accepts a new connection on the data server. Reads the initial
-     * pong to identify the peer, then fires onMessage for subsequent
-     * messages. Tracks the connection for cleanup on close/error.
-     */
-    handleIncomingDataConnection(socket) {
-        if (this.shutDown) {
-            socket.destroy();
-            return;
-        }
-        this.dataServerSockets.add(socket);
-        socket.on("close", () => this.dataServerSockets.delete(socket));
-        const buffer = new MessageBuffer();
-        let remotePeerId;
-        let disconnected = false;
-        attachSocketHandshake(socket, "server", (data) => {
-            const items = buffer.append(data.toString());
-            for (const item of items) {
-                if (isMeshMessage(item)) {
-                    if (item.method === "pong") {
-                        const peerId = item.peerId;
-                        remotePeerId = peerId;
-                        if (!this.peerConnections.has(peerId)) {
-                            this.peerConnections.set(peerId, { socket, buffer });
-                        }
-                        void this.flushPending(peerId, socket);
-                        const handle = { id: peerId };
-                        const info = {
-                            id: peerId,
-                            port: 0,
-                            startedAt: new Date().toISOString(),
-                        };
-                        this.events.onPeerConnected(handle, info);
-                    }
-                    else if (remotePeerId !== undefined) {
-                        const handle = { id: remotePeerId };
-                        this.dispatchDataMessage(handle, item);
-                    }
-                }
-            }
-        }, (error) => this.events.onError?.(error));
-        const onDisconnect = () => {
-            if (disconnected)
-                return;
-            disconnected = true;
-            if (remotePeerId !== undefined) {
-                this.peerConnections.delete(remotePeerId);
-                if (!this.shutDown) {
-                    this.events.onPeerDisconnected({ id: remotePeerId });
-                }
-            }
-        };
-        socket.on("close", onDisconnect);
-        socket.on("error", onDisconnect);
-    }
-}
-//# sourceMappingURL=tcp-transport.js.map