@webex/plugin-meetings 3.0.0-beta.111 → 3.0.0-beta.113

package/src/meeting/locusMediaRequest.ts

@@ -0,0 +1,303 @@
+/* eslint-disable valid-jsdoc */
+import {defer} from 'lodash';
+import {Defer} from '@webex/common';
+import {WebexPlugin} from '@webex/webex-core';
+import {MEDIA, HTTP_VERBS, ROAP} from '../constants';
+import LoggerProxy from '../common/logs/logger-proxy';
+
+export type MediaRequestType = 'RoapMessage' | 'LocalMute';
+export type RequestResult = any;
+
+export type RoapRequest = {
+  type: 'RoapMessage';
+  selfUrl: string;
+  mediaId: string;
+  roapMessage: any;
+  reachability: any;
+  joinCookie: any; // any, because this is opaque to the client, we pass whatever object we got from one backend component (Orpheus) to the other (Locus)
+};
+
+export type LocalMuteRequest = {
+  type: 'LocalMute';
+  selfUrl: string;
+  mediaId: string;
+  muteOptions: {
+    audioMuted?: boolean;
+    videoMuted?: boolean;
+  };
+};
+
+export type Request = RoapRequest | LocalMuteRequest;
+
+/** Class representing a single /media request being sent to Locus */
+class InternalRequestInfo {
+  public readonly request: Request;
+  private pendingPromises: Defer[];
+  private sendRequestFn: (request: Request) => Promise<RequestResult>;
+
+  /** Constructor */
+  constructor(
+    request: Request,
+    pendingPromise: Defer,
+    sendRequestFn: (request: Request) => Promise<RequestResult>
+  ) {
+    this.request = request;
+    this.pendingPromises = [pendingPromise];
+    this.sendRequestFn = sendRequestFn;
+  }
+
+  /**
+   * Returns the list of pending promises associated with this request
+   */
+  public getPendingPromises() {
+    return this.pendingPromises;
+  }
+
+  /**
+   * Adds promises to the list of pending promises associated with this request
+   */
+  public addPendingPromises(pendingPromises: Defer[]) {
+    this.pendingPromises.push(...pendingPromises);
+  }
+
+  /**
+   * Executes the request. Returned promise is resolved once the request
+   * is completed (no matter if it succeeded or failed).
+   */
+  public execute(): Promise<void> {
+    return this.sendRequestFn(this.request)
+      .then((result) => {
+        // resolve all the pending promises associated with this request
+        this.pendingPromises.forEach((d) => d.resolve(result));
+      })
+      .catch((e) => {
+        // reject all the pending promises associated with this request
+        this.pendingPromises.forEach((d) => d.reject(e));
+      });
+  }
+}
+
+export type Config = {
+  device: {
+    url: string;
+    deviceType: string;
+  };
+  correlationId: string;
+  preferTranscoding: boolean;
+};
+
+/**
+ * Returns true if the request is triggering confluence creation in the server
+ */
+function isRequestAffectingConfluenceState(request: Request): boolean {
+  return (
+    request.type === 'RoapMessage' && request.roapMessage.messageType === ROAP.ROAP_TYPES.OFFER
+  );
+}
+
+/**
+ * This class manages all /media API requests to Locus. Every call to that
+ * Locus API has to go through this class.
+ */
+export class LocusMediaRequest extends WebexPlugin {
+  private config: Config;
+  private latestAudioMuted?: boolean;
+  private latestVideoMuted?: boolean;
+  private isRequestInProgress: boolean;
+  private queuedRequests: InternalRequestInfo[];
+  private confluenceState: 'not created' | 'creation in progress' | 'created';
+  /**
+   * Constructor
+   */
+  constructor(config: Config, options: any) {
+    super({}, options);
+    this.isRequestInProgress = false;
+    this.queuedRequests = [];
+    this.config = config;
+    this.confluenceState = 'not created';
+  }
+
+  /**
+   * Add a request to the internal queue.
+   */
+  private addToQueue(info: InternalRequestInfo) {
+    if (info.request.type === 'LocalMute' && this.queuedRequests.length > 0) {
+      // We don't need additional local mute requests in the queue.
+      // We only need at most 1 local mute or 1 roap request, because
+      // roap requests also include mute state, so whatever request
+      // is sent out, it will send the latest local mute state.
+      // We only need to store the pendingPromises so that they get resolved
+      // when the roap request is sent out.
+      this.queuedRequests[0].addPendingPromises(info.getPendingPromises());
+
+      return;
+    }
+
+    if (info.request.type === 'RoapMessage' && this.queuedRequests.length > 0) {
+      // remove any LocalMute requests from the queue, because this Roap message
+      // will also update the mute status in Locus, so they are redundant
+      this.queuedRequests = this.queuedRequests.filter((r) => {
+        if (r.request.type === 'LocalMute') {
+          // we need to keep the pending promises from the local mute request
+          // that we're removing from the queue
+          info.addPendingPromises(r.getPendingPromises());
+
+          return false;
+        }
+
+        return true;
+      });
+    }
+
+    this.queuedRequests.push(info);
+  }
+
+  /**
+   * Takes the next request from the queue and executes it. Once that
+   * request is completed, the next one will be taken from the queue
+   * and executed and this is repeated until the queue is empty.
+   */
+  private executeNextQueuedRequest(): void {
+    if (this.isRequestInProgress) {
+      return;
+    }
+
+    const nextRequest = this.queuedRequests.shift();
+
+    if (nextRequest) {
+      this.isRequestInProgress = true;
+      nextRequest.execute().then(() => {
+        this.isRequestInProgress = false;
+        this.executeNextQueuedRequest();
+      });
+    }
+  }
+
+  /**
+   * Returns latest requested audio and video mute values. If they have never been
+   * requested, we assume audio/video to be muted.
+   */
+  private getLatestMuteState() {
+    const audioMuted = this.latestAudioMuted !== undefined ? this.latestAudioMuted : true;
+    const videoMuted = this.latestVideoMuted !== undefined ? this.latestVideoMuted : true;
+
+    return {audioMuted, videoMuted};
+  }
+
+  /**
+   * Prepares the uri and body for the media request to be sent to Locus
+   */
+  private sendHttpRequest(request: Request) {
+    const uri = `${request.selfUrl}/${MEDIA}`;
+
+    const {audioMuted, videoMuted} = this.getLatestMuteState();
+
+    // first setup things common to all requests
+    const body: any = {
+      device: this.config.device,
+      correlationId: this.config.correlationId,
+      clientMediaPreferences: {
+        preferTranscoding: this.config.preferTranscoding,
+      },
+    };
+
+    const localMedias: any = {
+      audioMuted,
+      videoMuted,
+    };
+
+    // now add things specific to request type
+    switch (request.type) {
+      case 'LocalMute':
+        body.respOnlySdp = true;
+        body.usingResource = null;
+        break;
+
+      case 'RoapMessage':
+        localMedias.roapMessage = request.roapMessage;
+        localMedias.reachability = request.reachability;
+        body.clientMediaPreferences.joinCookie = request.joinCookie;
+        break;
+    }
+
+    body.localMedias = [
+      {
+        localSdp: JSON.stringify(localMedias), // this part must be JSON stringified, Locus requires this
+        mediaId: request.mediaId,
+      },
+    ];
+
+    LoggerProxy.logger.info(
+      `Meeting:LocusMediaRequest#sendHttpRequest --> ${request.type} audioMuted=${audioMuted} videoMuted=${videoMuted}`
+    );
+
+    if (isRequestAffectingConfluenceState(request) && this.confluenceState === 'not created') {
+      this.confluenceState = 'creation in progress';
+    }
+
+    // @ts-ignore
+    return this.request({
+      method: HTTP_VERBS.PUT,
+      uri,
+      body,
+    })
+      .then((result) => {
+        if (isRequestAffectingConfluenceState(request)) {
+          this.confluenceState = 'created';
+        }
+
+        return result;
+      })
+      .catch((e) => {
+        if (
+          isRequestAffectingConfluenceState(request) &&
+          this.confluenceState === 'creation in progress'
+        ) {
+          this.confluenceState = 'not created';
+        }
+        throw e;
+      });
+  }
+
+  /**
+   * Sends a media request to Locus
+   */
+  public send(request: Request): Promise<RequestResult> {
+    if (request.type === 'LocalMute') {
+      const {audioMuted, videoMuted} = request.muteOptions;
+
+      if (audioMuted !== undefined) {
+        this.latestAudioMuted = audioMuted;
+      }
+      if (videoMuted !== undefined) {
+        this.latestVideoMuted = videoMuted;
+      }
+
+      if (this.confluenceState === 'not created') {
+        // if there is no confluence, there is no point sending out local mute request
+        // as it will fail so we just store the latest audio/video muted values
+        // and resolve immediately, so that higher layer (MuteState class) doesn't get blocked
+        // and can call us again if user mutes/unmutes again before confluence is created
+        LoggerProxy.logger.info(
+          'Meeting:LocusMediaRequest#send --> called with LocalMute request before confluence creation'
+        );
+
+        return Promise.resolve({});
+      }
+    }
+
+    const pendingPromise = new Defer();
+
+    const newRequest = new InternalRequestInfo(
+      request,
+      pendingPromise,
+      this.sendHttpRequest.bind(this)
+    );
+
+    this.addToQueue(newRequest);
+
+    defer(() => this.executeNextQueuedRequest());
+
+    return pendingPromise.promise;
+  }
+}

