@webex/plugin-meetings 2.60.1-next.9 → 2.60.2

package/src/meeting/muteState.ts

@@ -1,188 +1,122 @@
-import {ServerMuteReason} from '@webex/media-helpers';
 import LoggerProxy from '../common/logs/logger-proxy';
 import ParameterError from '../common/errors/parameter';
+import PermissionError from '../common/errors/permission';
+import Media from '../media';
 import MeetingUtil from './util';
 import {AUDIO, VIDEO} from '../constants';
 
-// eslint-disable-next-line import/prefer-default-export
-export const createMuteState = (type, meeting, enabled: boolean) => {
-  // todo: remove the meeting argument  (SPARK-399695)
+/* Certain aspects of server interaction for video muting are not implemented as we currently don't support remote muting of video.
+   If we ever need to support it, search for REMOTE_MUTE_VIDEO_MISSING_IMPLEMENTATION string to find the places that need updating
+*/
+
+const createMuteState = (type, meeting, mediaDirection) => {
+  if (type === AUDIO && !mediaDirection.sendAudio) {
+    return null;
+  }
+  if (type === VIDEO && !mediaDirection.sendVideo) {
+    return null;
+  }
 
   LoggerProxy.logger.info(
     `Meeting:muteState#createMuteState --> ${type}: creating MuteState for meeting id ${meeting?.id}`
   );
 
-  const muteState = new MuteState(type, meeting, enabled);
-
-  return muteState;
+  return new MuteState(type, meeting);
 };
 
 /** The purpose of this class is to manage the local and remote mute state and make sure that the server state always matches
    the last requested state by the client.
 
    More info about Locus muting API: https://sqbu-github.cisco.com/pages/WebExSquared/locus/guides/mute.html#
-
-   This class is exported only for unit tests. It should never be instantiated directly with new MuteState(), instead createMuteState() should be called
 */
-export class MuteState {
-  state: {
-    client: {
-      enabled: boolean; // indicates if audio/video is enabled at all or not
-      localMute: boolean;
-    };
-    server: {localMute: boolean; remoteMute: boolean; unmuteAllowed: boolean};
-    syncToServerInProgress: boolean;
-  };
-
+class MuteState {
+  pendingPromiseReject: any;
+  pendingPromiseResolve: any;
+  state: any;
   type: any;
-  ignoreMuteStateChange: boolean;
 
   /**
    * Constructor
    *
    * @param {String} type - audio or video
    * @param {Object} meeting - the meeting object (used for reading current remote mute status)
-   * @param {boolean} enabled - whether the client audio/video is enabled at all
    */
-  constructor(type: string, meeting: any, enabled: boolean) {
+  constructor(type: string, meeting: any) {
     if (type !== AUDIO && type !== VIDEO) {
       throw new ParameterError('Mute state is designed for handling audio or video only');
     }
     this.type = type;
-    this.ignoreMuteStateChange = false;
     this.state = {
       client: {
-        enabled,
-        localMute: true,
+        localMute: false,
       },
       server: {
-        localMute: true,
-        // because remoteVideoMuted and unmuteVideoAllowed are updated seperately, they might be undefined
-        remoteMute: type === AUDIO ? meeting.remoteMuted : meeting.remoteVideoMuted ?? false,
-        unmuteAllowed: type === AUDIO ? meeting.unmuteAllowed : meeting.unmuteVideoAllowed ?? true,
+        localMute: false,
+        // initial values available only for audio (REMOTE_MUTE_VIDEO_MISSING_IMPLEMENTATION)
+        remoteMute: type === AUDIO ? meeting.remoteMuted : false,
+        unmuteAllowed: type === AUDIO ? meeting.unmuteAllowed : true,
       },
       syncToServerInProgress: false,
     };
+    // these 2 hold the resolve, reject methods for the promise we returned to the client in last handleClientRequest() call
+    this.pendingPromiseResolve = null;
+    this.pendingPromiseReject = null;
   }
 
   /**
-   * Starts the mute state machine. Needs to be called after a new MuteState instance is created.
-   *
-   * @param {Object} meeting - the meeting object
-   * @returns {void}
-   */
-  public init(meeting: any) {
-    this.applyUnmuteAllowedToStream(meeting);
-
-    // if we are remotely muted, we need to apply that to the local stream now (mute on-entry)
-    if (this.state.server.remoteMute) {
-      this.muteLocalStream(meeting, this.state.server.remoteMute, 'remotelyMuted');
-    }
-
-    const initialMute =
-      this.type === AUDIO
-        ? meeting.mediaProperties.audioStream?.muted
-        : meeting.mediaProperties.videoStream?.muted;
-
-    LoggerProxy.logger.info(
-      `Meeting:muteState#init --> ${this.type}: local stream initial mute state: ${initialMute}`
-    );
-
-    if (initialMute !== undefined) {
-      this.state.client.localMute = initialMute;
-    } else {
-      // there is no stream, so it's like we are locally muted
-      // (this is important especially for transcoded meetings, in which the SDP m-line direction always stays "sendrecv")
-      this.state.client.localMute = true;
-    }
-    this.applyClientStateToServer(meeting);
-  }
-
-  /**
-   * This method needs to be called whenever the local audio/video stream has changed.
-   * It reapplies the remote mute state onto the new stream and also reads the current
-   * local mute state from the stream and updates the internal state machine and sends
-   * any required requests to the server.
-   *
-   * @param {Object} meeting - the meeting object
-   * @returns {void}
-   */
-  public handleLocalStreamChange(meeting: any) {
-    return this.init(meeting);
-  }
-
-  /**
-   * Enables/disables audio/video
+   * Handles mute/unmute request from the client/user. Returns a promise that's resolved once the server update is completed or
+   * at the point that this request becomese superseded by another client request.
    *
-   * @param {Object} meeting - the meeting object
-   * @param {boolean} enable
-   * @returns {void}
-   */
-  public enable(meeting: any, enable: boolean) {
-    this.state.client.enabled = enable;
-
-    this.applyClientStateToServer(meeting);
-  }
-
-  /**
-   * Mutes/unmutes local stream
+   * The client doesn't have to wait for the returned promise to resolve before calling handleClientRequest() again. If
+   * handleClientRequest() is called again before the previous one resolved, the MuteState class will make sure that eventually
+   * the server state will match the last requested state from the client.
    *
-   * @param {Object} meeting - the meeting object
-   * @param {Boolean} mute - true to mute the stream, false to unmute it
-   * @param {ServerMuteReason} reason - reason for muting/unmuting
-   * @returns {void}
-   */
-  private muteLocalStream(meeting: any, mute: boolean, reason: ServerMuteReason) {
-    this.ignoreMuteStateChange = true;
-    if (this.type === AUDIO) {
-      meeting.mediaProperties.audioStream?.setServerMuted(mute, reason);
-    } else {
-      meeting.mediaProperties.videoStream?.setServerMuted(mute, reason);
-    }
-    this.ignoreMuteStateChange = false;
-  }
-
-  /**
-   * This method should be called when the local stream mute state is changed
    * @public
    * @memberof MuteState
    * @param {Object} [meeting] the meeting object
    * @param {Boolean} [mute] true for muting, false for unmuting request
-   * @returns {void}
+   * @returns {Promise}
    */
-  public handleLocalStreamMuteStateChange(meeting?: object, mute?: boolean) {
-    if (this.ignoreMuteStateChange) {
-      return;
-    }
+  public handleClientRequest(meeting?: object, mute?: boolean) {
     LoggerProxy.logger.info(
-      `Meeting:muteState#handleLocalStreamMuteStateChange --> ${this.type}: local stream new mute state: ${mute}`
+      `Meeting:muteState#handleClientRequest --> ${this.type}: user requesting new mute state: ${mute}`
     );
 
-    this.state.client.localMute = mute;
+    if (!mute && this.state.server.unmuteAllowed !== null && !this.state.server.unmuteAllowed) {
+      return Promise.reject(
+        new PermissionError('User is not allowed to unmute self (hard mute feature is being used)')
+      );
+    }
 
-    this.applyClientStateToServer(meeting);
+    // we don't check if we're already in the same state, because even if we were, we would still have to apply the mute state locally,
+    // because the client may have changed the audio/vidoe tracks
+    this.state.client.localMute = mute;
+    this.applyClientStateLocally(meeting);
+
+    return new Promise((resolve, reject) => {
+      if (this.pendingPromiseResolve) {
+        // resolve the last promise we returned to the client as the client has issued a new request that has superseded the previous one
+        this.pendingPromiseResolve();
+      }
+      this.pendingPromiseResolve = resolve;
+      this.pendingPromiseReject = reject;
+      this.applyClientStateToServer(meeting);
+    });
   }
 
   /**
-   * Applies the current mute state to the local stream (by enabling or disabling it accordingly)
+   * Applies the current mute state to the local track (by enabling or disabling it accordingly)
    *
    * @public
    * @param {Object} [meeting] the meeting object
-   * @param {ServerMuteReason} reason - reason why we're applying our client state to the local stream
    * @memberof MuteState
    * @returns {void}
    */
-  public applyClientStateLocally(meeting?: any, reason?: ServerMuteReason) {
-    this.muteLocalStream(meeting, this.state.client.localMute, reason);
-  }
-
-  /** Returns true if client is locally muted - it takes into account not just the client local mute state,
-   *  but also whether audio/video is enabled at all
-   *
-   * @returns {boolean}
-   */
-  private getClientLocalMuteState() {
-    return this.state.client.enabled ? this.state.client.localMute : true;
+  public applyClientStateLocally(meeting?: any) {
+    Media.setLocalTrack(
+      !this.state.client.localMute,
+      this.type === AUDIO ? meeting.mediaProperties.audioTrack : meeting.mediaProperties.videoTrack
+    );
   }
 
   /**
@@ -193,7 +127,7 @@ export class MuteState {
    * @memberof MuteState
    * @returns {void}
    */
-  private applyClientStateToServer(meeting?: any) {
+  private applyClientStateToServer(meeting?: object) {
     if (this.state.syncToServerInProgress) {
       LoggerProxy.logger.info(
         `Meeting:muteState#applyClientStateToServer --> ${this.type}: request to server in progress, we need to wait for it to complete`
@@ -202,12 +136,11 @@ export class MuteState {
       return;
     }
 
-    const localMuteState = this.getClientLocalMuteState();
-    const localMuteRequiresSync = localMuteState !== this.state.server.localMute;
-    const remoteMuteRequiresSync = !localMuteState && this.state.server.remoteMute;
+    const localMuteRequiresSync = this.state.client.localMute !== this.state.server.localMute;
+    const remoteMuteRequiresSync = !this.state.client.localMute && this.state.server.remoteMute;
 
     LoggerProxy.logger.info(
-      `Meeting:muteState#applyClientStateToServer --> ${this.type}: localMuteRequiresSync: ${localMuteRequiresSync} (${localMuteState} ?= ${this.state.server.localMute})`
+      `Meeting:muteState#applyClientStateToServer --> ${this.type}: localMuteRequiresSync: ${localMuteRequiresSync} (${this.state.client.localMute} ?= ${this.state.server.localMute})`
     );
     LoggerProxy.logger.info(
       `Meeting:muteState#applyClientStateToServer --> ${this.type}: remoteMuteRequiresSync: ${remoteMuteRequiresSync}`
@@ -218,6 +151,12 @@ export class MuteState {
         `Meeting:muteState#applyClientStateToServer --> ${this.type}: client state already matching server state, nothing to do`
       );
 
+      if (this.pendingPromiseResolve) {
+        this.pendingPromiseResolve();
+      }
+      this.pendingPromiseResolve = null;
+      this.pendingPromiseReject = null;
+
       return;
     }
 
@@ -245,11 +184,11 @@ export class MuteState {
       .catch((e) => {
         this.state.syncToServerInProgress = false;
 
-        LoggerProxy.logger.warn(
-          `Meeting:muteState#applyClientStateToServer --> ${this.type}: error: ${e}`
-        );
-
-        this.applyServerMuteToLocalStream(meeting, 'clientRequestFailed');
+        if (this.pendingPromiseReject) {
+          this.pendingPromiseReject(e);
+        }
+        this.pendingPromiseResolve = null;
+        this.pendingPromiseReject = null;
       });
   }
 
@@ -262,14 +201,16 @@ export class MuteState {
    * @returns {Promise}
    */
   private sendLocalMuteRequestToServer(meeting?: any) {
-    const audioMuted = this.type === AUDIO ? this.getClientLocalMuteState() : undefined;
-    const videoMuted = this.type === VIDEO ? this.getClientLocalMuteState() : undefined;
+    const audioMuted =
+      this.type === AUDIO ? this.state.client.localMute : meeting.audio?.state.client.localMute;
+    const videoMuted =
+      this.type === VIDEO ? this.state.client.localMute : meeting.video?.state.client.localMute;
 
     LoggerProxy.logger.info(
       `Meeting:muteState#sendLocalMuteRequestToServer --> ${this.type}: sending local mute (audio=${audioMuted}, video=${videoMuted}) to server`
     );
 
-    return MeetingUtil.remoteUpdateAudioVideo(meeting, audioMuted, videoMuted)
+    return MeetingUtil.remoteUpdateAudioVideo(audioMuted, videoMuted, meeting)
       .then((locus) => {
         LoggerProxy.logger.info(
           `Meeting:muteState#sendLocalMuteRequestToServer --> ${this.type}: local mute (audio=${audioMuted}, video=${videoMuted}) applied to server`
@@ -277,9 +218,7 @@ export class MuteState {
 
         this.state.server.localMute = this.type === AUDIO ? audioMuted : videoMuted;
 
-        if (locus) {
-          meeting.locusInfo.handleLocusDelta(locus, meeting);
-        }
+        meeting.locusInfo.onFullLocus(locus);
 
         return locus;
       })
@@ -301,54 +240,35 @@ export class MuteState {
    * @returns {Promise}
    */
   private sendRemoteMuteRequestToServer(meeting?: any) {
-    const remoteMute = this.getClientLocalMuteState();
-
-    LoggerProxy.logger.info(
-      `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: sending remote mute:${remoteMute} to server`
-    );
-
-    return meeting.members
-      .muteMember(meeting.members.selfId, remoteMute, this.type === AUDIO)
-      .then(() => {
-        LoggerProxy.logger.info(
-          `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: remote mute:${remoteMute} applied to server`
-        );
-
-        this.state.server.remoteMute = remoteMute;
-      })
-      .catch((remoteUpdateError) => {
-        LoggerProxy.logger.warn(
-          `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: failed to apply remote mute ${remoteMute} to server: ${remoteUpdateError}`
-        );
+    if (this.type === AUDIO) {
+      const remoteMute = this.state.client.localMute;
 
-        return Promise.reject(remoteUpdateError);
-      });
-  }
+      LoggerProxy.logger.info(
+        `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: sending remote mute:${remoteMute} to server`
+      );
 
-  /** Sets the mute state of the local stream according to what server thinks is our state
-   * @param {Object} meeting - the meeting object
-   * @param {ServerMuteReason} serverMuteReason - reason why we're applying server mute to the local stream
-   * @returns {void}
-   */
-  private applyServerMuteToLocalStream(meeting: any, serverMuteReason: ServerMuteReason) {
-    const muted = this.state.server.localMute || this.state.server.remoteMute;
+      return meeting.members
+        .muteMember(meeting.members.selfId, remoteMute)
+        .then(() => {
+          LoggerProxy.logger.info(
+            `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: remote mute:${remoteMute} applied to server`
+          );
+
+          this.state.server.remoteMute = remoteMute;
+        })
+        .catch((remoteUpdateError) => {
+          LoggerProxy.logger.warn(
+            `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: failed to apply remote mute ${remoteMute} to server: ${remoteUpdateError}`
+          );
+
+          return Promise.reject(remoteUpdateError);
+        });
+    }
 
-    // update the local stream mute state, but not this.state.client.localMute
-    this.muteLocalStream(meeting, muted, serverMuteReason);
-  }
+    // for now we don't need to support remote muting of video (REMOTE_MUTE_VIDEO_MISSING_IMPLEMENTATION)
+    this.state.server.remoteMute = this.state.client.localMute;
 
-  /** Applies the current value for unmute allowed to the underlying stream
-   *
-   * @param {Meeting} meeting
-   * @returns {void}
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  private applyUnmuteAllowedToStream(meeting: any) {
-    if (this.type === AUDIO) {
-      meeting.mediaProperties.audioStream?.setUnmuteAllowed(this.state.server.unmuteAllowed);
-    } else {
-      meeting.mediaProperties.videoStream?.setUnmuteAllowed(this.state.server.unmuteAllowed);
-    }
+    return Promise.resolve();
   }
 
   /**
@@ -356,23 +276,16 @@ export class MuteState {
    *
    * @public
    * @memberof MuteState
-   * @param {Meeting} meeting
    * @param {Boolean} [muted] true if user is remotely muted, false otherwise
    * @param {Boolean} [unmuteAllowed] indicates if user is allowed to unmute self (false when "hard mute" feature is used)
    * @returns {undefined}
    */
-  public handleServerRemoteMuteUpdate(meeting: any, muted?: boolean, unmuteAllowed?: boolean) {
+  public handleServerRemoteMuteUpdate(muted?: boolean, unmuteAllowed?: boolean) {
     LoggerProxy.logger.info(
       `Meeting:muteState#handleServerRemoteMuteUpdate --> ${this.type}: updating server remoteMute to (${muted})`
     );
-    if (unmuteAllowed !== undefined) {
-      this.state.server.unmuteAllowed = unmuteAllowed;
-      this.applyUnmuteAllowedToStream(meeting);
-    }
-    if (muted !== undefined) {
-      this.state.server.remoteMute = muted;
-      this.applyServerMuteToLocalStream(meeting, 'remotelyMuted');
-    }
+    this.state.server.remoteMute = muted;
+    this.state.server.unmuteAllowed = unmuteAllowed;
   }
 
   /**
@@ -384,27 +297,27 @@ export class MuteState {
    * @returns {undefined}
    */
   public handleServerLocalUnmuteRequired(meeting?: object) {
-    if (!this.state.client.enabled) {
-      LoggerProxy.logger.warn(
-        `Meeting:muteState#handleServerLocalUnmuteRequired --> ${this.type}: localAudioUnmuteRequired received while ${this.type} is disabled -> local unmute will not result in ${this.type} being sent`
-      );
-    } else {
-      LoggerProxy.logger.info(
-        `Meeting:muteState#handleServerLocalUnmuteRequired --> ${this.type}: localAudioUnmuteRequired received -> doing local unmute`
-      );
-    }
+    LoggerProxy.logger.info(
+      `Meeting:muteState#handleServerLocalUnmuteRequired --> ${this.type}: localAudioUnmuteRequired received -> doing local unmute`
+    );
 
-    // todo: I'm seeing "you can now unmute yourself " popup  when this happens - but same thing happens on web.w.c so we can ignore for now
     this.state.server.remoteMute = false;
     this.state.client.localMute = false;
 
-    this.applyClientStateLocally(meeting, 'localUnmuteRequired');
+    if (this.pendingPromiseReject) {
+      this.pendingPromiseReject(
+        new Error('Server requested local unmute - this overrides any client request in progress')
+      );
+      this.pendingPromiseResolve = null;
+      this.pendingPromiseReject = null;
+    }
+
+    this.applyClientStateLocally(meeting);
     this.applyClientStateToServer(meeting);
   }
 
   /**
-   * Returns true if the user is locally or remotely muted.
-   * It only checks the mute status, ignoring the fact whether audio/video is enabled.
+   * Returns true if the user is locally or remotely muted
    *
    * @public
    * @memberof MuteState
@@ -417,35 +330,36 @@ export class MuteState {
   }
 
   /**
-   * Returns true if the user is remotely muted
+   * Returns true if the user is locally muted
    *
    * @public
    * @memberof MuteState
    * @returns {Boolean}
    */
-  public isRemotelyMuted() {
-    return this.state.server.remoteMute;
+  public isLocallyMuted() {
+    return this.state.client.localMute || this.state.server.localMute;
   }
 
   /**
-   * Returns true if unmute is allowed
+   * Returns true if the user is muted as a result of the client request (and not remotely muted)
    *
    * @public
    * @memberof MuteState
    * @returns {Boolean}
    */
-  public isUnmuteAllowed() {
-    return this.state.server.unmuteAllowed;
+  public isSelf() {
+    return this.state.client.localMute && !this.state.server.remoteMute;
   }
 
-  /**
-   * Returns true if the user is locally muted or audio/video is disabled
-   *
-   * @public
-   * @memberof MuteState
-   * @returns {Boolean}
-   */
-  public isLocallyMuted() {
-    return this.getClientLocalMuteState();
+  // defined for backwards compatibility with the old AudioStateMachine/VideoStateMachine classes
+  get muted() {
+    return this.isMuted();
+  }
+
+  // defined for backwards compatibility with the old AudioStateMachine/VideoStateMachine classes
+  get self() {
+    return this.isSelf();
   }
 }
+
+export default createMuteState;