@love-moon/conductor-sdk 0.2.16 → 0.2.18

package/dist/ws/client.js

@@ -16,10 +16,12 @@ export class ConductorWebSocketClient {
     connectImpl;
     onConnected;
     onDisconnected;
+    onPong;
     onReconnected;
     handlers = [];
     extraHeaders;
     conn = null;
+    runtime = null;
     stop = false;
     listenTask = null;
     heartbeatTask = null;
@@ -38,6 +40,7 @@ export class ConductorWebSocketClient {
         this.connectImpl = options.connectImpl ?? defaultConnectImpl;
         this.onConnected = options.onConnected;
         this.onDisconnected = options.onDisconnected;
+        this.onPong = options.onPong;
         this.onReconnected = options.onReconnected;
     }
     registerHandler(handler) {
@@ -60,9 +63,20 @@ export class ConductorWebSocketClient {
             this.heartbeatTask = null;
         }
         if (this.conn && !this.isConnectionClosed(this.conn)) {
-            await this.conn.close();
+            this.markDisconnectReason(this.conn, 'manual_disconnect');
+            await this.closeConnection(this.conn);
         }
         this.conn = null;
+        this.runtime = null;
+    }
+    async forceReconnect(reason = 'manual_reconnect') {
+        const conn = this.conn;
+        if (!conn || this.isConnectionClosed(conn)) {
+            await this.openConnection(true);
+            return;
+        }
+        this.markDisconnectReason(conn, reason);
+        await this.terminateConnection(conn);
     }
     async sendJson(payload) {
         await this.ensureConnection();
@@ -83,15 +97,19 @@ export class ConductorWebSocketClient {
             while (!this.stop) {
                 try {
                     const headers = { Authorization: `Bearer ${this.token}`, ...this.extraHeaders };
-                    this.conn = await this.connectImpl(this.url, { headers });
+                    const conn = await this.connectImpl(this.url, { headers });
+                    const runtime = this.createRuntime(conn);
+                    this.attachConnectionObservers(runtime);
+                    this.conn = conn;
+                    this.runtime = runtime;
                     const isReconnect = this.hasConnectedAtLeastOnce;
                     this.hasConnectedAtLeastOnce = true;
-                    this.notifyConnected(isReconnect);
+                    this.notifyConnected({ isReconnect, connectedAt: runtime.connectedAt });
                     if (isReconnect) {
                         this.notifyReconnected();
                     }
-                    this.listenTask = this.listenLoop(this.conn);
-                    this.heartbeatTask = this.heartbeatLoop(this.conn);
+                    this.listenTask = this.listenLoop(conn);
+                    this.heartbeatTask = this.heartbeatLoop(conn);
                     return;
                 }
                 catch (error) {
@@ -124,10 +142,26 @@ export class ConductorWebSocketClient {
         try {
             while (!this.stop && !this.isConnectionClosed(conn)) {
                 await wait(this.heartbeatInterval, this.waitController.signal);
+                if (this.stop || conn !== this.conn) {
+                    return;
+                }
+                const runtime = this.getRuntime(conn);
+                if (!runtime) {
+                    return;
+                }
+                if (runtime.supportsPongTracking && runtime.waitingForPong) {
+                    runtime.missedPongs += 1;
+                    runtime.disconnectReason = 'pong_timeout';
+                    await this.terminateConnection(conn);
+                    break;
+                }
+                runtime.lastPingAt = Date.now();
+                runtime.waitingForPong = runtime.supportsPongTracking;
                 try {
                     await conn.ping();
                 }
                 catch {
+                    this.markDisconnectReason(conn, 'ping_failed');
                     break;
                 }
             }
@@ -140,11 +174,17 @@ export class ConductorWebSocketClient {
         if (this.stop || conn !== this.conn) {
             return;
         }
+        const runtime = this.getRuntime(conn);
         this.conn = null;
-        this.notifyDisconnected();
+        this.runtime = null;
+        this.notifyDisconnected(this.buildDisconnectEvent(runtime));
         await this.openConnection(true);
     }
     async dispatch(message) {
+        const now = Date.now();
+        if (this.runtime) {
+            this.runtime.lastMessageAt = now;
+        }
         let payload;
         try {
             payload = JSON.parse(message);
@@ -159,12 +199,12 @@ export class ConductorWebSocketClient {
             }
         }
     }
-    notifyConnected(isReconnect) {
+    notifyConnected(event) {
         if (!this.onConnected) {
             return;
         }
         try {
-            this.onConnected({ isReconnect });
+            this.onConnected(event);
         }
         catch {
             // Swallow callback errors to avoid impacting reconnect behavior.
@@ -181,12 +221,12 @@ export class ConductorWebSocketClient {
             // Swallow callback errors to avoid impacting reconnect behavior.
         }
     }
-    notifyDisconnected() {
+    notifyDisconnected(event) {
         if (!this.onDisconnected) {
             return;
         }
         try {
-            this.onDisconnected();
+            this.onDisconnected(event);
         }
         catch {
             // Swallow callback errors to avoid impacting reconnect behavior.
@@ -222,8 +262,10 @@ export class ConductorWebSocketClient {
                 }
                 attemptedReconnect = true;
                 if (this.conn === conn) {
+                    this.markDisconnectReason(conn, 'send_reconnect');
                     this.conn = null;
-                    this.notifyDisconnected();
+                    this.notifyDisconnected(this.buildDisconnectEvent(this.getRuntime(conn)));
+                    this.runtime = null;
                 }
                 await this.openConnection(true);
             }
@@ -235,6 +277,100 @@ export class ConductorWebSocketClient {
         const message = error instanceof Error ? error.message : String(error);
         return message.toLowerCase().includes('websocket is not open');
     }
+    createRuntime(conn) {
+        const connectedAt = Date.now();
+        return {
+            conn,
+            connectedAt,
+            supportsPongTracking: typeof conn.onPong === 'function',
+            lastMessageAt: null,
+            lastPingAt: null,
+            lastPongAt: connectedAt,
+            waitingForPong: false,
+            missedPongs: 0,
+            disconnectReason: null,
+            closeCode: null,
+            closeReason: null,
+            socketError: null,
+        };
+    }
+    attachConnectionObservers(runtime) {
+        runtime.conn.onPong?.(() => {
+            const activeRuntime = this.getRuntime(runtime.conn);
+            if (!activeRuntime) {
+                return;
+            }
+            const at = Date.now();
+            const latencyMs = activeRuntime.lastPingAt ? at - activeRuntime.lastPingAt : null;
+            activeRuntime.lastPongAt = at;
+            activeRuntime.waitingForPong = false;
+            activeRuntime.missedPongs = 0;
+            if (this.onPong) {
+                try {
+                    this.onPong({ at, latencyMs });
+                }
+                catch {
+                    // Swallow callback errors to avoid impacting reconnect behavior.
+                }
+            }
+        });
+        runtime.conn.onCloseInfo?.((info) => {
+            const activeRuntime = this.getRuntime(runtime.conn);
+            if (!activeRuntime) {
+                return;
+            }
+            activeRuntime.closeCode = typeof info.code === 'number' ? info.code : null;
+            activeRuntime.closeReason = normalizeOptionalString(info.reason);
+        });
+        runtime.conn.onErrorInfo?.((error) => {
+            const activeRuntime = this.getRuntime(runtime.conn);
+            if (!activeRuntime) {
+                return;
+            }
+            activeRuntime.socketError = error instanceof Error ? error.message : String(error);
+            if (!activeRuntime.disconnectReason) {
+                activeRuntime.disconnectReason = 'socket_error';
+            }
+        });
+    }
+    getRuntime(conn) {
+        if (!this.runtime || this.runtime.conn !== conn) {
+            return null;
+        }
+        return this.runtime;
+    }
+    markDisconnectReason(conn, reason) {
+        const runtime = this.getRuntime(conn);
+        if (runtime && !runtime.disconnectReason) {
+            runtime.disconnectReason = reason;
+        }
+    }
+    buildDisconnectEvent(runtime) {
+        return {
+            reason: runtime?.disconnectReason || 'connection_lost',
+            disconnectedAt: Date.now(),
+            connectedAt: runtime?.connectedAt ?? null,
+            closeCode: runtime?.closeCode ?? null,
+            closeReason: runtime?.closeReason ?? null,
+            socketError: runtime?.socketError ?? null,
+            missedPongs: runtime?.missedPongs ?? 0,
+            lastPingAt: runtime?.lastPingAt ?? null,
+            lastPongAt: runtime?.lastPongAt ?? null,
+            lastMessageAt: runtime?.lastMessageAt ?? null,
+        };
+    }
+    async closeConnection(conn) {
+        if (typeof conn.close === 'function') {
+            await conn.close();
+        }
+    }
+    async terminateConnection(conn) {
+        if (typeof conn.terminate === 'function') {
+            await conn.terminate();
+            return;
+        }
+        await this.closeConnection(conn);
+    }
 }
 async function wait(ms, signal) {
     if (!signal) {
@@ -276,16 +412,34 @@ class WsAdapter {
     ws;
     queue = [];
     waiters = [];
+    pongHandlers = new Set();
+    closeInfoHandlers = new Set();
+    errorHandlers = new Set();
     closed = false;
     constructor(ws) {
         this.ws = ws;
         ws.on('message', (data) => this.enqueue(data.toString()));
-        ws.on('close', () => {
+        ws.on('pong', () => {
+            for (const handler of this.pongHandlers) {
+                handler();
+            }
+        });
+        ws.on('close', (code, reason) => {
             this.closed = true;
+            const closeInfo = {
+                code,
+                reason: normalizeOptionalString(reason?.toString()),
+            };
+            for (const handler of this.closeInfoHandlers) {
+                handler(closeInfo);
+            }
             this.enqueue(null);
         });
-        ws.on('error', () => {
+        ws.on('error', (error) => {
             this.closed = true;
+            for (const handler of this.errorHandlers) {
+                handler(error);
+            }
             this.enqueue(null);
         });
     }
@@ -323,6 +477,21 @@ class WsAdapter {
             this.ws.close();
         });
     }
+    terminate() {
+        if (this.closed) {
+            return;
+        }
+        this.ws.terminate();
+    }
+    onPong(handler) {
+        this.pongHandlers.add(handler);
+    }
+    onCloseInfo(handler) {
+        this.closeInfoHandlers.add(handler);
+    }
+    onErrorInfo(handler) {
+        this.errorHandlers.add(handler);
+    }
     async *[Symbol.asyncIterator]() {
         while (true) {
             const value = await this.nextValue();
@@ -351,3 +520,10 @@ class WsAdapter {
         }
     }
 }
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed || null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@love-moon/conductor-sdk",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,5 +27,5 @@
     "typescript": "^5.6.3",
     "vitest": "^2.1.4"
   },
-  "gitCommitId": "13b4d6c"
+  "gitCommitId": "942418b"
 }