@persistica/flux-agent 0.0.28 → 0.0.35

package/README.md

@@ -1,22 +1,28 @@
-# Flux Agent
+# @persistica/flux-agent
 
-```TypeScript
-import { FluxAgent, FluxAgentNetworkConnection } from '@persistica/flux-agent';
+Connect an **Agent** to a Flux network, join channels, and publish/subscribe over the Flux mesh.
 
-const NETWORK_ID = 'network-id-to-connect-to';
+```bash
+bun add @persistica/flux-agent    # or: npm i @persistica/flux-agent
+```
 
-const fluxAgent = new FluxAgent(NETWORK_ID);
+```ts
+import { FluxAgent } from '@persistica/flux-agent';
 
-// * Connect to network
-const fluxNetworkConnection: FluxAgentNetworkConnection = await fluxAgent
-    .connect(
-        'CODE_TO_ACCESS_NETWORK',
-    );
+const agent = new FluxAgent('my-network-id');
 
-console.log(`✅ Agent connected to network ID: '${NETWORK_ID}'`);
+// The argument is your claim — whatever your Authority accepts.
+const connection = await agent.connect({ user: 'alice' });
 
-// * Join network channel
-const fluxConnectedAgentNetworkChannel: FluxNetworkChannel = await fluxNetworkConnection
-    .joinChannel('connected-agents');
+const channel = await connection.joinChannel('connected-agents');
+channel.onPublish((msg) => console.log('received', msg));
+channel.publish({ text: 'hello mesh' });
+```
 
-```
+> A network needs an **Authority** ([`@persistica/flux-authority`](../authority/README.md)) running
+> before any Agent can join. With none present, `connect()` stays in the `waiting-for-authority`
+> state and keeps retrying. Attach `agent.onNetworkState(...)` and wrap `connect()` in a `try/catch`
+> to observe this.
+
+Full reference (options, connection states, error handling, troubleshooting):
+[docs/sdk/flux-agent.md](../../../docs/sdk/flux-agent.md).

package/index.js

@@ -43,6 +43,8 @@ var UNSUBSCRIBE_NETWORK_CHANNEL_NAME = "unsubscribe-nc-name";
 var UNSUBSCRIBED_NETWORK_CHANNEL_NAME = "unsubscribed-nc-name";
 var AUTHORITY_CHANNEL_SUBSCRIBE = "acs";
 var AUTHORITY_DISCONNECT_AGENT = "ada";
+var HEARTBEAT_PING = "hb-ping";
+var HEARTBEAT_PONG = "hb-pong";
 var ERROR = "e";
 
 // libs/flux/shared/types/src/lib/client.type.ts
