polfan-server-js-client 0.4.3 → 0.4.4

package/.idea/workspace.xml

@@ -4,8 +4,14 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="831dae43-0da1-47fd-a5f7-33dd5eec2992" name="Changes" comment="Bump version&#10;&#10;This reverts commit b9ff2004">
-      <change beforePath="$PROJECT_DIR$/src/types" beforeDir="false" afterPath="$PROJECT_DIR$/src/types" afterDir="false" />
+    <list default="true" id="831dae43-0da1-47fd-a5f7-33dd5eec2992" name="Changes" comment="Bump version">
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/build/index.cjs.js" beforeDir="false" afterPath="$PROJECT_DIR$/build/index.cjs.js" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/build/index.cjs.js.map" beforeDir="false" afterPath="$PROJECT_DIR$/build/index.cjs.js.map" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/build/index.umd.js" beforeDir="false" afterPath="$PROJECT_DIR$/build/index.umd.js" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/build/index.umd.js.map" beforeDir="false" afterPath="$PROJECT_DIR$/build/index.umd.js.map" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/build/types/WebSocketChatClient.d.ts" beforeDir="false" afterPath="$PROJECT_DIR$/build/types/WebSocketChatClient.d.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/WebSocketChatClient.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/WebSocketChatClient.ts" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -33,7 +39,7 @@
         <entry key="$PROJECT_DIR$/src/types" value="claude/chat-reactions-polls-system-hwea5i" />
       </map>
     </option>
-    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$/src/types" />
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
     <option name="RESET_MODE" value="HARD" />
     <option name="ROOT_SYNC" value="DONT_SYNC" />
   </component>
@@ -85,7 +91,7 @@
     "RunOnceActivity.typescript.service.memoryLimit.init": "true",
     "codeWithMe.voiceChat.enabledByDefault": "false",
     "com.intellij.ml.llm.matterhorn.ej.ui.settings.DefaultModelSelectionForGA.v1": "true",
-    "git-widget-placeholder": "main",
+    "git-widget-placeholder": "master",
     "git.auto.fetch.suggestion.counter": "3",
     "ignore.virus.scanning.warn.message": "true",
     "junie.onboarding.icon.badge.shown": "true",
@@ -258,15 +264,7 @@
       <workItem from="1787648458595" duration="3034000" />
       <workItem from="1787994100244" duration="588000" />
       <workItem from="1788873818076" duration="1523000" />
-      <workItem from="1788879390791" duration="635000" />
-    </task>
-    <task id="LOCAL-00068" summary="Improve reconnect on timeout">
-      <option name="closed" value="true" />
-      <created>1765145773196</created>
-      <option name="number" value="00068" />
-      <option name="presentableId" value="LOCAL-00068" />
-      <option name="project" value="LOCAL" />
-      <updated>1765145773196</updated>
+      <workItem from="1788879390791" duration="2740000" />
     </task>
     <task id="LOCAL-00069" summary="Bump version">
       <option name="closed" value="true" />
@@ -652,7 +650,15 @@
       <option name="project" value="LOCAL" />
       <updated>1787649696666</updated>
     </task>
-    <option name="localTasksCounter" value="117" />
+    <task id="LOCAL-00117" summary="Bump version">
+      <option name="closed" value="true" />
+      <created>1788952429127</created>
+      <option name="number" value="00117" />
+      <option name="presentableId" value="LOCAL-00117" />
+      <option name="project" value="LOCAL" />
+      <updated>1788952429128</updated>
+    </task>
+    <option name="localTasksCounter" value="118" />
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
@@ -744,7 +750,6 @@
     <MESSAGE value="Fixes in WebApiChatClient" />
     <MESSAGE value="Fix resolve window status after jump to message" />
     <MESSAGE value="Fix jumpTo when window is in LIVE state" />
-    <MESSAGE value="Bump version" />
     <MESSAGE value="Unread topic counter in summary, bump version" />
     <MESSAGE value="Unread room counter in summary, bump version" />
     <MESSAGE value="Reconcile tracked state on reconnect" />
@@ -757,7 +762,8 @@
     <MESSAGE value="Revert &quot;User presence status support&quot;&#10;&#10;This reverts commit b9ff2004" />
     <MESSAGE value="Bump version&#10;&#10;This reverts commit b9ff2004" />
     <MESSAGE value="Role flags and the MentionAllRoles permission" />
