livekit-client 2.15.8 → 2.15.9

package/src/api/SignalClient.ts

@@ -4,10 +4,13 @@ import {
   AudioTrackFeature,
   ClientInfo,
   ConnectionQualityUpdate,
+  ConnectionSettings,
   DisconnectReason,
+  JoinRequest,
   JoinResponse,
   LeaveRequest,
   LeaveRequest_Action,
+  MediaSectionsRequirement,
   MuteTrackRequest,
   ParticipantInfo,
   Ping,
@@ -38,6 +41,7 @@ import {
   UpdateTrackSettings,
   UpdateVideoLayers,
   VideoLayer,
+  WrappedJoinRequest,
   protoInt64,
 } from '@livekit/protocol';
 import log, { LoggerNames, getLogger } from '../logger';
@@ -46,7 +50,8 @@ import CriticalTimers from '../room/timers';
 import type { LoggerOptions } from '../room/types';
 import { getClientInfo, isReactNative, sleep } from '../room/utils';
 import { AsyncQueue } from '../utils/AsyncQueue';
-import { createRtcUrl, createValidateUrl } from './utils';
+import { type WebSocketConnection, WebSocketStream } from './WebSocketStream';
+import { createRtcUrl, createValidateUrl, parseSignalResponse } from './utils';
 
 // internal options
 interface ConnectOpts extends SignalOptions {
@@ -65,6 +70,7 @@ export interface SignalOptions {
   maxRetries: number;
   e2eeEnabled: boolean;
   websocketTimeout: number;
+  singlePeerConnection: boolean;
 }
 
 type SignalMessage = SignalRequest['message'];
@@ -94,6 +100,9 @@ export enum SignalConnectionState {
   DISCONNECTED,
 }
 
+/** specifies how much time (in ms) we allow for the ws to close its connection gracefully before continuing */
+const MAX_WS_CLOSE_TIME = 250;
+
 /** @internal */
 export class SignalClient {
   requestQueue: AsyncQueue;
@@ -151,9 +160,11 @@ export class SignalClient {
 
   onRoomMoved?: (res: RoomMovedResponse) => void;
 
+  onMediaSectionsRequirement?: (requirement: MediaSectionsRequirement) => void;
+
   connectOptions?: ConnectOpts;
 
-  ws?: WebSocket;
+  ws?: WebSocketStream;
 
   get currentState() {
     return this.state;
@@ -200,6 +211,8 @@ export class SignalClient {
 
   private _requestId = 0;
 
+  private streamWriter: WritableStreamDefaultWriter<ArrayBuffer | string> | undefined;
+
   constructor(useJSON: boolean = false, loggerOptions: LoggerOptions = {}) {
     this.log = getLogger(loggerOptions.loggerName ?? LoggerNames.Signal);
     this.loggerContextCb = loggerOptions.loggerContextCb;
@@ -251,39 +264,47 @@ export class SignalClient {
       reconnect: true,
       sid,
       reconnectReason: reason,
-    })) as ReconnectResponse;
+    })) as ReconnectResponse | undefined;
     return res;
   }
 
-  private connect(
+  private async connect(
     url: string,
     token: string,
     opts: ConnectOpts,
     abortSignal?: AbortSignal,
   ): Promise<JoinResponse | ReconnectResponse | undefined> {
+    const unlock = await this.connectionLock.lock();
+
     this.connectOptions = opts;
     const clientInfo = getClientInfo();
-    const params = createConnectionParams(token, clientInfo, opts);
+    const params = opts.singlePeerConnection
+      ? createJoinRequestConnectionParams(token, clientInfo, opts)
+      : createConnectionParams(token, clientInfo, opts);
     const rtcUrl = createRtcUrl(url, params);
     const validateUrl = createValidateUrl(rtcUrl);
 
     return new Promise<JoinResponse | ReconnectResponse | undefined>(async (resolve, reject) => {
-      const unlock = await this.connectionLock.lock();
       try {
-        const abortHandler = async () => {
+        const timeoutAbortController = new AbortController();
+
+        const signals = abortSignal
+          ? [timeoutAbortController.signal, abortSignal]
+          : [timeoutAbortController.signal];
+
+        const combinedAbort = AbortSignal.any(signals);
+
+        const abortHandler = async (event: Event) => {
           this.close();
           clearTimeout(wsTimeout);
-          reject(
-            new ConnectionError(
-              'room connection has been cancelled (signal)',
-              ConnectionErrorReason.Cancelled,
-            ),
-          );
+          const target = event.currentTarget;
+          reject(target instanceof AbortSignal ? target.reason : target);
         };
 
+        combinedAbort.addEventListener('abort', abortHandler);
+
         const wsTimeout = setTimeout(() => {
-          this.close();
-          reject(
+          timeoutAbortController.abort(
             new ConnectionError(
               'room connection has timed out (signal)',
               ConnectionErrorReason.ServerUnreachable,
@@ -291,10 +312,13 @@ export class SignalClient {
           );
         }, opts.websocketTimeout);
 
-        if (abortSignal?.aborted) {
-          abortHandler();
-        }
-        abortSignal?.addEventListener('abort', abortHandler);
+        const handleSignalConnected = (
+          connection: WebSocketConnection,
+          firstMessage?: SignalResponse,
+        ) => {
+          this.handleSignalConnected(connection, wsTimeout, firstMessage);
+        };
+
         const redactedUrl = new URL(rtcUrl);
         if (redactedUrl.searchParams.has('access_token')) {
           redactedUrl.searchParams.set('access_token', '<redacted>');
@@ -307,151 +331,130 @@ export class SignalClient {
         if (this.ws) {
           await this.close(false);
         }
-        this.ws = new WebSocket(rtcUrl);
-        this.ws.binaryType = 'arraybuffer';
+        this.ws = new WebSocketStream<ArrayBuffer>(rtcUrl, { signal: combinedAbort });
 
-        this.ws.onopen = () => {
-          clearTimeout(wsTimeout);
-        };
-
-        this.ws.onerror = async (ev: Event) => {
-          if (this.state !== SignalConnectionState.CONNECTED) {
-            this.state = SignalConnectionState.DISCONNECTED;
-            clearTimeout(wsTimeout);
-            try {
-              const resp = await fetch(validateUrl);
-              if (resp.status.toFixed(0).startsWith('4')) {
-                const msg = await resp.text();
-                reject(new ConnectionError(msg, ConnectionErrorReason.NotAllowed, resp.status));
-              } else {
+        try {
+          this.ws.closed
+            .then((closeInfo) => {
+              if (this.isEstablishingConnection) {
                 reject(
                   new ConnectionError(
-                    `Encountered unknown websocket error during connection: ${ev.toString()}`,
+                    `Websocket got closed during a (re)connection attempt: ${closeInfo.reason}`,
                     ConnectionErrorReason.InternalError,
-                    resp.status,
                   ),
                 );
               }
-            } catch (e) {
-              reject(
-                new ConnectionError(
-                  e instanceof Error ? e.message : 'server was not reachable',
-                  ConnectionErrorReason.ServerUnreachable,
-                ),
-              );
-            }
-            return;
-          }
-          // other errors, handle
-          this.handleWSError(ev);
-        };
-
-        this.ws.onmessage = async (ev: MessageEvent) => {
-          // not considered connected until JoinResponse is received
-          let resp: SignalResponse;
-          if (typeof ev.data === 'string') {
-            const json = JSON.parse(ev.data);
-            resp = SignalResponse.fromJson(json, { ignoreUnknownFields: true });
-          } else if (ev.data instanceof ArrayBuffer) {
-            resp = SignalResponse.fromBinary(new Uint8Array(ev.data));
-          } else {
-            this.log.error(
-              `could not decode websocket message: ${typeof ev.data}`,
-              this.logContext,
-            );
-            return;
-          }
-
-          if (this.state !== SignalConnectionState.CONNECTED) {
-            let shouldProcessMessage = false;
-            // handle join message only
-            if (resp.message?.case === 'join') {
-              this.state = SignalConnectionState.CONNECTED;
-              abortSignal?.removeEventListener('abort', abortHandler);
-              this.pingTimeoutDuration = resp.message.value.pingTimeout;
-              this.pingIntervalDuration = resp.message.value.pingInterval;
-
-              if (this.pingTimeoutDuration && this.pingTimeoutDuration > 0) {
-                this.log.debug('ping config', {
+              if (closeInfo.closeCode !== 1000) {
+                this.log.warn(`websocket closed`, {
                   ...this.logContext,
-                  timeout: this.pingTimeoutDuration,
-                  interval: this.pingIntervalDuration,
+                  reason: closeInfo.reason,
+                  code: closeInfo.closeCode,
+                  wasClean: closeInfo.closeCode === 1000,
+                  state: this.state,
                 });
-                this.startPingInterval();
               }
-              resolve(resp.message.value);
-            } else if (
-              this.state === SignalConnectionState.RECONNECTING &&
-              resp.message.case !== 'leave'
-            ) {
-              // in reconnecting, any message received means signal reconnected
-              this.state = SignalConnectionState.CONNECTED;
-              abortSignal?.removeEventListener('abort', abortHandler);
-              this.startPingInterval();
-              if (resp.message?.case === 'reconnect') {
-                resolve(resp.message.value);
-              } else {
-                this.log.debug(
-                  'declaring signal reconnected without reconnect response received',
-                  this.logContext,
+              return;
+            })
+            .catch((reason) => {
+              if (this.isEstablishingConnection) {
+                reject(
+                  new ConnectionError(
+                    `Websocket error during a (re)connection attempt: ${reason}`,
+                    ConnectionErrorReason.InternalError,
+                  ),
                 );
-                resolve(undefined);
-                shouldProcessMessage = true;
               }
-            } else if (this.isEstablishingConnection && resp.message.case === 'leave') {
-              reject(
-                new ConnectionError(
-                  'Received leave request while trying to (re)connect',
-                  ConnectionErrorReason.LeaveRequest,
-                  undefined,
-                  resp.message.value.reason,
-                ),
-              );
-            } else if (!opts.reconnect) {
-              // non-reconnect case, should receive join response first
-              reject(
-                new ConnectionError(
-                  `did not receive join response, got ${resp.message?.case} instead`,
-                  ConnectionErrorReason.InternalError,
-                ),
-              );
-            }
-            if (!shouldProcessMessage) {
+            });
+          const connection = await this.ws.opened.catch(async (reason: unknown) => {
+            if (this.state !== SignalConnectionState.CONNECTED) {
+              this.state = SignalConnectionState.DISCONNECTED;
+              clearTimeout(wsTimeout);
+              const error = await this.handleConnectionError(reason, validateUrl);
+              reject(error);
               return;
             }
+            // other errors, handle
+            this.handleWSError(reason);
+            reject(reason);
+            return;
+          });
+          clearTimeout(wsTimeout);
+          if (!connection) {
+            return;
+          }
+          const signalReader = connection.readable.getReader();
+          const firstMessage = await signalReader.read();
+          signalReader.releaseLock();
+          if (!firstMessage.value) {
+            throw new ConnectionError(
+              'no message received as first message',
+              ConnectionErrorReason.InternalError,
+            );
           }
 
-          if (this.signalLatency) {
-            await sleep(this.signalLatency);
+          const firstSignalResponse = parseSignalResponse(firstMessage.value);
+
+          // Validate the first message
+          const validation = this.validateFirstMessage(
+            firstSignalResponse,
+            opts.reconnect ?? false,
+          );
+
+          if (!validation.isValid) {
+            reject(validation.error);
+            return;
           }
-          this.handleSignalResponse(resp);
-        };
 
-        this.ws.onclose = (ev: CloseEvent) => {
-          if (this.isEstablishingConnection) {
-            reject(
-              new ConnectionError(
-                'Websocket got closed during a (re)connection attempt',
-                ConnectionErrorReason.InternalError,
-              ),
-            );
+          // Handle join response - set up ping configuration
+          if (firstSignalResponse.message?.case === 'join') {
+            this.pingTimeoutDuration = firstSignalResponse.message.value.pingTimeout;
+            this.pingIntervalDuration = firstSignalResponse.message.value.pingInterval;
+
+            if (this.pingTimeoutDuration && this.pingTimeoutDuration > 0) {
+              this.log.debug('ping config', {
+                ...this.logContext,
+                timeout: this.pingTimeoutDuration,
+                interval: this.pingIntervalDuration,
+              });
+            }
           }
 
-          this.log.warn(`websocket closed`, {
-            ...this.logContext,
-            reason: ev.reason,
-            code: ev.code,
-            wasClean: ev.wasClean,
-            state: this.state,
-          });
-          this.handleOnClose(ev.reason);
-        };
+          // Handle successful connection
+          const firstMessageToProcess = validation.shouldProcessFirstMessage
+            ? firstSignalResponse
+            : undefined;
+          handleSignalConnected(connection, firstMessageToProcess);
+          resolve(validation.response);
+        } catch (e) {
+          clearTimeout(wsTimeout);
+          reject(e);
+        }
       } finally {
         unlock();
       }
     });
   }
 
+  async startReadingLoop(
+    signalReader: ReadableStreamDefaultReader<string | ArrayBuffer>,
+    firstMessage?: SignalResponse,
+  ) {
+    if (firstMessage) {
+      this.handleSignalResponse(firstMessage);
+    }
+    while (true) {
+      if (this.signalLatency) {
+        await sleep(this.signalLatency);
+      }
+      const { done, value } = await signalReader.read();
+      if (done) {
+        break;
+      }
+      const resp = parseSignalResponse(value);
+      this.handleSignalResponse(resp);
+    }
+  }
+
   /** @internal */
   resetCallbacks = () => {
     this.onAnswer = undefined;
@@ -465,6 +468,7 @@ export class SignalClient {
     this.onTokenRefresh = undefined;
     this.onTrickle = undefined;
     this.onClose = undefined;
+    this.onMediaSectionsRequirement = undefined;
   };
 
   async close(updateState: boolean = true) {
@@ -475,28 +479,16 @@ export class SignalClient {
         this.state = SignalConnectionState.DISCONNECTING;
       }
       if (this.ws) {
-        this.ws.onmessage = null;
-        this.ws.onopen = null;
-        this.ws.onclose = null;
+        this.ws.close({ closeCode: 1000, reason: 'Close method called on signal client' });
 
         // calling `ws.close()` only starts the closing handshake (CLOSING state), prefer to wait until state is actually CLOSED
-        const closePromise = new Promise<void>((resolve) => {
-          if (this.ws) {
-            this.ws.onclose = () => {
-              resolve();
-            };
-          } else {
-            resolve();
-          }
-        });
-
-        if (this.ws.readyState < this.ws.CLOSING) {
-          this.ws.close();
-          // 250ms grace period for ws to close gracefully
-          await Promise.race([closePromise, sleep(250)]);
-        }
+        const closePromise = this.ws.closed;
         this.ws = undefined;
+        this.streamWriter = undefined;
+        await Promise.race([closePromise, sleep(MAX_WS_CLOSE_TIME)]);
       }
+    } catch (e) {
+      this.log.debug('websocket error while closing', { ...this.logContext, error: e });
     } finally {
       if (updateState) {
         this.state = SignalConnectionState.DISCONNECTED;
@@ -675,7 +667,7 @@ export class SignalClient {
       this.log.debug(`skipping signal request (type: ${message.case}) - SignalClient disconnected`);
       return;
     }
-    if (!this.ws || this.ws.readyState !== this.ws.OPEN) {
+    if (!this.streamWriter) {
       this.log.error(
         `cannot send signal request before connected, type: ${message?.case}`,
         this.logContext,
@@ -686,9 +678,9 @@ export class SignalClient {
 
     try {
       if (this.useJSON) {
-        this.ws.send(req.toJsonString());
+        await this.streamWriter.write(req.toJsonString());
       } else {
-        this.ws.send(req.toBinary());
+        await this.streamWriter.write(req.toBinary());
       }
     } catch (e) {
       this.log.error('error sending signal message', { ...this.logContext, error: e });
@@ -790,6 +782,10 @@ export class SignalClient {
       if (this.onRoomMoved) {
         this.onRoomMoved(msg.value);
       }
+    } else if (msg.case === 'mediaSectionsRequirement') {
+      if (this.onMediaSectionsRequirement) {
+        this.onMediaSectionsRequirement(msg.value);
+      }
     } else {
       this.log.debug('unsupported message', { ...this.logContext, msgCase: msg.case });
     }
@@ -818,8 +814,8 @@ export class SignalClient {
     }
   }
 
-  private handleWSError(ev: Event) {
-    this.log.error('websocket error', { ...this.logContext, error: ev });
+  private handleWSError(error: unknown) {
+    this.log.error('websocket error', { ...this.logContext, error });
   }
 
   /**
@@ -872,6 +868,129 @@ export class SignalClient {
       CriticalTimers.clearInterval(this.pingInterval);
     }
   }
+
+  /**
+   * Handles the successful connection to the signal server
+   * @param connection The WebSocket connection
+   * @param timeoutHandle The timeout handle to clear
+   * @param firstMessage Optional first message to process
+   * @internal
+   */
+  private handleSignalConnected(
+    connection: WebSocketConnection,
+    timeoutHandle: ReturnType<typeof setTimeout>,
+    firstMessage?: SignalResponse,
+  ) {
+    this.state = SignalConnectionState.CONNECTED;
+    clearTimeout(timeoutHandle);
+    this.startPingInterval();
+    this.startReadingLoop(connection.readable.getReader(), firstMessage);
+    this.streamWriter = connection.writable.getWriter();
+  }
+
+  /**
+   * Validates the first message received from the signal server
+   * @param firstSignalResponse The first signal response received
+   * @param isReconnect Whether this is a reconnection attempt
+   * @returns Validation result with response or error
+   * @internal
+   */
+  private validateFirstMessage(
+    firstSignalResponse: SignalResponse,
+    isReconnect: boolean,
+  ): {
+    isValid: boolean;
+    response?: JoinResponse | ReconnectResponse;
+    error?: ConnectionError;
+    shouldProcessFirstMessage?: boolean;
+  } {
+    if (firstSignalResponse.message?.case === 'join') {
+      return {
+        isValid: true,
+        response: firstSignalResponse.message.value,
+      };
+    } else if (
+      this.state === SignalConnectionState.RECONNECTING &&
+      firstSignalResponse.message?.case !== 'leave'
+    ) {
+      if (firstSignalResponse.message?.case === 'reconnect') {
+        return {
+          isValid: true,
+          response: firstSignalResponse.message.value,
+        };
+      } else {
+        // in reconnecting, any message received means signal reconnected and we still need to process it
+        this.log.debug(
+          'declaring signal reconnected without reconnect response received',
+          this.logContext,
+        );
+        return {
+          isValid: true,
+          response: undefined,
+          shouldProcessFirstMessage: true,
+        };
+      }
+    } else if (this.isEstablishingConnection && firstSignalResponse.message?.case === 'leave') {
+      return {
+        isValid: false,
+        error: new ConnectionError(
+          'Received leave request while trying to (re)connect',
+          ConnectionErrorReason.LeaveRequest,
+          undefined,
+          firstSignalResponse.message.value.reason,
+        ),
+      };
+    } else if (!isReconnect) {
+      // non-reconnect case, should receive join response first
+      return {
+        isValid: false,
+        error: new ConnectionError(
+          `did not receive join response, got ${firstSignalResponse.message?.case} instead`,
+          ConnectionErrorReason.InternalError,
+        ),
+      };
+    }
+
+    return {
+      isValid: false,
+      error: new ConnectionError('Unexpected first message', ConnectionErrorReason.InternalError),
+    };
+  }
+
+  /**
+   * Handles WebSocket connection errors by validating with the server
+   * @param reason The error that occurred
+   * @param validateUrl The URL to validate the connection with
+   * @returns A ConnectionError with appropriate reason and status
+   * @internal
+   */
+  private async handleConnectionError(
+    reason: unknown,
+    validateUrl: string,
+  ): Promise<ConnectionError> {
+    try {
+      const resp = await fetch(validateUrl);
+      if (resp.status.toFixed(0).startsWith('4')) {
+        const msg = await resp.text();
+        return new ConnectionError(msg, ConnectionErrorReason.NotAllowed, resp.status);
+      } else if (reason instanceof ConnectionError) {
+        return reason;
+      } else {
+        return new ConnectionError(
+          `Encountered unknown websocket error during connection: ${reason}`,
+          ConnectionErrorReason.InternalError,
+          resp.status,
+        );
+      }
+    } catch (e) {
+      return e instanceof ConnectionError
+        ? e
+        : new ConnectionError(
+            e instanceof Error ? e.message : 'server was not reachable',
+            ConnectionErrorReason.ServerUnreachable,
+          );
+    }
+  }
 }
 
 function fromProtoSessionDescription(sd: SessionDescription): RTCSessionDescriptionInit {
@@ -958,3 +1077,31 @@ function createConnectionParams(
 
   return params;
 }
+
+function createJoinRequestConnectionParams(
+  token: string,
+  info: ClientInfo,
+  opts: ConnectOpts,
+): URLSearchParams {
+  const params = new URLSearchParams();
+  params.set('access_token', token);
+
+  const joinRequest = new JoinRequest({
+    clientInfo: info,
+    connectionSettings: new ConnectionSettings({
+      autoSubscribe: !!opts.autoSubscribe,
+      adaptiveStream: !!opts.adaptiveStream,
+    }),
+    reconnect: !!opts.reconnect,
+    participantSid: opts.sid ? opts.sid : undefined,
+  });
+  if (opts.reconnectReason) {
+    joinRequest.reconnectReason = opts.reconnectReason;
+  }
+  const wrappedJoinRequest = new WrappedJoinRequest({
+    joinRequest: joinRequest.toBinary(),
+  });
+  params.set('join_request', btoa(new TextDecoder('utf-8').decode(wrappedJoinRequest.toBinary())));
+
+  return params;
+}