@stream-io/video-client 1.5.0 → 1.6.0-0

package/src/StreamSfuClient.ts

@@ -1,20 +1,20 @@
-import type { WebSocket } from 'ws';
-import type {
-  FinishedUnaryCall,
-  MethodInfo,
-  NextUnaryFn,
-  RpcInterceptor,
-  RpcOptions,
-  UnaryCall,
-} from '@protobuf-ts/runtime-rpc';
 import { SignalServerClient } from './gen/video/sfu/signal_rpc/signal.client';
-import { createSignalClient, withHeaders } from './rpc';
+import {
+  createSignalClient,
+  retryable,
+  withHeaders,
+  withRequestLogger,
+} from './rpc';
 import {
   createWebSocketSignalChannel,
   Dispatcher,
   IceTrickleBuffer,
 } from './rtc';
-import { JoinRequest, SfuRequest } from './gen/video/sfu/event/events';
+import {
+  JoinRequest,
+  JoinResponse,
+  SfuRequest,
+} from './gen/video/sfu/event/events';
 import {
   ICERestartRequest,
   SendAnswerRequest,
@@ -23,19 +23,16 @@ import {
   TrackSubscriptionDetails,
   UpdateMuteStatesRequest,
 } from './gen/video/sfu/signal_rpc/signal';
+import { ICETrickle, TrackType } from './gen/video/sfu/models/models';
+import { generateUUIDv4, sleep } from './coordinator/connection/utils';
+import { Credentials } from './gen/coordinator';
+import { Logger } from './coordinator/connection/types';
+import { getLogger, getLogLevel } from './logger';
+import { withoutConcurrency } from './helpers/concurrency';
 import {
-  Error as SfuError,
-  ICETrickle,
-  TrackType,
-} from './gen/video/sfu/models/models';
-import {
-  generateUUIDv4,
-  retryInterval,
-  sleep,
-} from './coordinator/connection/utils';
-import { SFUResponse } from './gen/coordinator';
-import { LogLevel, Logger } from './coordinator/connection/types';
-import { getLogger } from './logger';
+  promiseWithResolvers,
+  PromiseWithResolvers,
+} from './helpers/withResolvers';
 
 export type StreamSfuClientConstructor = {
   /**
@@ -44,20 +41,31 @@ export type StreamSfuClientConstructor = {
   dispatcher: Dispatcher;
 
   /**
-   * The SFU server to connect to.
+   * The credentials to use for the connection.
+   */
+  credentials: Credentials;
+
+  /**
+   * `sessionId` to use for the connection.
    */
-  sfuServer: SFUResponse;
+  sessionId?: string;
 
   /**
-   * The JWT token to use for authentication.
+   * A log tag to use for logging. Useful for debugging multiple instances.
    */
-  token: string;
+  logTag: string;
 
   /**
-   * An optional `sessionId` to use for the connection.
-   * If not provided, a random UUIDv4 will be generated.
+   * The timeout in milliseconds for waiting for the `joinResponse`.
+   * Defaults to 5000ms.
    */
-  sessionId?: string;
+  joinResponseTimeout?: number;
+
+  /**
+   * Callback for when the WebSocket connection is closed.
+   * @param event the event.
+   */
+  onSignalClose?: (event: CloseEvent) => void;
 };
 
 /**
@@ -66,9 +74,10 @@ export type StreamSfuClientConstructor = {
 export class StreamSfuClient {
   /**
    * A buffer for ICE Candidates that are received before
-   * the PeerConnections are ready to handle them.
+   * the Publisher and Subscriber Peer Connections are ready to handle them.
    */
   readonly iceTrickleBuffer = new IceTrickleBuffer();
+
   /**
    * The `sessionId` of the currently connected participant.
    */
