polfan-server-js-client 0.4.3 → 0.4.4

package/build/types/WebSocketChatClient.d.ts

@@ -16,14 +16,29 @@ export interface WebSocketClientOptions {
     ping?: {
         enabled?: boolean;
         /**
-         * Time without activity after which a ping will be sent. Default is 10 seconds.
+         * Time without activity after which a ping will be sent. Default is 15 seconds.
          */
         noActivityTimeoutMs?: number;
         /**
-         * Time to wait for a pong response before considering the connection dead. Default is 2 seconds.
+         * Time to wait for a pong response before considering the connection dead. Default is 5 seconds.
          */
         pongBackTimeoutMs?: number;
     };
+    /**
+     * Automatic reconnection. After the connection is lost (error, connecting timeout, missing pong
+     * or closure with a code other than 1000) the client retries indefinitely, waiting between attempts
+     * with an exponential backoff. Calling `disconnect()` stops retrying until the next `connect()`.
+     */
+    reconnect?: {
+        /**
+         * Delay before the first retry; each subsequent one doubles it. Default is 1 second.
+         */
+        minDelayMs?: number;
+        /**
+         * Upper limit of the delay between retries. Default is 30 seconds.
+         */
+        maxDelayMs?: number;
+    };
 }
 declare enum WebSocketChatClientEvent {
     connect = "connect",
@@ -50,14 +65,31 @@ export declare class WebSocketChatClient extends AbstractChatClient<Pick<WebSock
     protected pingMonitorInterval?: NodeJS.Timeout;
     protected inFlightPingTimeout: NodeJS.Timeout;
     protected lastReceivedMessageAt?: number;
+    protected reconnectEnabled: boolean;
+    protected reconnectTimeoutId?: any;
+    protected reconnectAttempts: number;
     constructor(options: WebSocketClientOptions);
     connect(): Promise<void>;
     disconnect(): void;
     send<CommandType extends keyof CommandsMap>(commandType: CommandType, commandData: CommandRequest<CommandType>): Promise<CommandResult<CommandResponse<CommandType>>>;
     get isReady(): boolean;
+    private openSocket;
     private sendEnvelope;
     private onMessage;
     private onClose;
+    /**
+     * 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.
+     */
+    private handleConnectionLoss;
+    /**
+     * Detach the current socket from the client and close it if it is still
+     * alive, together with all timers bound to it.
+     */
+    private releaseSocket;
+    private scheduleReconnect;
+    private cancelScheduledReconnect;
     /**
      * Resolve (or reject, when an error is given) a pending connect() promise.
      * No-op when there is nothing pending.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polfan-server-js-client",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "JavaScript client library for handling communication with Polfan chat server.",
   "author": "Jarosław Żak",
   "license": "MIT",

package/src/WebSocketChatClient.ts

@@ -1,7 +1,7 @@
 import {ObservableInterface} from "./EventTarget";
 import {AbstractChatClient, CommandRequest, CommandResult, CommandResponse, CommandsMap, EventsMap} from "./AbstractChatClient";
 import {ChatStateTracker} from "./state-tracker/ChatStateTracker";
-import {Envelope} from "./types/src";
+import {Bye, Envelope} from "./types/src";
 
 export interface WebSocketClientOptions {
     url: string;
@@ -16,14 +16,29 @@ export interface WebSocketClientOptions {
     ping?: {
         enabled?: boolean;
         /**
-         * Time without activity after which a ping will be sent. Default is 10 seconds.
+         * Time without activity after which a ping will be sent. Default is 15 seconds.
          */
         noActivityTimeoutMs?: number;
         /**
-         * Time to wait for a pong response before considering the connection dead. Default is 2 seconds.
+         * Time to wait for a pong response before considering the connection dead. Default is 5 seconds.
          */
         pongBackTimeoutMs?: number;
     },