package/src/meeting/muteState.ts

@@ -34,8 +34,10 @@ export const createMuteState = (type, meeting, mediaDirection, sdkOwnsLocalTrack
    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
 */
-class MuteState {
+export class MuteState {
   pendingPromiseReject: any;
   pendingPromiseResolve: any;
   state: any;
@@ -62,7 +64,7 @@ class MuteState {
         localMute: false,
       },
       server: {
-        localMute: false,
+        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,
@@ -95,7 +97,7 @@ class MuteState {
           : meeting.mediaProperties.videoTrack?.muted;
 
       LoggerProxy.logger.info(
-        `Meeting:muteState#start --> ${this.type}: local track initial mute state: ${initialMute}`
+        `Meeting:muteState#init --> ${this.type}: local track initial mute state: ${initialMute}`
       );
 
       if (initialMute !== undefined) {
@@ -103,6 +105,19 @@ class MuteState {
 
         this.applyClientStateToServer(meeting);
       }
+    } else {
+      // in the mode where sdkOwnsLocalTrack is false (transcoded meetings),
+      // SDK API currently doesn't allow to start with audio/video muted,
+      // so we need to apply the initial local mute state (false) to server
+      this.state.syncToServerInProgress = true;
+      this.sendLocalMuteRequestToServer(meeting)
+        .then(() => {
+          this.state.syncToServerInProgress = false;
+        })
+        .catch(() => {
+          this.state.syncToServerInProgress = false;
+          // not much we can do here...
+        });
     }
   }
 
@@ -312,16 +327,14 @@ class MuteState {
    * @returns {Promise}
    */
   private sendLocalMuteRequestToServer(meeting?: any) {
-    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;
+    const audioMuted = this.type === AUDIO ? this.state.client.localMute : undefined;
+    const videoMuted = this.type === VIDEO ? this.state.client.localMute : undefined;
 
     LoggerProxy.logger.info(
       `Meeting:muteState#sendLocalMuteRequestToServer --> ${this.type}: sending local mute (audio=${audioMuted}, video=${videoMuted}) to server`
     );
 
-    return MeetingUtil.remoteUpdateAudioVideo(audioMuted, videoMuted, meeting)
+    return MeetingUtil.remoteUpdateAudioVideo(meeting, audioMuted, videoMuted)
       .then((locus) => {
         LoggerProxy.logger.info(
           `Meeting:muteState#sendLocalMuteRequestToServer --> ${this.type}: local mute (audio=${audioMuted}, video=${videoMuted}) applied to server`
@@ -329,7 +342,9 @@ class MuteState {
 
         this.state.server.localMute = this.type === AUDIO ? audioMuted : videoMuted;
 
-        meeting.locusInfo.onFullLocus(locus);
+        if (locus) {
+          meeting.locusInfo.onFullLocus(locus);
+        }
 
         return locus;
       })

package/src/meeting/request.ts

@@ -89,6 +89,8 @@ export default class MeetingRequest extends StatelessWebexPlugin {
    * @param {boolean} options.moveToResource
    * @param {Object} options.roapMessage
    * @param {boolean} options.breakoutsSupported
+   * @param {String} options.locale,
+   * @param {Array} options.deviceCapabilities
    * @param {boolean} options.liveAnnotationSupported
    * @returns {Promise}
    */
@@ -109,6 +111,8 @@ export default class MeetingRequest extends StatelessWebexPlugin {
     permissionToken: any;
     preferTranscoding: any;
     breakoutsSupported: boolean;
+    locale?: string;
+    deviceCapabilities?: Array<string>;
     liveAnnotationSupported: boolean;
   }) {
     const {
@@ -127,6 +131,8 @@ export default class MeetingRequest extends StatelessWebexPlugin {
       roapMessage,
       preferTranscoding,
       breakoutsSupported,
+      locale,
+      deviceCapabilities = [],
       liveAnnotationSupported,
     } = options;
 
@@ -156,17 +162,21 @@ export default class MeetingRequest extends StatelessWebexPlugin {
       },
     };
 
-    let deviceCapabilities = [];
     if (breakoutsSupported) {
-      deviceCapabilities = [...deviceCapabilities, BREAKOUTS.BREAKOUTS_SUPPORTED];
+      deviceCapabilities.push(BREAKOUTS.BREAKOUTS_SUPPORTED);
     }
     if (liveAnnotationSupported) {
-      deviceCapabilities = [...deviceCapabilities, ANNOTATION.ANNOTATION_ON_SHARE_SUPPORTED];
+      deviceCapabilities.push(ANNOTATION.ANNOTATION_ON_SHARE_SUPPORTED);
     }
-    if (deviceCapabilities.length > 0) {
-      body.deviceCapabilities = deviceCapabilities;
+
+    if (locale) {
+      body.locale = locale;
     }
 
+    // add deviceCapabilities prop
+    if (deviceCapabilities.length) {
+      body.deviceCapabilities = deviceCapabilities;
+    }
     // @ts-ignore
     if (this.webex.meetings.clientRegion) {
       // @ts-ignore
@@ -593,52 +603,6 @@ export default class MeetingRequest extends StatelessWebexPlugin {
     });
   }
 
-  /**
-   * Toggle remote audio and/or video
-   * @param {Object} options options for toggling
-   * @param {String} options.selfId Locus self id??
-   * @param {String} options.locusUrl Locus url
-   * @param {String} options.deviceUrl Url of a device
-   * @param {String} options.resourceId Populated if you are paired to a device
-   * @param {String} options.localMedias local sdps
-   * @param {Boolean} options.preferTranscoding false for multistream (Homer), true for transcoded media (Edonus)
-   * @returns {Promise}
-   */
-  remoteAudioVideoToggle(
-    options:
-      | {
-          selfId: string;
-          locusUrl: string;
-          deviceUrl: string;
-          resourceId: string;
-          localMedias: string;
-        }
-      | any
-  ) {
-    const uri = `${options.locusUrl}/${PARTICIPANT}/${options.selfId}/${MEDIA}`;
-    const body = {
-      device: {
-        // @ts-ignore
-        deviceType: this.config.meetings.deviceType,
-        url: options.deviceUrl,
-      },
-      usingResource: options.resourceId || null,
-      correlationId: options.correlationId,
-      respOnlySdp: true,
-      localMedias: options.localMedias,
-      clientMediaPreferences: {
-        preferTranscoding: options.preferTranscoding ?? true,
-      },
-    };
-
-    // @ts-ignore
-    return this.request({
-      method: HTTP_VERBS.PUT,
-      uri,
-      body,
-    });
-  }
-
   /**
    * change the content floor grant
    * @param {Object} options options for floor grant

package/src/meeting/util.ts

@@ -44,33 +44,35 @@ MeetingUtil.parseLocusJoin = (response) => {
   return parsed;
 };
 
-MeetingUtil.remoteUpdateAudioVideo = (audioMuted, videoMuted, meeting) => {
+MeetingUtil.remoteUpdateAudioVideo = (meeting, audioMuted?: boolean, videoMuted?: boolean) => {
   if (!meeting) {
     return Promise.reject(new ParameterError('You need a meeting object.'));
   }
-  const localMedias = Media.generateLocalMedias(meeting.mediaId, audioMuted, videoMuted);
 
-  if (isEmpty(localMedias)) {
+  if (!meeting.locusMediaRequest) {
     return Promise.reject(
-      new ParameterError('You need a media id on the meeting to change remote audio.')
+      new ParameterError(
+        'You need a meeting with a media connection, call Meeting.addMedia() first.'
+      )
     );
   }
 
   Metrics.postEvent({event: eventType.MEDIA_REQUEST, meeting});
 
-  return meeting.meetingRequest
-    .remoteAudioVideoToggle({
-      locusUrl: meeting.locusUrl,
-      selfId: meeting.selfId,
-      localMedias,
-      deviceUrl: meeting.deviceUrl,
-      correlationId: meeting.correlationId,
-      preferTranscoding: !meeting.isMultistream,
+  return meeting.locusMediaRequest
+    .send({
+      type: 'LocalMute',
+      selfUrl: meeting.selfUrl,
+      mediaId: meeting.mediaId,
+      muteOptions: {
+        audioMuted,
+        videoMuted,
+      },
     })
     .then((response) => {
       Metrics.postEvent({event: eventType.MEDIA_RESPONSE, meeting});
 
-      return response.body.locus;
+      return response?.body?.locus;
     });
 };
 
@@ -107,6 +109,8 @@ MeetingUtil.joinMeeting = (meeting, options) => {
       preferTranscoding: !meeting.isMultistream,
       asResourceOccupant: options.asResourceOccupant,
       breakoutsSupported: options.breakoutsSupported,
+      locale: options.locale,
+      deviceCapabilities: options.deviceCapabilities,
     })
     .then((res) => {
       Metrics.postEvent({

package/src/roap/index.ts

@@ -98,11 +98,8 @@ export default class Roap extends StatelessWebexPlugin {
           roapMessage,
           locusSelfUrl: meeting.selfUrl,
           mediaId: options.mediaId,
-          correlationId: options.correlationId,
-          audioMuted: meeting.audio?.isLocallyMuted(),
-          videoMuted: meeting.video?.isLocallyMuted(),
           meetingId: meeting.id,
-          preferTranscoding: !meeting.isMultistream,
+          locusMediaRequest: meeting.locusMediaRequest,
         })
         .then(() => {
           LoggerProxy.logger.log(`Roap:index#sendRoapOK --> ROAP OK sent with seq ${options.seq}`);
@@ -135,11 +132,8 @@ export default class Roap extends StatelessWebexPlugin {
       roapMessage,
       locusSelfUrl: meeting.selfUrl,
       mediaId: options.mediaId,
-      correlationId: options.correlationId,
-      audioMuted: meeting.isAudioMuted(),
-      videoMuted: meeting.isVideoMuted(),
       meetingId: meeting.id,
-      preferTranscoding: !meeting.isMultistream,
+      locusMediaRequest: meeting.locusMediaRequest,
     });
   }
 
@@ -167,11 +161,8 @@ export default class Roap extends StatelessWebexPlugin {
         roapMessage,
         locusSelfUrl: meeting.selfUrl,
         mediaId: options.mediaId,
-        correlationId: options.correlationId,
-        audioMuted: meeting.audio?.isLocallyMuted(),
-        videoMuted: meeting.video?.isLocallyMuted(),
         meetingId: meeting.id,
-        preferTranscoding: !meeting.isMultistream,
+        locusMediaRequest: meeting.locusMediaRequest,
       })
       .then(() => {
         LoggerProxy.logger.log(
@@ -206,13 +197,10 @@ export default class Roap extends StatelessWebexPlugin {
 
         return this.roapRequest.sendRoap({
           roapMessage,
-          correlationId: meeting.correlationId,
           locusSelfUrl: meeting.selfUrl,
           mediaId: sendEmptyMediaId ? '' : meeting.mediaId,
-          audioMuted: meeting.audio?.isLocallyMuted(),
-          videoMuted: meeting.video?.isLocallyMuted(),
           meetingId: meeting.id,
-          preferTranscoding: !meeting.isMultistream,
+          locusMediaRequest: meeting.locusMediaRequest,
         });
       })