@@ -79,46 +88,53 @@ export class StreamSfuClient {
    */
   readonly edgeName: string;
 
-  /**
-   * The current token used for authenticating against the SFU.
-   */
-  readonly token: string;
-
-  /**
-   * The SFU server details the current client is connected to.
-   */
-  readonly sfuServer: SFUResponse;
-
   /**
    * Holds the current WebSocket connection to the SFU.
    */
-  signalWs: WebSocket;
+  private signalWs!: WebSocket;
 
   /**
    * Promise that resolves when the WebSocket connection is ready (open).
    */
-  signalReady: Promise<WebSocket>;
-
-  /**
-   * A flag indicating whether the client is currently migrating away
-   * from this SFU.
-   */
-  isMigratingAway = false;
+  private signalReady!: Promise<WebSocket>;
 
   /**
-   * A flag indicating that the client connection is broken for the current
-   * client and that a fast-reconnect with a new client should be attempted.
+   * Flag to indicate if the client is in the process of leaving the call.
+   * This is set to `true` when the user initiates the leave process.
    */
-  isFastReconnecting = false;
+  isLeaving = false;
 
   private readonly rpc: SignalServerClient;
   private keepAliveInterval?: NodeJS.Timeout;
   private connectionCheckTimeout?: NodeJS.Timeout;
+  private migrateAwayTimeout?: NodeJS.Timeout;
   private pingIntervalInMs = 10 * 1000;
   private unhealthyTimeoutInMs = this.pingIntervalInMs + 5 * 1000;
   private lastMessageTimestamp?: Date;
+  private readonly restoreWebSocketConcurrencyTag = Symbol('recoverWebSocket');
   private readonly unsubscribeIceTrickle: () => void;
+  private readonly onSignalClose: ((event: CloseEvent) => void) | undefined;
   private readonly logger: Logger;
+  private readonly logTag: string;
+  private readonly credentials: Credentials;
+  private readonly dispatcher: Dispatcher;
+  private readonly joinResponseTimeout?: number;
+  /**
+   * Promise that resolves when the JoinResponse is received.
+   * Rejects after a certain threshold if the response is not received.
+   */
+  joinResponseTask = promiseWithResolvers<JoinResponse>();
+
+  /**
+   * Promise that resolves when the migration is complete.
+   * Rejects after a certain threshold if the migration is not complete.
+   */
+  private migrationTask?: PromiseWithResolvers<void>;
+
+  /**
+   * A controller to abort the current requests.
+   */
+  private readonly abortController = new AbortController();
 
   /**
    * The normal closure code. Used for controlled shutdowns.
@@ -131,246 +147,322 @@ export class StreamSfuClient {
    */
   static ERROR_CONNECTION_UNHEALTHY = 4001;
 
-  /**
-   * The error code used when the SFU connection is broken.
-   * Usually, this means that the WS connection has been closed unexpectedly.
-   * This error code is used to announce a fast-reconnect.
-   */
-  static ERROR_CONNECTION_BROKEN = 4002; // used in fast-reconnects
-
   /**
    * Constructs a new SFU client.
-   *
-   * @param dispatcher the event dispatcher to use.
-   * @param sfuServer the SFU server to connect to.
-   * @param token the JWT token to use for authentication.
-   * @param sessionId the `sessionId` of the currently connected participant.
    */
   constructor({
     dispatcher,
-    sfuServer,
-    token,
+    credentials,
     sessionId,
+    logTag,
+    joinResponseTimeout = 5000,
+    onSignalClose,
   }: StreamSfuClientConstructor) {
+    this.dispatcher = dispatcher;
     this.sessionId = sessionId || generateUUIDv4();
-    this.sfuServer = sfuServer;
-    this.edgeName = sfuServer.edge_name;
-    this.token = token;
-    this.logger = getLogger(['sfu-client']);
-    const logInterceptor: RpcInterceptor = {
-      interceptUnary: (
-        next: NextUnaryFn,
-        method: MethodInfo,
-        input: object,
-        options: RpcOptions,
-      ): UnaryCall => {
-        this.logger('trace', `Calling SFU RPC method ${method.name}`, {
-          input,
-          options,
-        });
-        return next(method, input, options);
-      },
-    };
+    this.onSignalClose = onSignalClose;
+    this.credentials = credentials;
+    const { server, token } = credentials;
+    this.edgeName = server.edge_name;
+    this.joinResponseTimeout = joinResponseTimeout;
+    this.logTag = logTag;
+    this.logger = getLogger(['sfu-client', logTag]);
     this.rpc = createSignalClient({
-      baseUrl: sfuServer.url,
+      baseUrl: server.url,
       interceptors: [
         withHeaders({
           Authorization: `Bearer ${token}`,
         }),
-        logInterceptor,
-      ],
+        getLogLevel() === 'trace' && withRequestLogger(this.logger, 'trace'),
+      ].filter((v) => !!v),
     });
 
     // Special handling for the ICETrickle kind of events.
-    // These events might be triggered by the SFU before the initial RTC
-    // connection is established. In that case, those events (ICE candidates)
-    // need to be buffered and later added to the appropriate PeerConnection
+    // The SFU might trigger these events before the initial RTC
+    // connection is established or "JoinResponse" received.
+    // In that case, those events (ICE candidates) need to be buffered
+    // and later added to the appropriate PeerConnection
     // once the remoteDescription is known and set.
     this.unsubscribeIceTrickle = dispatcher.on('iceTrickle', (iceTrickle) => {
       this.iceTrickleBuffer.push(iceTrickle);
     });
 
+    this.createWebSocket();
+  }
+
+  private createWebSocket = () => {
     this.signalWs = createWebSocketSignalChannel({
-      endpoint: sfuServer.ws_endpoint,
+      logTag: this.logTag,
+      endpoint: `${this.credentials.server.ws_endpoint}?tag=${this.logTag}`,
       onMessage: (message) => {
         this.lastMessageTimestamp = new Date();
         this.scheduleConnectionCheck();
-        dispatcher.dispatch(message);
+        this.dispatcher.dispatch(message, this.logTag);
       },
     });
 
+    this.signalWs.addEventListener('close', this.handleWebSocketClose);
+    this.signalWs.addEventListener('error', this.restoreWebSocket);
+
     this.signalReady = new Promise((resolve) => {
       const onOpen = () => {
         this.signalWs.removeEventListener('open', onOpen);
-        this.keepAlive();
         resolve(this.signalWs);
       };
       this.signalWs.addEventListener('open', onOpen);
     });
+  };
+
+  private cleanUpWebSocket = () => {
+    this.signalWs.removeEventListener('error', this.restoreWebSocket);
+    this.signalWs.removeEventListener('close', this.handleWebSocketClose);
+  };
+
+  private restoreWebSocket = () => {
+    withoutConcurrency(this.restoreWebSocketConcurrencyTag, async () => {
+      this.logger('debug', 'Restoring SFU WS connection');
+      this.cleanUpWebSocket();
+      await sleep(500);
+      this.createWebSocket();
+    }).catch((err) => this.logger('debug', `Can't restore WS connection`, err));
+  };
+
+  get isHealthy() {
+    return this.signalWs.readyState === WebSocket.OPEN;
   }
 