+    /**
+     * Automatic reconnection. After the connection is lost (error, connecting timeout, missing pong
+     * or closure with a code other than 1000) the client retries indefinitely, waiting between attempts
+     * with an exponential backoff. Calling `disconnect()` stops retrying until the next `connect()`.
+     */
+    reconnect?: {
+        /**
+         * Delay before the first retry; each subsequent one doubles it. Default is 1 second.
+         */
+        minDelayMs?: number;
+        /**
+         * Upper limit of the delay between retries. Default is 30 seconds.
+         */
+        maxDelayMs?: number;
+    },
 }
 
 enum WebSocketChatClientEvent {
@@ -53,6 +68,9 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
     protected pingMonitorInterval?: NodeJS.Timeout;
     protected inFlightPingTimeout: NodeJS.Timeout;
     protected lastReceivedMessageAt?: number;
+    protected reconnectEnabled: boolean = false;
+    protected reconnectTimeoutId?: any;
+    protected reconnectAttempts: number = 0;
 
     public constructor(private readonly options: WebSocketClientOptions) {
         super();
@@ -67,6 +85,10 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
     }
 
     public async connect(): Promise<void> {
+        this.reconnectEnabled = true;
+        // A manual call does not wait for a scheduled retry.
+        this.cancelScheduledReconnect();
+
         if (this.isOpenWsState() || this.isConnectingWsState()) {
             return this.connectPromise ?? undefined;
         }
@@ -74,27 +96,33 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
         // 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.connectPromise ??= new Promise<void>((...args) => this.authenticatedResolvers = args);
-
-        const params = new URLSearchParams(this.options.queryParams ?? {});
-        params.set('token', this.options.token);
+        if (! this.connectPromise) {
+            this.connectPromise = new Promise<void>((...args) => this.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(() => undefined);
+        }
 
-        this.ws = new WebSocket(`${this.options.url}?${params}`);
-        this.ws.onclose = ev => this.onClose(ev);
-        this.ws.onmessage = ev => this.onMessage(ev);
-        this.connectingTimeoutId = setTimeout(
-            () => this.triggerConnectionTimeout(),
-            this.options.connectingTimeoutMs ?? 10000
-        );
-        this.authenticated = false;
+        const connectPromise = this.connectPromise;
+        this.openSocket();
 
-        return this.connectPromise;
+        return connectPromise;
     }
 
     public disconnect(): void {
+        const 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?.close(1000); // Normal closure
-        this.ws = null;
+        this.settleConnect(new Error('Client disconnected before authentication'));
+
+        if (wasActive) {
+            this.emit(this.Event.disconnect, false);
+        }
     }
 
     public async send<CommandType extends keyof CommandsMap>(commandType: CommandType, commandData: CommandRequest<CommandType>):
@@ -115,6 +143,37 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
         return this.isOpenWsState() && this.authenticated;
     }
 
+    private openSocket(): void {
+        // Never leave a previous socket attached (e.g. one still closing).
+        this.releaseSocket(1000);
+
+        const params = new URLSearchParams(this.options.queryParams ?? {});
+        params.set('token', this.options.token);
+
+        let ws: WebSocket;
+        try {
+            ws = new WebSocket(`${this.options.url}?${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 = ev => ws === this.ws && this.onMessage(ev);
+        ws.onclose = ev => ws === this.ws && this.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 = () => ws === this.ws && this.handleConnectionLoss(true);
+
+        this.ws = ws;
+        this.authenticated = false;
+        this.connectingTimeoutId = setTimeout(
+            () => this.triggerConnectionTimeout(),
+            this.options.connectingTimeoutMs ?? 10000
+        );
+    }
+
     private sendEnvelope(envelope: Envelope): void {
         if (this.isReady) {
             this.ws.send(JSON.stringify(envelope));
@@ -139,36 +198,104 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
             const isAuthenticated = envelope.type !== 'Bye';
             this.authenticated = isAuthenticated;
             if (isAuthenticated) {
+                this.reconnectAttempts = 0;
                 this.startConnectionMonitor();
                 this.settleConnect();
                 this.emit(this.Event.connect);
                 this.sendFromQueue();
             } else {
                 this.settleConnect(envelope.data);
+
+                const error = (envelope.data as Bye)?.reason?.error;
+                if (error?.code === 'AuthenticationException') {
+                    // Invalid token - retrying would be rejected the same way.
+                    this.handleConnectionLoss(false);
+                    this.emit(this.Event.error, new Error(`Authentication rejected: ${error.message}`));
+                }
             }
         }
     }
 
     private onClose(event: CloseEvent): void {
-        this.stopConnectionMonitor();
-        clearTimeout(this.connectingTimeoutId);
-        const 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.
+     */
+    private handleConnectionLoss(reconnect: boolean): void {
+        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 &&= 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.
+     */
+    private releaseSocket(closeCode: number): void {
+        this.stopConnectionMonitor();
+        clearTimeout(this.connectingTimeoutId);
+        this.connectingTimeoutId = undefined;
+        this.authenticated = false;
+
+        const 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 {
+                // Nothing more can be done with a broken socket.
+            }
+        }
+    }
+
+    private scheduleReconnect(): void {
+        this.cancelScheduledReconnect();
+
+        const minDelay = Math.max(0, this.options.reconnect?.minDelayMs ?? 1000);
+        const maxDelay = Math.max(minDelay, this.options.reconnect?.maxDelayMs ?? 30000);
+        const delay = Math.min(maxDelay, minDelay * 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(() => {
+            this.reconnectTimeoutId = undefined;
+            this.connect().catch(() => undefined);
+        }, delay / 2 + Math.random() * delay / 2);
+    }
+
+    private cancelScheduledReconnect(): void {
+        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.
@@ -214,7 +341,7 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
     }
 
     private triggerConnectionTimeout(): void {
-        this.disconnect();
+        this.handleConnectionLoss(true);
         this.emit(this.Event.error, new Error('Connection timeout'));
     }
 
@@ -227,6 +354,8 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
     }
 
     private startConnectionMonitor(): void {
+        this.stopConnectionMonitor();
+
         if (!this.options.ping!.enabled) {
             return;
         }
@@ -244,11 +373,13 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
 
             this.inFlightPingTimeout = setTimeout(() => {
                 this.inFlightPingTimeout = undefined;
-                this.ws.close(3000); // Service Restart (reconnect)
+                // Closing a dead connection can hang in CLOSING for minutes,
+                // so drop it right away instead of waiting for the close event.
+                this.handleConnectionLoss(true);
             }, this.options.ping.pongBackTimeoutMs);
 
             // A rejection here means the connection dropped while the ping was
-            // in flight; onClose already handles that, so just stop waiting.
+            // in flight; the loss is already handled, so just stop waiting.
             this.send('Ping', {}).catch(() => undefined).then(() => {
                 clearTimeout(this.inFlightPingTimeout);
                 this.inFlightPingTimeout = undefined;
@@ -266,4 +397,4 @@ export class WebSocketChatClient extends AbstractChatClient<Pick<WebSocketEventM
             this.pingMonitorInterval = undefined;
         }
     }
-}
+}