-    <option name="LAST_COMMIT_MESSAGE" value="Role flags and the MentionAllRoles permission" />
+    <MESSAGE value="Bump version" />
+    <option name="LAST_COMMIT_MESSAGE" value="Bump version" />
   </component>
   <component name="XSLT-Support.FileAssociations.UIState">
     <expand />

package/README.md

@@ -24,6 +24,26 @@ TypeScript client library to handle connection with Devana (new Polfan) chat ser
 })();
 ```
 
+## Connection maintenance
+
+`WebSocketChatClient` keeps the connection alive: after any loss (error, connecting timeout, missing pong, closure with
+a code other than 1000) it reconnects indefinitely, with an exponential backoff between attempts. The `disconnect` event
+tells whether a retry follows. A pending `connect()` promise resolves once an attempt authenticates, and is rejected by
+`disconnect()`, which also stops reconnecting. An invalid token (`Bye` with `AuthenticationException`) rejects `connect()`
+with the `Bye` data, emits an `error` event and stops reconnecting as well.
+
+```js
+const wsClient = new PServ.WebSocketChatClient({
+    token: 'your-access-token',
+    url: 'wss://pserv-websocket-address',
+    connectingTimeoutMs: 10000, // Per attempt (default)
+    reconnect: {
+        minDelayMs: 1000, // Delay before the first retry, doubled on every next one (default)
+        maxDelayMs: 30000, // Maximum delay between retries (default)
+    },
+});
+```
+
 ## State management
 
 The library provides built-in state management for WebSocket client. To enable it, just pass `stateTracking`

package/build/index.cjs.js

@@ -5439,6 +5439,9 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
     WebSocketChatClient_defineProperty(_this, "pingMonitorInterval", void 0);
     WebSocketChatClient_defineProperty(_this, "inFlightPingTimeout", void 0);
     WebSocketChatClient_defineProperty(_this, "lastReceivedMessageAt", void 0);
+    WebSocketChatClient_defineProperty(_this, "reconnectEnabled", false);
+    WebSocketChatClient_defineProperty(_this, "reconnectTimeoutId", void 0);
+    WebSocketChatClient_defineProperty(_this, "reconnectAttempts", 0);
     _this.options = options;
     if ((_this$options$stateTr = _this.options.stateTracking) !== null && _this$options$stateTr !== void 0 ? _this$options$stateTr : true) {
       _this.state = new ChatStateTracker(_this);
@@ -5454,14 +5457,14 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
     key: "connect",
     value: function () {
       var _connect = WebSocketChatClient_asyncToGenerator(/*#__PURE__*/WebSocketChatClient_regenerator().m(function _callee() {
-        var _this$connectPromise2,
-          _this2 = this,
-          _this$options$queryPa,
-          _this$options$connect;
-        var _this$connectPromise, params;
+        var _this2 = this;
+        var _this$connectPromise, connectPromise;
         return WebSocketChatClient_regenerator().w(function (_context) {
           while (1) switch (_context.n) {
             case 0:
+              this.reconnectEnabled = true;
+              // A manual call does not wait for a scheduled retry.
+              this.cancelScheduledReconnect();
               if (!(this.isOpenWsState() || this.isConnectingWsState())) {
                 _context.n = 1;
                 break;
@@ -5471,26 +5474,23 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
               // Reuse the promise of an attempt that has not settled yet (an
               // automatic reconnect), so the caller that started connecting is
               // resolved by whichever attempt eventually authenticates.
-              (_this$connectPromise2 = this.connectPromise) !== null && _this$connectPromise2 !== void 0 ? _this$connectPromise2 : this.connectPromise = new Promise(function () {
-                for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
-                  args[_key] = arguments[_key];
-                }
-                return _this2.authenticatedResolvers = args;
-              });
-              params = new URLSearchParams((_this$options$queryPa = this.options.queryParams) !== null && _this$options$queryPa !== void 0 ? _this$options$queryPa : {});
-              params.set('token', this.options.token);
-              this.ws = new WebSocket("".concat(this.options.url, "?").concat(params));
-              this.ws.onclose = function (ev) {
-                return _this2.onClose(ev);
-              };
-              this.ws.onmessage = function (ev) {
-                return _this2.onMessage(ev);
-              };
-              this.connectingTimeoutId = setTimeout(function () {
-                return _this2.triggerConnectionTimeout();
-              }, (_this$options$connect = this.options.connectingTimeoutMs) !== null && _this$options$connect !== void 0 ? _this$options$connect : 10000);
-              this.authenticated = false;
-              return _context.a(2, this.connectPromise);
+              if (!this.connectPromise) {
+                this.connectPromise = new Promise(function () {
+                  for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+                    args[_key] = arguments[_key];
+                  }
+                  return _this2.authenticatedResolvers = args;
+                });
+                // Automatic reconnects create this promise with no one awaiting it,
+                // so its rejection must not surface as an unhandled one. Callers
+                // awaiting it still receive the rejection.
+                this.connectPromise["catch"](function () {
+                  return undefined;
+                });
+              }
+              connectPromise = this.connectPromise;
+              this.openSocket();
+              return _context.a(2, connectPromise);
           }
         }, _callee, this);
       }));
@@ -5502,10 +5502,16 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
   }, {
     key: "disconnect",
     value: function disconnect() {
-      var _this$ws;
+      var wasActive = this.ws !== null || this.reconnectTimeoutId !== undefined;
+      this.reconnectEnabled = false;
+      this.reconnectAttempts = 0;
+      this.cancelScheduledReconnect();
+      this.releaseSocket(1000); // Normal closure
       this.failPendingCommands(new Error('Client disconnected before the command was answered'));
-      (_this$ws = this.ws) === null || _this$ws === void 0 || _this$ws.close(1000); // Normal closure
-      this.ws = null;
+      this.settleConnect(new Error('Client disconnected before authentication'));
+      if (wasActive) {
+        this.emit(this.Event.disconnect, false);
+      }
     }
   }, {
     key: "send",
@@ -5539,15 +5545,52 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
     get: function get() {
       return this.isOpenWsState() && this.authenticated;
     }
+  }, {
+    key: "openSocket",
+    value: function openSocket() {
+      var _this$options$queryPa,
+        _this3 = this,
+        _this$options$connect;
+      // Never leave a previous socket attached (e.g. one still closing).
+      this.releaseSocket(1000);
+      var params = new URLSearchParams((_this$options$queryPa = this.options.queryParams) !== null && _this$options$queryPa !== void 0 ? _this$options$queryPa : {});
+      params.set('token', this.options.token);
+      var ws;
+      try {
+        ws = new WebSocket("".concat(this.options.url, "?").concat(params));
+      } catch (error) {
+        // Invalid URL - no retry can fix that.
+        this.settleConnect(error);
+        return;
+      }
+
+      // Events of an abandoned socket must not touch the current connection.
+      ws.onmessage = function (ev) {
+        return ws === _this3.ws && _this3.onMessage(ev);
+      };
+      ws.onclose = function (ev) {
+        return ws === _this3.ws && _this3.onClose(ev);
+      };
+      // Not every implementation follows a failed handshake with a close
+      // event (e.g. Node.js), so an error alone means the connection is lost.
+      ws.onerror = function () {
+        return ws === _this3.ws && _this3.handleConnectionLoss(true);
+      };
+      this.ws = ws;
+      this.authenticated = false;
+      this.connectingTimeoutId = setTimeout(function () {
+        return _this3.triggerConnectionTimeout();
+      }, (_this$options$connect = this.options.connectingTimeoutMs) !== null && _this$options$connect !== void 0 ? _this$options$connect : 10000);
+    }
   }, {
     key: "sendEnvelope",
     value: function sendEnvelope(envelope) {
-      var _this$ws$readyState, _this$ws2;
+      var _this$ws$readyState, _this$ws;
       if (this.isReady) {
         this.ws.send(JSON.stringify(envelope));
         return;
       }
-      this.handleEnvelopeSendError(envelope, new Error("Cannot send - client is not ready (state=".concat((_this$ws$readyState = (_this$ws2 = this.ws) === null || _this$ws2 === void 0 ? void 0 : _this$ws2.readyState) !== null && _this$ws$readyState !== void 0 ? _this$ws$readyState : '[no connection]', "; authenticated=").concat(this.authenticated, ")")));
+      this.handleEnvelopeSendError(envelope, new Error("Cannot send - client is not ready (state=".concat((_this$ws$readyState = (_this$ws = this.ws) === null || _this$ws === void 0 ? void 0 : _this$ws.readyState) !== null && _this$ws$readyState !== void 0 ? _this$ws$readyState : '[no connection]', "; authenticated=").concat(this.authenticated, ")")));
     }
   }, {
     key: "onMessage",
@@ -5563,35 +5606,110 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
         var isAuthenticated = envelope.type !== 'Bye';
         this.authenticated = isAuthenticated;
         if (isAuthenticated) {
+          this.reconnectAttempts = 0;
           this.startConnectionMonitor();
           this.settleConnect();
           this.emit(this.Event.connect);
           this.sendFromQueue();
         } else {
+          var _envelope$data;
           this.settleConnect(envelope.data);
+          var error = (_envelope$data = envelope.data) === null || _envelope$data === void 0 || (_envelope$data = _envelope$data.reason) === null || _envelope$data === void 0 ? void 0 : _envelope$data.error;
+          if ((error === null || error === void 0 ? void 0 : error.code) === 'AuthenticationException') {
+            // Invalid token - retrying would be rejected the same way.
+            this.handleConnectionLoss(false);
+            this.emit(this.Event.error, new Error("Authentication rejected: ".concat(error.message)));
+          }
         }
       }
     }
   }, {
     key: "onClose",
     value: function onClose(event) {
-      this.stopConnectionMonitor();
-      clearTimeout(this.connectingTimeoutId);
-      var reconnect = event.code !== 1000; // Connection was closed because of error
+      // Connection was closed because of error
+      this.handleConnectionLoss(event.code !== 1000);
+    }
+
+    /**
+     * Abandon the current socket without waiting for its close event (which
+     * may never come, or take minutes on a dead TCP connection), settle
+     * everything that depended on it and schedule a retry when requested.
+     */
+  }, {
+    key: "handleConnectionLoss",
+    value: function handleConnectionLoss(reconnect) {
+      this.releaseSocket(reconnect ? 3000 : 1000);
 
       // The server can no longer answer anything that was queued or in
       // flight, so settle those promises instead of leaving them pending.
       this.failPendingCommands(new Error('Connection closed before the command was answered'));
+      reconnect && (reconnect = this.reconnectEnabled);
       if (reconnect) {
         // Keep a pending connect() promise unsettled - the retry below is
         // expected to authenticate and will resolve it.
-        void this.connect();
+        this.scheduleReconnect();
       } else {
+        this.reconnectEnabled = false;
         this.settleConnect(new Error('Connection closed before authentication'));
       }
       this.emit(this.Event.disconnect, reconnect);
     }
 
+    /**
+     * Detach the current socket from the client and close it if it is still
+     * alive, together with all timers bound to it.
+     */
+  }, {
+    key: "releaseSocket",
+    value: function releaseSocket(closeCode) {
+      this.stopConnectionMonitor();
+      clearTimeout(this.connectingTimeoutId);
+      this.connectingTimeoutId = undefined;
+      this.authenticated = false;
+      var ws = this.ws;
+      this.ws = null;
+      if (!ws) {
+        return;
+      }
+      ws.onmessage = ws.onclose = ws.onerror = null;
+      if (ws.readyState === ws.CONNECTING || ws.readyState === ws.OPEN) {
+        try {
+          ws.close(closeCode);
+        } catch (_unused) {
+          // Nothing more can be done with a broken socket.
+        }
+      }
+    }
+  }, {
+    key: "scheduleReconnect",
+    value: function scheduleReconnect() {
+      var _this$options$reconne,
+        _this$options$reconne2,
+        _this$options$reconne3,
+        _this$options$reconne4,
+        _this4 = this;
+      this.cancelScheduledReconnect();
+      var minDelay = Math.max(0, (_this$options$reconne = (_this$options$reconne2 = this.options.reconnect) === null || _this$options$reconne2 === void 0 ? void 0 : _this$options$reconne2.minDelayMs) !== null && _this$options$reconne !== void 0 ? _this$options$reconne : 1000);
+      var maxDelay = Math.max(minDelay, (_this$options$reconne3 = (_this$options$reconne4 = this.options.reconnect) === null || _this$options$reconne4 === void 0 ? void 0 : _this$options$reconne4.maxDelayMs) !== null && _this$options$reconne3 !== void 0 ? _this$options$reconne3 : 30000);
+      var delay = Math.min(maxDelay, minDelay * Math.pow(2, Math.min(this.reconnectAttempts, 30)));
+      this.reconnectAttempts++;
+
+      // Random jitter (50-100% of the delay) keeps clients from reconnecting
+      // in lockstep after a server restart.
+      this.reconnectTimeoutId = setTimeout(function () {
+        _this4.reconnectTimeoutId = undefined;
+        _this4.connect()["catch"](function () {
+          return undefined;
+        });
+      }, delay / 2 + Math.random() * delay / 2);
+    }
+  }, {
+    key: "cancelScheduledReconnect",
+    value: function cancelScheduledReconnect() {
+      clearTimeout(this.reconnectTimeoutId);
+      this.reconnectTimeoutId = undefined;
+    }
+
     /**
      * Resolve (or reject, when an error is given) a pending connect() promise.
      * No-op when there is nothing pending.
@@ -5634,16 +5752,16 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
   }, {
     key: "sendFromQueue",
     value: function sendFromQueue() {
-      var _this3 = this;
+      var _this5 = this;
       // Send awaiting data to server
       var lastDelay = 0;
       var _loop = function _loop() {
-        var _this3$options$awaitQ;
-        var envelope = _this3.sendQueue[dataIndex];
+        var _this5$options$awaitQ;
+        var envelope = _this5.sendQueue[dataIndex];
         setTimeout(function () {
-          return _this3.sendEnvelope(envelope);
+          return _this5.sendEnvelope(envelope);
         }, lastDelay);
-        lastDelay += (_this3$options$awaitQ = _this3.options.awaitQueueSendDelayMs) !== null && _this3$options$awaitQ !== void 0 ? _this3$options$awaitQ : 500;
+        lastDelay += (_this5$options$awaitQ = _this5.options.awaitQueueSendDelayMs) !== null && _this5$options$awaitQ !== void 0 ? _this5$options$awaitQ : 500;
       };
       for (var dataIndex in this.sendQueue) {
         _loop();
@@ -5654,7 +5772,7 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
   }, {
     key: "triggerConnectionTimeout",
     value: function triggerConnectionTimeout() {
-      this.disconnect();
+      this.handleConnectionLoss(true);
       this.emit(this.Event.error, new Error('Connection timeout'));
     }
   }, {
@@ -5670,7 +5788,8 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
   }, {
     key: "startConnectionMonitor",
     value: function startConnectionMonitor() {
-      var _this4 = this;
+      var _this6 = this;
+      this.stopConnectionMonitor();
       if (!this.options.ping.enabled) {
         return;
       }
@@ -5679,30 +5798,32 @@ var WebSocketChatClient = /*#__PURE__*/function (_AbstractChatClient) {
         return WebSocketChatClient_regenerator().w(function (_context3) {
           while (1) switch (_context3.n) {
             case 0:
-              if (!(!_this4.isReady || _this4.inFlightPingTimeout)) {
+              if (!(!_this6.isReady || _this6.inFlightPingTimeout)) {
                 _context3.n = 1;
                 break;
               }
               return _context3.a(2);
             case 1:
-              if (!(Date.now() - _this4.lastReceivedMessageAt < _this4.options.ping.noActivityTimeoutMs)) {
+              if (!(Date.now() - _this6.lastReceivedMessageAt < _this6.options.ping.noActivityTimeoutMs)) {
                 _context3.n = 2;
                 break;
               }
               return _context3.a(2);
             case 2:
-              _this4.inFlightPingTimeout = setTimeout(function () {
-                _this4.inFlightPingTimeout = undefined;
-                _this4.ws.close(3000); // Service Restart (reconnect)
-              }, _this4.options.ping.pongBackTimeoutMs);
+              _this6.inFlightPingTimeout = setTimeout(function () {
+                _this6.inFlightPingTimeout = undefined;
+                // Closing a dead connection can hang in CLOSING for minutes,
+                // so drop it right away instead of waiting for the close event.
+                _this6.handleConnectionLoss(true);
+              }, _this6.options.ping.pongBackTimeoutMs);
 
               // A rejection here means the connection dropped while the ping was
-              // in flight; onClose already handles that, so just stop waiting.
-              _this4.send('Ping', {})["catch"](function () {
+              // in flight; the loss is already handled, so just stop waiting.
+              _this6.send('Ping', {})["catch"](function () {
                 return undefined;
               }).then(function () {
-                clearTimeout(_this4.inFlightPingTimeout);
-                _this4.inFlightPingTimeout = undefined;
+                clearTimeout(_this6.inFlightPingTimeout);
+                _this6.inFlightPingTimeout = undefined;
               });
             case 3:
               return _context3.a(2);