stream-chat 9.50.3 → 10.0.0-rc.2

package/src/connection.ts

@@ -13,9 +13,14 @@ import {
   buildWsSuccessAfterFailureInsight,
   postInsights,
 } from './insights';
-import type { ConnectAPIResponse, ConnectionOpen, LogLevel, UR } from './types';
+import { chatLoggerSystem } from './logger';
+import type { ConnectAPIResponse, ConnectionOpen, EventPayload } from './types';
 import type { StreamChat } from './client';
 import type { APIError } from './errors';
+import { decodeWSEvent } from './gen/model-decoders/event-decoder-mapping';
+import type { WSEvent } from './gen/models';
+
+const logger = chatLoggerSystem.getLogger('connection');
 
 // Type guards to check WebSocket error type
 const isCloseEvent = (
@@ -27,15 +32,16 @@ const isErrorEvent = (
 ): res is WebSocket.ErrorEvent => (res as WebSocket.ErrorEvent).error !== undefined;
 
 /**
- * StableWSConnection - A WS connection that reconnects upon failure.
+ * A WS connection that reconnects upon failure.
+ *
  * - the browser will sometimes report that you're online or offline
  * - the WS connection can break and fail (there is a 30s health check)
  * - sometimes your WS connection will seem to work while the user is in fact offline
- * - to speed up online/offline detection you can use the window.addEventListener('offline');
+ * - to speed up online/offline detection you can use the `window.addEventListener('offline')`
  *
  * There are 4 ways in which a connection can become unhealthy:
- * - websocket.onerror is called
- * - websocket.onclose is called
+ * - WebSocket.onerror is called
+ * - WebSocket.onclose is called
  * - the health check fails and no event is received for ~40 seconds
  * - the browser indicates the connection is now offline
  *
@@ -99,18 +105,15 @@ export class StableWSConnection {
     addConnectionEventListeners(this.onlineStatusChanged);
   }
 
-  _log(msg: string, extra: UR = {}, level: LogLevel = 'info') {
-    this.client.logger(level, 'connection:' + msg, { tags: ['connection'], ...extra });
-  }
-
   setClient(client: StreamChat) {
     this.client = client;
   }
 
   /**
-   * connect - Connect to the WS URL
-   * the default 15s timeout allows between 2~3 tries
-   * @return {ConnectAPIResponse<ChannelType, CommandType, UserType>} Promise that completes once the first health check message is received
+   * Connects to the WS URL. The default 15s timeout allows between 2 and 3 tries.
+   *
+   * @param timeout - Connect timeout in milliseconds (optional, defaults to `15000`).
+   * @returns A promise that resolves once the first health check message is received.
    */
   async connect(timeout = 15000) {
     if (this.isConnecting) {
@@ -125,8 +128,9 @@ export class StableWSConnection {
       const healthCheck = await this._connect();
       this.consecutiveFailures = 0;
 
-      this._log(`connect() - Established ws connection with healthcheck: ${healthCheck}`);
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      logger
+        .withExtraTags('connect')
+        .info(`Established a WebSocket connection. Health check: ${healthCheck}.`);
     } catch (error: any) {
       this.isHealthy = false;
       this.consecutiveFailures += 1;
@@ -134,9 +138,11 @@ export class StableWSConnection {
       const e = error as APIError;
 
       if (e.code === chatCodes.TOKEN_EXPIRED && !this.client.tokenManager.isStatic()) {
-        this._log(
-          'connect() - WS failure due to expired token, so going to try to reload token and reconnect',
-        );
+        logger
+          .withExtraTags('connect')
+          .warn(
+            'WebSocket connection failed due to an expired token. Reloading the token and reconnecting.',
+          );
         this._reconnect({ refreshToken: true });
       } else if (!e.isWSFailure) {
         // API rejected the connection and we should not retry
@@ -157,7 +163,8 @@ export class StableWSConnection {
   /**
    * _waitForHealthy polls the promise connection to see if its resolved until it times out
    * the default 15s timeout allows between 2~3 tries
-   * @param timeout duration(ms)
+   *
+   * @param timeout - duration (ms)
    */
   _waitForHealthy(timeout = 15000) {
     return Promise.race([
@@ -166,7 +173,6 @@ export class StableWSConnection {
         for (let i = 0; i <= timeout; i += interval) {
           try {
             return await this.connectionOpen;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
           } catch (error: any) {
             if (i === timeout) {
               throw new Error(
@@ -198,7 +204,8 @@ export class StableWSConnection {
   }
 
   /**
-   * Builds and returns the url for websocket.
+   * Builds and returns the URL for the WebSocket connection.
+   *
    * @private
    * @returns url string
    */
@@ -220,11 +227,14 @@ export class StableWSConnection {
   };
 
   /**
-   * disconnect - Disconnect the connection and doesn't recover...
+   * Disconnects the connection without attempting to recover.
    *
+   * @param timeout - Optional timeout in milliseconds to wait for the close frame from the server.
    */
   disconnect(timeout?: number) {
-    this._log(`disconnect() - Closing the websocket connection for wsID ${this.wsID}`);
+    logger
+      .withExtraTags('disconnect')
+      .info(`Closing the WebSocket connection for wsID ${this.wsID}.`);
 
     this.wsID += 1;
     this.isConnecting = false;
@@ -255,29 +265,33 @@ export class StableWSConnection {
     if (ws && ws.close && ws.readyState === ws.OPEN) {
       isClosedPromise = new Promise((resolve) => {
         const onclose = (event: WebSocket.CloseEvent) => {
-          this._log(
-            `disconnect() - resolving isClosedPromise ${event ? 'with' : 'without'} close frame`,
-            { event },
-          );
+          logger
+            .withExtraTags('disconnect')
+            .debug(
+              `Resolving the close promise ${event ? 'with' : 'without'} a close frame.`,
+              { event },
+            );
           resolve();
         };
 
         ws.onclose = onclose;
-        // In case we don't receive close frame websocket server in time,
+        // In case we don't receive a close frame from the WebSocket server in time,
         // lets not wait for more than 1 seconds.
         setTimeout(onclose, timeout != null ? timeout : 1000);
       });
 
-      this._log(
-        `disconnect() - Manually closed connection by calling client.disconnect()`,
-      );
+      logger
+        .withExtraTags('disconnect')
+        .debug('Manually closing the connection via client.disconnect().');
 
       ws.close(
         chatCodes.WS_CLOSED_SUCCESS,
         'Manually closed connection by calling client.disconnect()',
       );
     } else {
-      this._log(`disconnect() - ws connection doesn't exist or it is already closed.`);
+      logger
+        .withExtraTags('disconnect')
+        .debug('The WebSocket connection does not exist or is already closed.');
       isClosedPromise = Promise.resolve();
     }
 
@@ -287,9 +301,9 @@ export class StableWSConnection {
   }
 
   /**
-   * _connect - Connect to the WS endpoint
+   * Connects to the WS endpoint.
    *
-   * @return {ConnectAPIResponse<ChannelType, CommandType, UserType>} Promise that completes once the first health check message is received
+   * @returns A promise that resolves once the first health check message is received.
    */
   async _connect() {
     if (
@@ -302,7 +316,7 @@ export class StableWSConnection {
     this.client.insightMetrics.connectionStartTimestamp = new Date().getTime();
     let isTokenReady = false;
     try {
-      this._log(`_connect() - waiting for token`);
+      logger.withExtraTags('_connect').debug('Waiting for the auth token.');
       await this.client.tokenManager.tokenReady();
       isTokenReady = true;
     } catch (e) {
@@ -311,13 +325,15 @@ export class StableWSConnection {
 
     try {
       if (!isTokenReady) {
-        this._log(`_connect() - tokenProvider failed before, so going to retry`);
+        logger
+          .withExtraTags('_connect')
+          .warn('The token provider failed previously. Retrying.');
         await this.client.tokenManager.loadToken();
       }
 
       this._setupConnectionPromise();
       const wsURL = this._buildUrl();
-      this._log(`_connect() - Connecting to ${wsURL}`, {
+      logger.withExtraTags('_connect').info(`Connecting to ${wsURL}.`, {
         wsURL,
         requestID: this.requestID,
       });
@@ -343,10 +359,11 @@ export class StableWSConnection {
         }
         return response;
       }
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } catch (error: any) {
       this.isConnecting = false;
-      this._log(`_connect() - Error - `, error);
+      logger
+        .withExtraTags('_connect')
+        .warn('An error occurred while connecting.', { error });
       if (this.client.options.enableInsights) {
         this.client.insightMetrics.wsConsecutiveFailures++;
         this.client.insightMetrics.wsTotalFailures++;
@@ -362,21 +379,22 @@ export class StableWSConnection {
   }
 
   /**
-   * _reconnect - Retry the connection to WS endpoint
-   *
-   * @param {{ interval?: number; refreshToken?: boolean }} options Following options are available
+   * Retries the connection to the WS endpoint.
    *
-   * - `interval`	{int}			number of ms that function should wait before reconnecting
-   * - `refreshToken` {boolean}	reload/refresh user token be refreshed before attempting reconnection.
+   * @param options - Reconnect options.
+   * @param options.interval - Number of milliseconds to wait before reconnecting.
+   * @param options.refreshToken - Reload/refresh the user token before attempting to reconnect.
    */
   async _reconnect(
     options: { interval?: number; refreshToken?: boolean } = {},
   ): Promise<void> {
-    this._log('_reconnect() - Initiating the reconnect');
+    logger.withExtraTags('_reconnect').info('Initiating a reconnect.');
 
     // only allow 1 connection at the time
     if (this.isConnecting || this.isHealthy) {
-      this._log('_reconnect() - Abort (1) since already connecting or healthy');
+      logger
+        .withExtraTags('_reconnect')
+        .debug('Aborting reconnect: already connecting or healthy (check 1).');
       return;
     }
 
@@ -392,16 +410,22 @@ export class StableWSConnection {
     // Check once again if by some other call to _reconnect is active or connection is
     // already restored, then no need to proceed.
     if (this.isConnecting || this.isHealthy) {
-      this._log('_reconnect() - Abort (2) since already connecting or healthy');
+      logger
+        .withExtraTags('_reconnect')
+        .debug('Aborting reconnect: already connecting or healthy (check 2).');
       return;
     }
 
     if (this.isDisconnected && this.client.options.enableWSFallback) {
-      this._log('_reconnect() - Abort (3) since disconnect() is called');
+      logger
+        .withExtraTags('_reconnect')
+        .debug('Aborting reconnect: disconnect() was called.');
       return;
     }
 
-    this._log('_reconnect() - Destroying current WS connection');
+    logger
+      .withExtraTags('_reconnect')
+      .info('Destroying the current WebSocket connection.');
 
     // cleanup the old connection
     this._destroyCurrentWSConnection();
@@ -412,12 +436,11 @@ export class StableWSConnection {
 
     try {
       await this._connect();
-      this._log('_reconnect() - Waiting for recoverCallBack');
+      logger.withExtraTags('_reconnect').debug('Waiting for the recover callback.');
       await this.client.recoverState();
-      this._log('_reconnect() - Finished recoverCallBack');
+      logger.withExtraTags('_reconnect').debug('Finished the recover callback.');
 
       this.consecutiveFailures = 0;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } catch (error: any) {
       this.isHealthy = false;
       this.consecutiveFailures += 1;
@@ -425,60 +448,71 @@ export class StableWSConnection {
         error.code === chatCodes.TOKEN_EXPIRED &&
         !this.client.tokenManager.isStatic()
       ) {
-        this._log(
-          '_reconnect() - WS failure due to expired token, so going to try to reload token and reconnect',
-        );
+        logger
+          .withExtraTags('_reconnect')
+          .warn(
+            'WebSocket connection failed due to an expired token. Reloading the token and reconnecting.',
+          );
 
         return this._reconnect({ refreshToken: true });
       }
 
       // reconnect on WS failures, don't reconnect if there is a code bug
       if (error.isWSFailure) {
-        this._log('_reconnect() - WS failure, so going to try to reconnect');
+        logger
+          .withExtraTags('_reconnect')
+          .warn('WebSocket connection failed. Retrying the reconnect.');
 
         this._reconnect();
       }
     }
-    this._log('_reconnect() - == END ==');
+    logger.withExtraTags('_reconnect').debug('Reconnect attempt finished.');
   }
 
   /**
-   * onlineStatusChanged - this function is called when the browser connects or disconnects from the internet.
-   *
-   * @param {Event} event Event with type online or offline
+   * Called when the browser connects or disconnects from the internet.
    *
+   * @param event - The DOM event whose `type` is `'online'` or `'offline'`.
    */
   onlineStatusChanged = (event: Event) => {
     if (event.type === 'offline') {
       // mark the connection as down
-      this._log('onlineStatusChanged() - Status changing to offline');
+      logger
+        .withExtraTags('onlineStatusChanged')
+        .info('Network status changed to offline.');
       this._setHealth(false);
     } else if (event.type === 'online') {
       // retry right now...
       // We check this.isHealthy, not sure if it's always
       // smart to create a new WS connection if the old one is still up and running.
       // it's possible we didn't miss any messages, so this process is just expensive and not needed.
-      this._log(
-        `onlineStatusChanged() - Status changing to online. isHealthy: ${this.isHealthy}`,
-      );
+      logger
+        .withExtraTags('onlineStatusChanged')
+        .info(`Network status changed to online. isHealthy: ${this.isHealthy}.`);
       if (!this.isHealthy) {
         this._reconnect({ interval: 10 });
       }
     }
   };
 
-  onopen = (wsID: number) => {
-    if (this.wsID !== wsID) return;
+  onopen = (wsId: number) => {
+    if (this.wsID !== wsId) return;
 
-    this._log('onopen() - onopen callback', { wsID });
+    logger.withExtraTags('onopen').debug('WebSocket onopen callback fired.', {
+      wsID: wsId,
+    });
   };
 
-  onmessage = (wsID: number, event: WebSocket.MessageEvent) => {
-    if (this.wsID !== wsID) return;
+  onmessage = (wsId: number, event: WebSocket.MessageEvent) => {
+    if (this.wsID !== wsId) return;
 
-    this._log('onmessage() - onmessage callback', { event, wsID });
+    logger.withExtraTags('onmessage').trace('WebSocket onmessage callback fired.', {
+      event,
+      wsID: wsId,
+    });
     if (typeof event.data !== 'string') return;
     const data = JSON.parse(event.data);
+    const decodedData = decodeWSEvent(data) as WSEvent;
 
     // we wait till the first message before we consider the connection open..
     // the reason for this is that auth errors and similar errors trigger a ws.onopen and immediately
@@ -490,7 +524,7 @@ export class StableWSConnection {
         return;
       }
 
-      this.resolvePromise?.(data);
+      this.resolvePromise?.(decodedData as EventPayload<'health.check'>);
       this._setHealth(true);
     }
 
@@ -501,14 +535,19 @@ export class StableWSConnection {
       this.scheduleNextPing();
     }
 
-    this.client.dispatchEvent(data);
+    this.client.dispatchEvent(decodedData);
     this.scheduleConnectionCheck();
   };
 
-  onclose = (wsID: number, event: WebSocket.CloseEvent) => {
-    if (this.wsID !== wsID) return;
+  onclose = (wsId: number, event: WebSocket.CloseEvent) => {
+    if (this.wsID !== wsId) return;
 
-    this._log('onclose() - onclose callback - ' + event.code, { event, wsID });
+    logger
+      .withExtraTags('onclose')
+      .debug(`WebSocket onclose callback fired with code ${event.code}.`, {
+        event,
+        wsID: wsId,
+      });
 
     if (event.code === chatCodes.WS_CLOSED_SUCCESS) {
       // this is a permanent error raised by stream..
@@ -523,7 +562,9 @@ export class StableWSConnection {
       error.target = event.target;
 
       this.rejectPromise?.(error);
-      this._log(`onclose() - WS connection reject with error ${event.reason}`, { event });
+      logger
+        .withExtraTags('onclose')
+        .warn(`The WebSocket connection was rejected: ${event.reason}.`, { event });
     } else {
       this.consecutiveFailures += 1;
       this.totalFailures += 1;
@@ -532,15 +573,19 @@ export class StableWSConnection {
 
       this.rejectPromise?.(this._errorFromWSEvent(event));
 
-      this._log(`onclose() - WS connection closed. Calling reconnect ...`, { event });
+      logger
+        .withExtraTags('onclose')
+        .warn('The WebSocket connection was closed. Attempting to reconnect.', {
+          event,
+        });
 
       // reconnect if its an abnormal failure
       this._reconnect();
     }
   };
 
-  onerror = (wsID: number, event: WebSocket.ErrorEvent) => {
-    if (this.wsID !== wsID) return;
+  onerror = (wsId: number, event: WebSocket.ErrorEvent) => {
+    if (this.wsID !== wsId) return;
 
     this.consecutiveFailures += 1;
     this.totalFailures += 1;
@@ -548,17 +593,17 @@ export class StableWSConnection {
     this.isConnecting = false;
 
     this.rejectPromise?.(this._errorFromWSEvent(event));
-    this._log(`onerror() - WS connection resulted into error`, { event });
+    logger
+      .withExtraTags('onerror')
+      .warn('The WebSocket connection raised an error.', { event });
 
     this._reconnect();
   };
 
   /**
-   * _setHealth - Sets the connection to healthy or unhealthy.
-   * Broadcasts an event in case the connection status changed.
-   *
-   * @param {boolean} healthy boolean indicating if the connection is healthy or not
+   * Sets the connection to healthy or unhealthy. Broadcasts an event if the connection status changed.
    *
+   * @param healthy - Whether the connection is healthy.
    */
   _setHealth = (healthy: boolean) => {
     if (healthy === this.isHealthy) return;
@@ -578,8 +623,11 @@ export class StableWSConnection {
   };
 
   /**
-   * _errorFromWSEvent - Creates an error object for the WS event
+   * Creates an error object for the WS event.
    *
+   * @param event - The raw WebSocket close / data / error event.
+   * @param isWSFailure - Whether the underlying cause is a WebSocket failure (optional, defaults to `true`).
+   * @returns A normalized error describing the WS failure.
    */
   _errorFromWSEvent = (
     event: WebSocket.CloseEvent | WebSocket.Data | WebSocket.ErrorEvent,
@@ -601,7 +649,9 @@ export class StableWSConnection {
     }
 
     // Keeping this `warn` level log, to avoid cluttering of error logs from ws failures.
-    this._log(`_errorFromWSEvent() - WS failed with code ${code}`, { event }, 'warn');
+    logger
+      .withExtraTags('_errorFromWSEvent')
+      .warn(`The WebSocket failed with code ${code}.`, { event });
 
     const error = new Error(
       `WS failed with code ${code} and reason - ${message}`,
@@ -621,8 +671,7 @@ export class StableWSConnection {
   };
 
   /**
-   * _destroyCurrentWSConnection - Removes the current WS connection
-   *
+   * Removes the current WS connection.
    */
   _destroyCurrentWSConnection() {
     // increment the ID, meaning we will ignore all messages from the old
@@ -638,7 +687,7 @@ export class StableWSConnection {
   }
 
   /**
-   * _setupPromise - sets up the this.connectOpen promise
+   * Sets up the `this.connectionOpen` promise.
    */
   _setupConnectionPromise = () => {
     this.isResolved = false;
@@ -650,7 +699,7 @@ export class StableWSConnection {
   };
 
   /**
-   * Schedules a next health check ping for websocket.
+   * Schedules the next health check ping for the WebSocket connection.
    */
   scheduleNextPing = () => {
     if (this.healthCheckTimeoutRef) {
@@ -660,7 +709,7 @@ export class StableWSConnection {
     // 30 seconds is the recommended interval (messenger uses this)
     this.healthCheckTimeoutRef = setTimeout(() => {
       // send the healthcheck.., server replies with a health check event
-      const data = [{ type: 'health.check', client_id: this.client.clientID }];
+      const data = [{ type: 'health.check', client_id: this.client.clientId }];
       // try to send on the connection
       try {
         this.ws?.send(JSON.stringify(data));
@@ -671,9 +720,9 @@ export class StableWSConnection {
   };
 
   /**
-   * scheduleConnectionCheck - schedules a check for time difference between last received event and now.
-   * If the difference is more than 35 seconds, it means our health check logic has failed and websocket needs
-   * to be reconnected.
+   * Schedules a check for the time difference between the last received event and now. If the
+   * difference is more than 35 seconds, it means our health check logic has failed and the
+   * WebSocket needs to be reconnected.
    */
   scheduleConnectionCheck = () => {
     if (this.connectionCheckTimeoutRef) {
@@ -686,7 +735,9 @@ export class StableWSConnection {
         this.lastEvent &&
         now.getTime() - this.lastEvent.getTime() > this.connectionCheckTimeout
       ) {
-        this._log('scheduleConnectionCheck - going to reconnect');
+        logger
+          .withExtraTags('scheduleConnectionCheck')
+          .warn('No events received within the health-check window. Reconnecting.');
         this._setHealth(false);
         this._reconnect();
       }