-  close = (code: number, reason: string) => {
-    this.logger('debug', `Closing SFU WS connection: ${code} - ${reason}`);
-    if (this.signalWs.readyState !== this.signalWs.CLOSED) {
+  private handleWebSocketClose = (e: CloseEvent) => {
+    this.signalWs.removeEventListener('close', this.handleWebSocketClose);
+    clearInterval(this.keepAliveInterval);
+    clearTimeout(this.connectionCheckTimeout);
+    if (this.onSignalClose) {
+      this.onSignalClose(e);
+    }
+  };
+
+  close = (code: number = StreamSfuClient.NORMAL_CLOSURE, reason?: string) => {
+    if (this.signalWs.readyState === WebSocket.OPEN) {
+      this.logger('debug', `Closing SFU WS connection: ${code} - ${reason}`);
       this.signalWs.close(code, `js-client: ${reason}`);
+      this.cleanUpWebSocket();
     }
+    this.dispose();
+  };
 
+  dispose = () => {
+    this.logger('debug', 'Disposing SFU client');
     this.unsubscribeIceTrickle();
     clearInterval(this.keepAliveInterval);
     clearTimeout(this.connectionCheckTimeout);
+    clearTimeout(this.migrateAwayTimeout);
+    this.abortController.abort();
+    this.migrationTask?.resolve();
+  };
+
+  leaveAndClose = async (reason: string) => {
+    await this.joinResponseTask.promise;
+    try {
+      this.isLeaving = true;
+      await this.notifyLeave(reason);
+    } catch (err) {
+      this.logger('debug', 'Error notifying SFU about leaving call', err);
+    }
+
+    this.close(StreamSfuClient.NORMAL_CLOSURE, reason.substring(0, 115));
   };
 
-  updateSubscriptions = async (subscriptions: TrackSubscriptionDetails[]) => {
+  updateSubscriptions = async (tracks: TrackSubscriptionDetails[]) => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.updateSubscriptions({
-          sessionId: this.sessionId,
-          tracks: subscriptions,
-        }),
-      this.logger,
-      'debug',
+      () => this.rpc.updateSubscriptions({ sessionId: this.sessionId, tracks }),
+      this.abortController.signal,
     );
   };
 
   setPublisher = async (data: Omit<SetPublisherRequest, 'sessionId'>) => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.setPublisher({
-          ...data,
-          sessionId: this.sessionId,
-        }),
-      this.logger,
+      () => this.rpc.setPublisher({ ...data, sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
   sendAnswer = async (data: Omit<SendAnswerRequest, 'sessionId'>) => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.sendAnswer({
-          ...data,
-          sessionId: this.sessionId,
-        }),
-      this.logger,
+      () => this.rpc.sendAnswer({ ...data, sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
   iceTrickle = async (data: Omit<ICETrickle, 'sessionId'>) => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.iceTrickle({
-          ...data,
-          sessionId: this.sessionId,
-        }),
-      this.logger,
+      () => this.rpc.iceTrickle({ ...data, sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
   iceRestart = async (data: Omit<ICERestartRequest, 'sessionId'>) => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.iceRestart({
-          ...data,
-          sessionId: this.sessionId,
-        }),
-      this.logger,
+      () => this.rpc.iceRestart({ ...data, sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
   updateMuteState = async (trackType: TrackType, muted: boolean) => {
-    return this.updateMuteStates({
-      muteStates: [
-        {
-          trackType,
-          muted,
-        },
-      ],
-    });
+    await this.joinResponseTask.promise;
+    return this.updateMuteStates({ muteStates: [{ trackType, muted }] });
   };
 
   updateMuteStates = async (
     data: Omit<UpdateMuteStatesRequest, 'sessionId'>,
   ) => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.updateMuteStates({
-          ...data,
-          sessionId: this.sessionId,
-        }),
-      this.logger,
+      () => this.rpc.updateMuteStates({ ...data, sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
   sendStats = async (stats: Omit<SendStatsRequest, 'sessionId'>) => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.sendStats({
-          ...stats,
-          sessionId: this.sessionId,
-        }),
-      this.logger,
-      'debug',
+      () => this.rpc.sendStats({ ...stats, sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
   startNoiseCancellation = async () => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.startNoiseCancellation({
-          sessionId: this.sessionId,
-        }),
-      this.logger,
+      () => this.rpc.startNoiseCancellation({ sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
   stopNoiseCancellation = async () => {
+    await this.joinResponseTask.promise;
     return retryable(
-      () =>
-        this.rpc.stopNoiseCancellation({
-          sessionId: this.sessionId,
-        }),
-      this.logger,
+      () => this.rpc.stopNoiseCancellation({ sessionId: this.sessionId }),
+      this.abortController.signal,
     );
   };
 
-  join = async (data: Omit<JoinRequest, 'sessionId' | 'token'>) => {
-    const joinRequest = JoinRequest.create({
-      ...data,
-      sessionId: this.sessionId,
-      token: this.token,
+  enterMigration = async (opts: { timeout?: number } = {}) => {
+    this.isLeaving = true;
+    const { timeout = 7 * 1000 } = opts;
+
+    this.migrationTask?.reject(new Error('Cancelled previous migration'));
+    const task = (this.migrationTask = promiseWithResolvers());
+    const unsubscribe = this.dispatcher.on(
+      'participantMigrationComplete',
+      () => {
+        unsubscribe();
+        clearTimeout(this.migrateAwayTimeout);
+        task.resolve();
+      },
+    );
+    this.migrateAwayTimeout = setTimeout(() => {
+      unsubscribe();
+      task.reject(
+        new Error(
+          `Migration (${this.logTag}) failed to complete in ${timeout}ms`,
+        ),
+      );
+    }, timeout);
+
+    return task.promise;
+  };
+
+  join = async (
+    data: Omit<JoinRequest, 'sessionId' | 'token'>,
+  ): Promise<JoinResponse> => {
+    // wait for the signal web socket to be ready before sending "joinRequest"
+    await this.signalReady;
+    if (this.joinResponseTask.isResolved || this.joinResponseTask.isRejected) {
+      // we need to lock the RPC requests until we receive a JoinResponse.
+      // that's why we have this primitive lock mechanism.
+      // the client starts with already initialized joinResponseTask,
+      // and this code creates a new one for the next join request.
+      this.joinResponseTask = promiseWithResolvers<JoinResponse>();
+    }
+
+    // capture a reference to the current joinResponseTask as it might
+    // be replaced with a new one in case a second join request is made
+    const current = this.joinResponseTask;
+
+    let timeoutId: NodeJS.Timeout;
+    const unsubscribe = this.dispatcher.on('joinResponse', (joinResponse) => {
+      this.logger('debug', 'Received joinResponse', joinResponse);
+      clearTimeout(timeoutId);
+      unsubscribe();
+      this.keepAlive();
+      current.resolve(joinResponse);
     });
-    return this.send(
+
+    timeoutId = setTimeout(() => {
+      unsubscribe();
+      current.reject(new Error('Waiting for "joinResponse" has timed out'));
+    }, this.joinResponseTimeout);
+
+    await this.send(
       SfuRequest.create({
         requestPayload: {
           oneofKind: 'joinRequest',
-          joinRequest,
+          joinRequest: JoinRequest.create({
+            ...data,
+            sessionId: this.sessionId,
+            token: this.credentials.token,
+          }),
         },
       }),
     );
-  };
 
-  send = async (message: SfuRequest) => {
-    return this.signalReady.then((signal) => {
-      if (signal.readyState !== signal.OPEN) return;
-      this.logger(
-        'debug',
-        `Sending message to: ${this.edgeName}`,
-        SfuRequest.toJson(message),
-      );
-      signal.send(SfuRequest.toBinary(message));
-    });
+    return current.promise;
   };
 
-  private keepAlive = () => {
-    clearInterval(this.keepAliveInterval);
-    this.keepAliveInterval = setInterval(() => {
-      this.logger('trace', 'Sending healthCheckRequest to SFU');
-      const message = SfuRequest.create({
+  ping = async () => {
+    return this.send(
+      SfuRequest.create({
         requestPayload: {
           oneofKind: 'healthCheckRequest',
           healthCheckRequest: {},
         },
-      });
-      this.send(message).catch((e) => {
+      }),
+    );
+  };
+
+  private notifyLeave = async (reason: string) => {
+    return this.send(
+      SfuRequest.create({
+        requestPayload: {
+          oneofKind: 'leaveCallRequest',
+          leaveCallRequest: {
+            sessionId: this.sessionId,
+            reason,
+          },
+        },
+      }),
+    );
+  };
+
+  private send = async (message: SfuRequest) => {
+    await this.signalReady; // wait for the signal ws to be open
+    const msgJson = SfuRequest.toJson(message);
+    if (this.signalWs.readyState !== WebSocket.OPEN) {
+      this.logger('debug', 'Signal WS is not open. Skipping message', msgJson);
+      return;
+    }
+    this.logger('debug', `Sending message to: ${this.edgeName}`, msgJson);
+    this.signalWs.send(SfuRequest.toBinary(message));
+  };
+
+  private keepAlive = () => {
+    clearInterval(this.keepAliveInterval);
+    this.keepAliveInterval = setInterval(() => {
+      this.ping().catch((e) => {
         this.logger('error', 'Error sending healthCheckRequest to SFU', e);
       });
     }, this.pingIntervalInMs);
@@ -393,65 +485,3 @@ export class StreamSfuClient {
     }, this.unhealthyTimeoutInMs);
   };
 }
-
-/**
- * An internal interface which asserts that "retryable" SFU responses
- * contain a field called "error".
- * Ideally, this should be coming from the Protobuf definitions.
- */
-interface SfuResponseWithError {
-  /**
-   * An optional error field which should be present in all SFU responses.
-   */
-  error?: SfuError;
-}
-
-const MAX_RETRIES = 5;
-
-/**
- * Creates a closure which wraps the given RPC call and retries invoking
- * the RPC until it succeeds or the maximum number of retries is reached.
- *
- * Between each retry, there would be a random delay in order to avoid
- * request bursts towards the SFU.
- *
- * @param rpc the closure around the RPC call to execute.
- * @param logger a logger instance to use.
- * @param <I> the type of the request object.
- * @param <O> the type of the response object.
- */
-const retryable = async <I extends object, O extends SfuResponseWithError>(
-  rpc: () => UnaryCall<I, O>,
-  logger: Logger,
-  level: LogLevel = 'error',
-) => {
-  let retryAttempt = 0;
-  let rpcCallResult: FinishedUnaryCall<I, O>;
-  do {
-    // don't delay the first invocation
-    if (retryAttempt > 0) {
-      await sleep(retryInterval(retryAttempt));
-    }
-
-    rpcCallResult = await rpc();
-
-    // if the RPC call failed, log the error and retry
-    if (rpcCallResult.response.error) {
-      logger(
-        level,
-        `SFU RPC Error (${rpcCallResult.method.name}):`,
-        rpcCallResult.response.error,
-      );
-    }
-    retryAttempt++;
-  } while (
-    rpcCallResult.response.error?.shouldRetry &&
-    retryAttempt < MAX_RETRIES
-  );
-
-  if (rpcCallResult.response.error) {
-    throw rpcCallResult.response.error;
-  }
-
-  return rpcCallResult;
-};