@@ -147,11 +149,21 @@ var WebSocketClient = class extends RPCServer {
   ws;
   isOpen = false;
   // Is the connection open
+  // * Heartbeat (see #488): a half-open socket (1006, no close frame) never fires
+  // `onclose`, so the client pings on an interval and treats a missed pong as the
+  // disconnect signal itself — it cannot rely on `ws.close()` producing an event.
+  heartbeatTimer;
+  awaitingPong = false;
+  pongSeen = false;
+  // The server proved it answers pings on this connection
+  closeHandled = false;
+  // Guards against running the close path twice (heartbeat + late onclose)
   constructor(options) {
     super();
     this.options = {
       autoReconnect: true,
       reconnectDelay: 1e3,
+      maxReconnectDelay: 3e4,
       heartbeatInterval: 6e4,
       connectionTimeout: 5e3,
       ...options
@@ -162,50 +174,48 @@ var WebSocketClient = class extends RPCServer {
    */
   connect() {
     return new Promise((resolve, reject) => {
+      this.closeHandled = false;
       this.emit("connecting", this.reconnectAttempts);
-      this.ws = new WebSocket(
+      const socket = new WebSocket(
         this.options.url
       );
+      this.ws = socket;
       const timeout = setTimeout(() => {
-        if (this.ws?.readyState !== WebSocket.OPEN) {
-          this.ws?.close();
+        if (socket.readyState !== WebSocket.OPEN) {
+          socket.close();
           reject(new Error("Connection timeout"));
         }
       }, this.options.connectionTimeout);
-      this.ws.onopen = () => {
+      socket.onopen = () => {
         clearTimeout(timeout);
+        if (this.ws !== socket) {
+          return;
+        }
         this.reconnectAttempts = 0;
         this.isOpen = true;
+        this.startHeartbeat();
         this.emit("open");
         resolve();
       };
-      this.ws.onmessage = (event) => {
+      socket.onmessage = (event) => {
+        if (this.ws !== socket) {
+          return;
+        }
+        if (event.data === HEARTBEAT_PONG) {
+          this.awaitingPong = false;
+          this.pongSeen = true;
+          return;
+        }
         this.emit("message", event.data);
       };
-      this.ws.onclose = (closeEvent) => {
-        const wasKicked = closeEvent.reason === "Kicked by process";
+      socket.onclose = (closeEvent) => {
         clearTimeout(timeout);
-        if (this.isOpen) {
-          this.emit(
-            "close",
-            wasKicked ? "kicked" : void 0
-          );
-          this.isOpen = false;
-        }
-        if (this.options.autoReconnect && (this.options.retries === void 0 || this.reconnectAttempts < this.options.retries)) {
-          const delay = wasKicked ? RECONNECTION_DELAY_ON_KICK_MS : Math.min(
-            this.options.reconnectDelay ?? Number.POSITIVE_INFINITY,
-            (this.options.reconnectDelay ?? 0) * (this.reconnectAttempts || 1)
-          );
-          setTimeout(() => {
-            this.reconnectAttempts++;
-            void this.connect();
-          }, delay);
-        } else if (this.options.autoReconnect) {
-          this.emit("error", new Error("Connection failed: retries exhausted"));
+        if (this.ws !== socket) {
+          return;
         }
+        this.handleConnectionClosed(closeEvent.reason === "Kicked by process");
       };
-      this.ws.onerror = (event) => {
+      socket.onerror = (event) => {
         if (event?.message?.includes("Failed to connect")) {
         } else {
           console.log("\u274C Error", event.message);
@@ -213,6 +223,84 @@ var WebSocketClient = class extends RPCServer {
       };
     });
   }
+  /**
+   * The single close path, reachable from `onclose` AND from a missed heartbeat
+   * pong (where `onclose` never fires): emit `close` once, then schedule the
+   * reconnect per the retry policy.
+   */
+  handleConnectionClosed(wasKicked) {
+    if (this.closeHandled) {
+      return;
+    }
+    this.closeHandled = true;
+    this.stopHeartbeat();
+    if (this.isOpen) {
+      this.emit(
+        "close",
+        wasKicked ? "kicked" : void 0
+      );
+      this.isOpen = false;
+    }
+    if (this.options.autoReconnect && (this.options.retries === void 0 || this.reconnectAttempts < this.options.retries)) {
+      const delay = wasKicked ? RECONNECTION_DELAY_ON_KICK_MS : Math.min(
+        this.options.maxReconnectDelay ?? Number.POSITIVE_INFINITY,
+        (this.options.reconnectDelay ?? 0) * 2 ** this.reconnectAttempts
+      );
+      setTimeout(() => {
+        this.reconnectAttempts++;
+        this.connect().catch((error) => {
+          this.emit(
+            "error",
+            error instanceof Error ? error : new Error(String(error))
+          );
+        });
+      }, delay);
+    } else if (this.options.autoReconnect) {
+      this.emit("error", new Error("Connection failed: retries exhausted"));
+    }
+  }
+  /**
+   * Starts the keepalive: every `heartbeatInterval` send an app-level ping (the
+   * browser/Bun `WebSocket` exposes no ping frame) and require the mesh's pong
+   * before the next tick. A missed pong means the socket is dead — force the
+   * close path directly, since a half-open socket produces no `onclose`.
+   */
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.pongSeen = false;
+    const interval = this.options.heartbeatInterval;
+    if (interval === void 0 || interval <= 0) {
+      return;
+    }
+    this.heartbeatTimer = setInterval(() => {
+      if (this.awaitingPong) {
+        if (!this.pongSeen) {
+          console.warn("\u{1F49B} Server does not answer heartbeat pings \u2014 dead-connection detection disabled for this connection");
+          this.stopHeartbeat();
+          return;
+        }
+        console.warn(`\u{1F494} No heartbeat pong within ${interval}ms \u2014 treating the connection as dead`);
+        this.stopHeartbeat();
+        try {
+          this.ws?.close(4e3, "Heartbeat timeout");
+        } catch {
+        }
+        this.handleConnectionClosed(false);
+        return;
+      }
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.awaitingPong = true;
+        this.ws.send(HEARTBEAT_PING);
+      }
+    }, interval);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer !== void 0) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    this.awaitingPong = false;
+  }
   /**
    * Emits a WebSocket event to all registered listeners.
    */
@@ -253,6 +341,7 @@ var WebSocketClient = class extends RPCServer {
    */
   close() {
     this.options.autoReconnect = false;
+    this.stopHeartbeat();
     this.ws?.close();
     this.clearEventSubscribers();
   }
@@ -290,22 +379,12 @@ var peerConnectionConfig = {
   ]
 };
 var ICEConnection = class {
-  constructor(_fluxWebSocketClientConnection, _stateChange) {
+  constructor(_fluxWebSocketClientConnection, _stateChange, _onMessage) {
     this._fluxWebSocketClientConnection = _fluxWebSocketClientConnection;
     this._stateChange = _stateChange;
+    this._onMessage = _onMessage;
     this.peerConnection.ondatachannel = (event) => {
-      console.log("*********** GOT DATAT SCHANNNEL ");
-      this.dataChannel = event.channel;
-      this.dataChannel.onopen = () => console.log("ReceiveChannel opened");
-      this.dataChannel.onmessage = (event2) => {
-        console.log("Receiving ICE event", event2);
-      };
-      this.dataChannel.onopen = () => {
-        console.log("Opened");
-      };
-      this.dataChannel.onclose = () => {
-        console.log("Opened");
-      };
+      this._wireDataChannel(event.channel);
     };
     this.peerConnection.onicecandidate = (event) => {
       if (event.candidate) {
@@ -323,10 +402,10 @@ var ICEConnection = class {
   }
   _fluxWebSocketClientConnection;
   _stateChange;
+  _onMessage;
   //extends RPCServer<'createOffer' | 'acceptOffer' | 'acceptAnswer'> {
   peerConnection = new RTCPeerConnection(peerConnectionConfig);
   dataChannel;
-  //  = this.peerConnection.createDataChannel('flux-channel');
   offerSDP;
   /**
    * This offer must be sent to the other peer.
@@ -335,7 +414,7 @@ var ICEConnection = class {
    */
   async createOffer() {
     console.log("creating offer and data channel");
-    this.dataChannel = this.peerConnection.createDataChannel("flux-channel");
+    this._wireDataChannel(this.peerConnection.createDataChannel("flux-channel"));
     this._stateChange("creating-offer");
     const offer = await this.peerConnection.createOffer();
     await this.peerConnection.setLocalDescription(offer);
@@ -380,9 +459,28 @@ var ICEConnection = class {
   answerAcceptedByInitiator(answerAccepted) {
     this._stateChange(answerAccepted ? "connected" : "failed");
   }
+  /**
+   * Wires up a data channel's lifecycle handlers. Used for both the initiator's
+   * locally-created channel and the receiver's incoming channel so inbound
+   * messages are delivered the same way on both ends.
+   *
+   * @param { RTCDataChannel } channel - The data channel to wire up
+   */
+  _wireDataChannel(channel) {
+    this.dataChannel = channel;
+    channel.onopen = () => {
+      console.log("Data channel opened");
+    };
+    channel.onclose = () => {
+      console.log("Data channel closed");
+    };
+    channel.onmessage = (event) => {
+      this._onMessage(event.data);
+    };
+  }
   /**
    * Sends a message to the connected peer via the WebRTC data channel.
-   * 
+   *
    * @param { string } message - The message to send
    */
   sendMessage(message) {
@@ -397,14 +495,16 @@ var ICEConnection = class {
 
 // libs/flux/shared/connection/src/lib/agent/flux-agent-network.class.ts
 var FluxAgentNetworkConnection = class {
-  constructor(_fluxWebSocketConnection, _fluxWebSocketClientConnection, _webRTCStateChange) {
+  constructor(_fluxWebSocketConnection, _fluxWebSocketClientConnection, _webRTCStateChange, _onDirectMessage) {
     this._fluxWebSocketConnection = _fluxWebSocketConnection;
     this._fluxWebSocketClientConnection = _fluxWebSocketClientConnection;
     this._webRTCStateChange = _webRTCStateChange;
+    this._onDirectMessage = _onDirectMessage;
     if (typeof RTCPeerConnection !== "undefined") {
       this.iceConnection = new ICEConnection(
         this._fluxWebSocketClientConnection,
-        this._webRTCStateChange
+        this._webRTCStateChange,
+        this._onDirectMessage
       );
       console.log(`RTCPeerConnection is available`);
     } else {
@@ -414,6 +514,7 @@ var FluxAgentNetworkConnection = class {
   _fluxWebSocketConnection;
   _fluxWebSocketClientConnection;
   _webRTCStateChange;
+  _onDirectMessage;
   iceConnection;
   connectedChannelSet = /* @__PURE__ */ new Set();
   /**
@@ -514,8 +615,10 @@ var FluxNetworkChannel = class {
   onPublish(fn) {
     this._fluxWebSocketConnection.onPublish(
       this._channelName,
+      // The transport types payloads as `string` (TMessageCallback), but
+      // `o:`-prefixed messages are JSON-parsed before delivery, so the
+      // callback actually receives `T`. Bridge the two deliberately.
       fn
-      // TODO
     );
   }
 };
@@ -734,7 +837,7 @@ var FluxWebSocketConnection = class {
     });
     this.socket.clearEventSubscribers();
     this.socket.on("message", this.socketMessageHandler).on("close", this.socketCloseHandler).on("connecting", this.socketConnectingHandler).on("error", this.socketErrorHandler);
-    void this.socket.connect();
+    this.socket.connect().catch(this.socketErrorHandler);
     return this.connectPromise;
   }
   /**
@@ -768,7 +871,8 @@ var FluxWebSocketConnection = class {
     return Promise.resolve(new FluxAgentNetworkConnection(
       this,
       webSocketClient,
-      this.stateManager.emitWebRTCState.bind(this.stateManager)
+      this.stateManager.emitWebRTCState.bind(this.stateManager),
+      this.stateManager.emitDirectMessage.bind(this.stateManager)
     ));
   }
   /**
@@ -796,7 +900,7 @@ var FluxWebSocketConnection = class {
    */
   publish(channelName, message) {
     if (this.webSocketClient) {
-      const messageString = typeof message === "string" ? message : `o:${JSON.stringify(message)}`;
+      const messageString = typeof message === "string" ? `s:${message}` : `o:${JSON.stringify(message)}`;
       this.webSocketClient.send(`${NETWORK_CHANNEL_PUBLISH}:${channelName}:${messageString}`);
     }
   }
@@ -909,13 +1013,18 @@ var FluxWebSocketConnection = class {
         if (validateChannelNameOrThrow(channelName)) {
           const topicCallbacks = this.channelCallbacks.get(channelName);
           if (topicCallbacks) {
-            let data = message_.slice(thirdColon + 1);
-            if (data.startsWith("o:")) {
+            const raw = message_.slice(thirdColon + 1);
+            let data;
+            if (raw.startsWith("o:")) {
               try {
-                data = JSON.parse(data.substring(2));
+                data = JSON.parse(raw.substring(2));
               } catch {
-                data = data.substring(2);
+                data = raw.substring(2);
               }
+            } else if (raw.startsWith("s:")) {
+              data = raw.substring(2);
+            } else {
+              data = raw;
             }
             for (const cb of topicCallbacks) {
               cb(data);
@@ -1002,6 +1111,7 @@ async function encrypt(data, password) {
 var StateManager = class {
   networkStateListeners = /* @__PURE__ */ new Set();
   webRTCStateListeners = /* @__PURE__ */ new Set();
+  directMessageListeners = /* @__PURE__ */ new Set();
   /**
    * Attaches a listener for network connection state changes.
    */
@@ -1026,6 +1136,28 @@ var StateManager = class {
   detachWebRTCStateListener(fn) {
     this.webRTCStateListeners.delete(fn);
   }
+  /**
+   * Attaches a listener for messages received directly from a peer over a
+   * WebRTC data channel (i.e. off-Mesh, peer-to-peer).
+   */
+  attachDirectMessageListener(fn) {
+    this.directMessageListeners.add(fn);
+  }
+  /**
+   * Detaches a previously registered direct-message listener.
+   */
+  detachDirectMessageListener(fn) {
+    this.directMessageListeners.delete(fn);
+  }
+  /**
+   * Emits a message received over a peer-to-peer WebRTC data channel to all
+   * registered listeners.
+   */
+  emitDirectMessage(message) {
+    for (const fn of this.directMessageListeners) {
+      fn(message);
+    }
+  }
   /**
    * Emits a network connection state change to all registered listeners.
    */
@@ -1123,12 +1255,12 @@ var getMachineUID = async () => {
   if (typeof globalThis !== "object") {
     throw new Error("Flux can only be used in an environment with globalThis");
   }
-  if (globalThis.__flux_client_id !== null) {
+  if (globalThis.__flux_client_id !== null && globalThis.__flux_client_id !== void 0) {
     console.log("[flux-client] Reusing existing id");
     return globalThis.__flux_client_id;
   }
   globalThis.__flux_client_id = null;
-  return globalThis.__flux_client_id;
+  return null;
 };
 
 // packages/flux/agent/src/lib/connector/auth/register-client.auth.ts
@@ -1206,6 +1338,7 @@ var FluxClientData = class {
 
 // packages/flux/agent/src/lib/flux-agent.class.ts
 var DEFAULT_FLUX_DOMAIN = "https://mesh.persistica.io";
+var MAX_CONNECT_ATTEMPTS = 100;
 var FluxAgent = class {
   id = nanoid();
   networkId;
@@ -1235,6 +1368,7 @@ var FluxAgent = class {
       if (clientUId && !validateAgentUIDOrThrow(clientUId)) {
         throw new Error("Will never be thrown");
       }
+      let warnedWaitingForAuthority = false;
       const ticket = await retryOrThrow(
         async () => {
           return authenticateAgentOrThrow(
@@ -1250,10 +1384,21 @@ var FluxAgent = class {
         // Retry if no authority was found yet
         (error) => error instanceof NetworkAuthorityNotFoundError,
         {
-          retries: 100,
+          // Fixed by the SDK, not the consuming app: Agents run on untrusted client
+          // machines, so the mesh operator — not the app — controls how long an Agent
+          // waits for an Authority to appear.
+          retries: MAX_CONNECT_ATTEMPTS,
           delayMs: 500,
-          // Backoff until 3 seconds
-          onRetry: (attempt) => Math.min(3e3, 500 + attempt * 200)
+          onRetry: (attempt, retries) => {
+            this.stateManager.emitNetworkState("waiting-for-authority");
+            if (!warnedWaitingForAuthority) {
+              warnedWaitingForAuthority = true;
+              console.warn(
+                `[flux-agent] No Authority is registered on network '${this.networkId}' yet. An Authority must be running before Agents can join; retrying up to ${retries} times until one appears. If this never resolves, start your Authority process (or check its Network Access Token).`
+              );
+            }
+            return Math.min(3e3, 500 + attempt * 200);
+          }
         }
       );
       this.fluxWebSocketConnection = createWSConnection(
@@ -1288,6 +1433,14 @@ var FluxAgent = class {
    * Attaches a listener for WebRTC connection state changes.
    */
   onWebRTConnectionState = this.stateManager.attachWebRTCStateListener.bind(this.stateManager);
+  /**
+   * Attaches a listener for messages received directly from a peer over a
+   * WebRTC data channel (off-Mesh, peer-to-peer).
+   *
+   * NB: unlike channel messages, the sender identity is NOT Mesh-stamped
+   * (see ADR-0004) — the message is whatever arrived on the peer connection.
+   */
+  onDirectPublish = this.stateManager.attachDirectMessageListener.bind(this.stateManager);
   /**
    * Attaches a listener for network connection state changes.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@persistica/flux-agent",
-    "version": "0.0.28",
+    "version": "0.0.35",
     "description": "Persistica Flux Agent",
     "type": "module",
     "keywords": [],

package/src/lib/connector/low-level-com/web-rtc/ice-connection.d.ts

@@ -9,10 +9,18 @@ import type { FluxWebSocketClientConnection } from '@flux/shared/ws';
 export declare class ICEConnection {
     private readonly _fluxWebSocketClientConnection;
     private readonly _stateChange;
+    /**
+     * Called with every message received from the peer over the data channel.
+     */
+    private readonly _onMessage;
     private readonly peerConnection;
     private dataChannel;
     private offerSDP;
-    constructor(_fluxWebSocketClientConnection: FluxWebSocketClientConnection, _stateChange: (state: TRTCState) => void);
+    constructor(_fluxWebSocketClientConnection: FluxWebSocketClientConnection, _stateChange: (state: TRTCState) => void, 
+    /**
+     * Called with every message received from the peer over the data channel.
+     */
+    _onMessage: (message: string) => void);
     /**
      * This offer must be sent to the other peer.
      *
@@ -41,6 +49,14 @@ export declare class ICEConnection {
      * @param { boolean } answerAccepted - Whether the answer was accepted
      */
     private answerAcceptedByInitiator;
+    /**
+     * Wires up a data channel's lifecycle handlers. Used for both the initiator's
+     * locally-created channel and the receiver's incoming channel so inbound
+     * messages are delivered the same way on both ends.
+     *
+     * @param { RTCDataChannel } channel - The data channel to wire up
+     */
+    private _wireDataChannel;
     /**
      * Sends a message to the connected peer via the WebRTC data channel.
      *

package/src/lib/flux-agent.class.d.ts

@@ -30,6 +30,14 @@ export declare class FluxAgent {
      * Attaches a listener for WebRTC connection state changes.
      */
     onWebRTConnectionState: (fn: (rtcState: import("@flux/shared/utils").TRTCState) => void) => void;
+    /**
+     * Attaches a listener for messages received directly from a peer over a
+     * WebRTC data channel (off-Mesh, peer-to-peer).
+     *
+     * NB: unlike channel messages, the sender identity is NOT Mesh-stamped
+     * (see ADR-0004) — the message is whatever arrived on the peer connection.
+     */
+    onDirectPublish: (fn: (message: string) => void) => void;
     /**
      * Attaches a listener for network connection state changes.
      */