@webex/plugin-meetings 3.0.0-next.10 → 3.0.0-next.12

package/src/meeting/request.ts

@@ -103,6 +103,7 @@ export default class MeetingRequest extends StatelessWebexPlugin {
    * @param {String} options.locale,
    * @param {Array} options.deviceCapabilities
    * @param {boolean} options.liveAnnotationSupported
+   * @param {String} options.alias
    * @returns {Promise}
    */
   async joinMeeting(options: {
@@ -122,11 +123,13 @@ export default class MeetingRequest extends StatelessWebexPlugin {
     meetingNumber: any;
     permissionToken: any;
     preferTranscoding: any;
+    reachability: any;
     breakoutsSupported: boolean;
     locale?: string;
     deviceCapabilities?: Array<string>;
     liveAnnotationSupported: boolean;
     ipVersion?: IP_VERSION;
+    alias?: string;
   }) {
     const {
       asResourceOccupant,
@@ -143,12 +146,14 @@ export default class MeetingRequest extends StatelessWebexPlugin {
       pin,
       moveToResource,
       roapMessage,
+      reachability,
       preferTranscoding,
       breakoutsSupported,
       locale,
       deviceCapabilities = [],
       liveAnnotationSupported,
       ipVersion,
+      alias,
     } = options;
 
     LoggerProxy.logger.info('Meeting:request#joinMeeting --> Joining a meeting', correlationId);
@@ -178,6 +183,10 @@ export default class MeetingRequest extends StatelessWebexPlugin {
       },
     };
 
+    if (alias) {
+      body.alias = alias;
+    }
+
     if (breakoutsSupported) {
       deviceCapabilities.push(BREAKOUTS.BREAKOUTS_SUPPORTED);
     }
@@ -260,8 +269,15 @@ export default class MeetingRequest extends StatelessWebexPlugin {
       };
     }
 
-    if (roapMessage) {
-      body.localMedias = roapMessage.localMedias;
+    if (roapMessage || reachability) {
+      body.localMedias = [
+        {
+          localSdp: JSON.stringify({
+            roapMessage,
+            reachability,
+          }),
+        },
+      ];
     }
 
     /// @ts-ignore

package/src/meeting/util.ts

@@ -149,6 +149,7 @@ const MeetingUtil = {
         locusUrl: meeting.locusUrl,
         locusClusterUrl: meeting.meetingInfo?.locusClusterUrl,
         correlationId: meeting.correlationId,
+        reachability: options.reachability,
         roapMessage: options.roapMessage,
         permissionToken: meeting.permissionToken,
         resourceId: options.resourceId || null,

package/src/multistream/mediaRequestManager.ts

@@ -8,10 +8,10 @@ import {
   H264Codec,
   getRecommendedMaxBitrateForFrameSize,
   RecommendedOpusBitrates,
+  NamedMediaGroup,
 } from '@webex/internal-media-core';
 import {cloneDeepWith, debounce, isEmpty} from 'lodash';
 
-import {NamedMediaGroup} from '@webex/json-multistream';
 import LoggerProxy from '../common/logs/logger-proxy';
 
 import {ReceiveSlot, ReceiveSlotEvents} from './receiveSlot';

package/src/multistream/remoteMediaGroup.ts

@@ -2,7 +2,7 @@
 /* eslint-disable require-jsdoc */
 /* eslint-disable import/prefer-default-export */
 import {forEach} from 'lodash';
-import {NamedMediaGroup} from '@webex/json-multistream';
+import {NamedMediaGroup} from '@webex/internal-media-core';
 import LoggerProxy from '../common/logs/logger-proxy';
 
 import {getMaxFs, RemoteMedia, RemoteVideoResolution} from './remoteMedia';

package/src/multistream/remoteMediaManager.ts

@@ -1,8 +1,7 @@
 /* eslint-disable valid-jsdoc */
 import {cloneDeep, forEach, remove} from 'lodash';
 import {EventMap} from 'typed-emitter';
-import {MediaType} from '@webex/internal-media-core';
-import {NamedMediaGroup} from '@webex/json-multistream';
+import {MediaType, NamedMediaGroup} from '@webex/internal-media-core';
 
 import LoggerProxy from '../common/logs/logger-proxy';
 import EventsScope from '../common/events/events-scope';

package/src/multistream/sendSlotManager.ts

@@ -3,10 +3,9 @@ import {
   MediaType,
   LocalStream,
   MultistreamRoapMediaConnection,
+  NamedMediaGroup,
 } from '@webex/internal-media-core';
 
-import {NamedMediaGroup} from '@webex/json-multistream';
-
 export default class SendSlotManager {
   private readonly slots: Map<MediaType, SendSlot> = new Map();
   private readonly LoggerProxy: any;

package/src/reconnection-manager/index.ts

@@ -568,7 +568,7 @@ export default class ReconnectionManager {
 
     const iceServers = [];
 
-    if (turnServerResult.turnServerInfo) {
+    if (turnServerResult.turnServerInfo?.url) {
       iceServers.push({
         urls: turnServerResult.turnServerInfo.url,
         username: turnServerResult.turnServerInfo.username || '',

package/src/roap/index.ts

@@ -5,12 +5,18 @@ import {ROAP} from '../constants';
 import LoggerProxy from '../common/logs/logger-proxy';
 
 import RoapRequest from './request';
-import TurnDiscovery from './turnDiscovery';
+import TurnDiscovery, {TurnDiscoveryResult} from './turnDiscovery';
 import Meeting from '../meeting';
 import MeetingUtil from '../meeting/util';
 import Metrics from '../metrics';
 import BEHAVIORAL_METRICS from '../metrics/constants';
 
+export {
+  type TurnDiscoveryResult,
+  type TurnServerInfo,
+  type TurnDiscoverySkipReason,
+} from './turnDiscovery';
+
 /**
  * Roap options
  * @typedef {Object} RoapOptions
@@ -39,7 +45,7 @@ export default class Roap extends StatelessWebexPlugin {
   options: any;
   roapHandler: any;
   roapRequest: any;
-  turnDiscovery: any;
+  turnDiscovery: TurnDiscovery;
 
   /**
    *
@@ -260,7 +266,23 @@ export default class Roap extends StatelessWebexPlugin {
    * @param {Boolean} [isForced]
    * @returns {Promise}
    */
-  doTurnDiscovery(meeting: Meeting, isReconnecting: boolean, isForced?: boolean) {
+  doTurnDiscovery(
+    meeting: Meeting,
+    isReconnecting: boolean,
+    isForced?: boolean
+  ): Promise<TurnDiscoveryResult> {
     return this.turnDiscovery.doTurnDiscovery(meeting, isReconnecting, isForced);
   }
+
+  generateTurnDiscoveryRequestMessage(meeting: Meeting, isForced: boolean) {
+    return this.turnDiscovery.generateTurnDiscoveryRequestMessage(meeting, isForced);
+  }
+
+  handleTurnDiscoveryHttpResponse(meeting: Meeting, httpResponse: object) {
+    return this.turnDiscovery.handleTurnDiscoveryHttpResponse(meeting, httpResponse);
+  }
+
+  abortTurnDiscovery() {
+    return this.turnDiscovery.abort();
+  }
 }

package/src/roap/turnDiscovery.ts

@@ -4,7 +4,7 @@ import {Defer} from '@webex/common';
 import Metrics from '../metrics';
 import BEHAVIORAL_METRICS from '../metrics/constants';
 import LoggerProxy from '../common/logs/logger-proxy';
-import {ROAP} from '../constants';
+import {ROAP, Enum} from '../constants';
 
 import RoapRequest from './request';
 import Meeting from '../meeting';
@@ -18,6 +18,28 @@ const TURN_DISCOVERY_TIMEOUT = 10; // in seconds
 // and do the SDP offer with seq=1
 const TURN_DISCOVERY_SEQ = 0;
 
+const TurnDiscoverySkipReason = {
+  missingHttpResponse: 'missing http response', // when we asked for the TURN discovery response to be in the http response, but it wasn't there
+  reachability: 'reachability', // when udp reachability to public clusters is ok, so we don't need TURN (this doens't apply when joinWithMedia() is used)
+  alreadyInProgress: 'already in progress', // when we try to start TURN discovery while it's already in progress
+} as const;
+
+export type TurnDiscoverySkipReason =
+  | Enum<typeof TurnDiscoverySkipReason> // this is a kind of FYI, because in practice typescript will infer the type of TurnDiscoverySkipReason as a string
+  | string // used in case of errors, contains the error message
+  | undefined; // used when TURN discovery is not skipped
+
+export type TurnServerInfo = {
+  url: string;
+  username: string;
+  password: string;
+};
+
+export type TurnDiscoveryResult = {
+  turnServerInfo?: TurnServerInfo;
+  turnDiscoverySkippedReason: TurnDiscoverySkipReason;
+};
+
 /**
  * Handles the process of finding out TURN server information from Linus.
  * This is achieved by sending a TURN_DISCOVERY_REQUEST.
@@ -27,11 +49,7 @@ export default class TurnDiscovery {
 
   private defer?: Defer; // used for waiting for the response
 
-  private turnInfo: {
-    url: string;
-    username: string;
-    password: string;
-  };
+  private turnInfo: TurnServerInfo;
 
   private responseTimer?: ReturnType<typeof setTimeout>;
 
@@ -85,7 +103,8 @@ export default class TurnDiscovery {
   }
 
   /**
-   * handles TURN_DISCOVERY_RESPONSE roap message
+   * Handles TURN_DISCOVERY_RESPONSE roap message. Use it if the roap message comes over the websocket,
+   * otherwise use handleTurnDiscoveryHttpResponse() if it comes in the http response.
    *
    * @param {Object} roapMessage
    * @param {string} from string to indicate how we got the response (used just for logging)
@@ -158,18 +177,191 @@ export default class TurnDiscovery {
   }
 
   /**
-   * handles TURN_DISCOVERY_RESPONSE roap message that came in http response
+   * Generates TURN_DISCOVERY_REQUEST roap message. When this method returns a roapMessage, it means that a TURN discovery process has started.
+   * It needs be ended by calling handleTurnDiscoveryHttpResponse() once you get a response from the backend. If you don't get any response
+   * or want to abort, you need to call abort().
    *
-   * @param {Object} roapMessage
-   * @returns {Promise}
+   * @param {Meeting} meeting
+   * @param {boolean} isForced
+   * @returns {Object}
+   */
+  public async generateTurnDiscoveryRequestMessage(
+    meeting: Meeting,
+    isForced: boolean
+  ): Promise<{roapMessage?: object; turnDiscoverySkippedReason: TurnDiscoverySkipReason}> {
+    if (this.defer) {
+      LoggerProxy.logger.warn(
+        'Roap:turnDiscovery#generateTurnDiscoveryRequestMessage --> TURN discovery already in progress'
+      );
+
+      return {
+        roapMessage: undefined,
+        turnDiscoverySkippedReason: TurnDiscoverySkipReason.alreadyInProgress,
+      };
+    }
+
+    let turnDiscoverySkippedReason: TurnDiscoverySkipReason;
+
+    if (!isForced) {
+      turnDiscoverySkippedReason = await this.getSkipReason(meeting);
+    }
+
+    if (turnDiscoverySkippedReason) {
+      return {roapMessage: undefined, turnDiscoverySkippedReason};
+    }
+
+    this.defer = new Defer();
+
+    const roapMessage = {
+      messageType: ROAP.ROAP_TYPES.TURN_DISCOVERY_REQUEST,
+      version: ROAP.ROAP_VERSION,
+      seq: TURN_DISCOVERY_SEQ,
+      headers: ['includeAnswerInHttpResponse', 'noOkInTransaction'],
+    };
+
+    LoggerProxy.logger.info(
+      'Roap:turnDiscovery#generateTurnDiscoveryRequestMessage --> generated TURN_DISCOVERY_REQUEST message'
+    );
+
+    return {roapMessage, turnDiscoverySkippedReason: undefined};
+  }
+
+  /**
+   * Handles any errors that occur during TURN discovery without re-throwing them.
+   *
+   * @param {Meeting} meeting
+   * @param {Error} error
+   * @returns {TurnDiscoveryResult}
+   */
+  private handleTurnDiscoveryFailure(meeting: Meeting, error: Error): TurnDiscoveryResult {
+    // we catch any errors and resolve with no turn information so that the normal call join flow can continue without TURN
+    LoggerProxy.logger.info(
+      `Roap:turnDiscovery#doTurnDiscovery --> TURN discovery failed, continuing without TURN: ${error}`
+    );
+
+    Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.TURN_DISCOVERY_FAILURE, {
+      correlation_id: meeting.correlationId,
+      locus_id: meeting.locusUrl.split('/').pop(),
+      reason: error.message,
+      stack: error.stack,
+    });
+
+    return {turnServerInfo: undefined, turnDiscoverySkippedReason: `failure: ${error.message}`};
+  }
+
+  /**
+   * Handles TURN_DISCOVERY_RESPONSE roap message that came in http response. If the response is not valid,
+   * it returns an object with turnServerInfo set to undefined. In that case you need to call abort()
+   * to end the TURN discovery process.
+   *
+   * @param {Meeting} meeting
+   * @param {Object|undefined} httpResponse can be undefined to indicate that we didn't get the response
+   * @returns {Promise<TurnDiscoveryResult>}
    * @memberof Roap
    */
-  private async handleTurnDiscoveryResponseInHttpResponse(
-    roapMessage: object
-  ): Promise<{isOkRequired: boolean}> {
-    this.handleTurnDiscoveryResponse(roapMessage, 'in http response');
+  public async handleTurnDiscoveryHttpResponse(
+    meeting: Meeting,
+    httpResponse?: object
+  ): Promise<TurnDiscoveryResult> {
+    if (!this.defer) {
+      LoggerProxy.logger.warn(
+        'Roap:turnDiscovery#handleTurnDiscoveryHttpResponse --> unexpected http response, TURN discovery is not in progress'
+      );
 
-    return this.defer.promise;
+      throw new Error(
+        'handleTurnDiscoveryHttpResponse() called before generateTurnDiscoveryRequestMessage()'
+      );
+    }
+
+    if (httpResponse === undefined) {
+      return {
+        turnServerInfo: undefined,
+        turnDiscoverySkippedReason: TurnDiscoverySkipReason.missingHttpResponse,
+      };
+    }
+
+    try {
+      const roapMessage = this.parseHttpTurnDiscoveryResponse(meeting, httpResponse);
+
+      if (!roapMessage) {
+        return {
+          turnServerInfo: undefined,
+          turnDiscoverySkippedReason: TurnDiscoverySkipReason.missingHttpResponse,
+        };
+      }
+
+      this.handleTurnDiscoveryResponse(roapMessage, 'in http response');
+
+      const {isOkRequired} = await this.defer.promise;
+
+      if (isOkRequired) {
+        await this.sendRoapOK(meeting);
+      }
+
+      this.defer = undefined;
+
+      LoggerProxy.logger.info('Roap:turnDiscovery#doTurnDiscovery --> TURN discovery completed');
+
+      return {turnServerInfo: this.turnInfo, turnDiscoverySkippedReason: undefined};
+    } catch (error) {
+      this.abort();
+
+      return this.handleTurnDiscoveryFailure(meeting, error);
+    }
+  }
+
+  /**
+   * Aborts current TURN discovery. This method needs to be called if you called generateTurnDiscoveryRequestMessage(),
+   * but then never got any response from the server.
+   * @returns {void}
+   */
+  public abort() {
+    if (this.defer) {
+      this.defer.reject(new Error('TURN discovery aborted'));
+      this.defer = undefined;
+    }
+  }
+
+  /**
+   * Parses the TURN_DISCOVERY_RESPONSE roap message out of the http response
+   * and returns it.
+   *
+   * @param {Meeting} meeting
+   * @param {any} httpResponse
+   * @returns {any}
+   */
+  private parseHttpTurnDiscoveryResponse(
+    meeting: Meeting,
+    httpResponse: {mediaConnections?: Array<{remoteSdp?: string}>}
+  ) {
+    let turnDiscoveryResponse;
+
+    if (httpResponse.mediaConnections?.[0]?.remoteSdp) {
+      const remoteSdp = JSON.parse(httpResponse.mediaConnections[0].remoteSdp);
+
+      if (remoteSdp.roapMessage) {
+        // yes, it's misleading that remoteSdp actually contains a TURN discovery response, but that's how the backend works...
+        const {seq, messageType, errorType, errorCause, headers} = remoteSdp.roapMessage;
+
+        turnDiscoveryResponse = {
+          seq,
+          messageType,
+          errorType,
+          errorCause,
+          headers,
+        };
+      }
+    }
+
+    if (!turnDiscoveryResponse) {
+      Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.ROAP_HTTP_RESPONSE_MISSING, {
+        correlationId: meeting.correlationId,
+        messageType: 'TURN_DISCOVERY_RESPONSE',
+        isMultistream: meeting.isMultistream,
+      });
+    }
+
+    return turnDiscoveryResponse;
   }
 
   /**
@@ -181,13 +373,19 @@ export default class TurnDiscovery {
    * @private
    * @memberof Roap
    */
-  sendRoapTurnDiscoveryRequest(meeting: Meeting, isReconnecting: boolean) {
+  private sendRoapTurnDiscoveryRequest(
+    meeting: Meeting,
+    isReconnecting: boolean
+  ): Promise<TurnDiscoveryResult> {
     if (this.defer) {
       LoggerProxy.logger.warn(
         'Roap:turnDiscovery#sendRoapTurnDiscoveryRequest --> already in progress'
       );
 
-      return Promise.resolve();
+      return Promise.resolve({
+        turnServerInfo: undefined,
+        turnDiscoverySkippedReason: TurnDiscoverySkipReason.alreadyInProgress,
+      });
     }
 
     this.defer = new Defer();
@@ -215,41 +413,14 @@ export default class TurnDiscovery {
         // @ts-ignore - because of meeting.webex
         ipVersion: MeetingUtil.getIpVersion(meeting.webex),
       })
-      .then((response) => {
+      .then(async (response) => {
         const {mediaConnections} = response;
 
-        let turnDiscoveryResponse;
-
         if (mediaConnections) {
           meeting.updateMediaConnections(mediaConnections);
-
-          if (mediaConnections[0]?.remoteSdp) {
-            const remoteSdp = JSON.parse(mediaConnections[0].remoteSdp);
-
-            if (remoteSdp.roapMessage) {
-              // yes, it's misleading that remoteSdp actually contains a TURN discovery response, but that's how the backend works...
-              const {seq, messageType, errorType, errorCause, headers} = remoteSdp.roapMessage;
-
-              turnDiscoveryResponse = {
-                seq,
-                messageType,
-                errorType,
-                errorCause,
-                headers,
-              };
-            }
-          }
         }
 
-        if (!turnDiscoveryResponse) {
-          Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.ROAP_HTTP_RESPONSE_MISSING, {
-            correlationId: meeting.correlationId,
-            messageType: 'TURN_DISCOVERY_RESPONSE',
-            isMultistream: meeting.isMultistream,
-          });
-        }
-
-        return turnDiscoveryResponse;
+        return this.handleTurnDiscoveryHttpResponse(meeting, response);
       });
   }
 
@@ -261,7 +432,14 @@ export default class TurnDiscovery {
    * @returns {Promise}
    */
   sendRoapOK(meeting: Meeting) {
-    LoggerProxy.logger.info('Roap:turnDiscovery#sendRoapOK --> sending OK');
+    LoggerProxy.logger.info(
+      'Roap:turnDiscovery#sendRoapOK --> TURN discovery response requires OK, sending it...'
+    );
+
+    Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.TURN_DISCOVERY_REQUIRES_OK, {
+      correlation_id: meeting.correlationId,
+      locus_id: meeting.locusUrl.split('/').pop(),
+    });
 
     return this.roapRequest.sendRoap({
       roapMessage: {
@@ -284,7 +462,7 @@ export default class TurnDiscovery {
    * @param {Meeting} meeting
    * @returns {Promise<string>} Promise with empty string if reachability is not skipped or a reason if it is skipped
    */
-  private async getSkipReason(meeting: Meeting): Promise<string> {
+  private async getSkipReason(meeting: Meeting): Promise<TurnDiscoverySkipReason> {
     const isAnyPublicClusterReachable =
       // @ts-ignore - fix type
       await meeting.webex.meetings.reachability.isAnyPublicClusterReachable();
@@ -294,10 +472,10 @@ export default class TurnDiscovery {
         'Roap:turnDiscovery#getSkipReason --> reachability has not failed, skipping TURN discovery'
       );
 
-      return 'reachability';
+      return TurnDiscoverySkipReason.reachability;
     }
 
-    return '';
+    return undefined;
   }
 
   /**
@@ -330,8 +508,12 @@ export default class TurnDiscovery {
    * @param {Boolean} [isForced]
    * @returns {Promise}
    */
-  async doTurnDiscovery(meeting: Meeting, isReconnecting?: boolean, isForced?: boolean) {
-    let turnDiscoverySkippedReason: string;
+  async doTurnDiscovery(
+    meeting: Meeting,
+    isReconnecting?: boolean,
+    isForced?: boolean
+  ): Promise<TurnDiscoveryResult> {
+    let turnDiscoverySkippedReason: TurnDiscoverySkipReason;
 
     if (!isForced) {
       turnDiscoverySkippedReason = await this.getSkipReason(meeting);
@@ -345,24 +527,20 @@ export default class TurnDiscovery {
     }
 
     try {
-      const httpResponse = await this.sendRoapTurnDiscoveryRequest(meeting, isReconnecting);
+      const turnDiscoveryResult = await this.sendRoapTurnDiscoveryRequest(meeting, isReconnecting);
+
+      if (
+        turnDiscoveryResult.turnDiscoverySkippedReason !==
+        TurnDiscoverySkipReason.missingHttpResponse
+      ) {
+        return turnDiscoveryResult;
+      }
 
       // if we haven't got the response over http, we need to wait for it to come over the websocket via Mercury
-      const {isOkRequired} = httpResponse
-        ? await this.handleTurnDiscoveryResponseInHttpResponse(httpResponse)
-        : await this.waitForTurnDiscoveryResponse();
+      const {isOkRequired} = await this.waitForTurnDiscoveryResponse();
 
       if (isOkRequired) {
         await this.sendRoapOK(meeting);
-
-        LoggerProxy.logger.info(
-          'Roap:turnDiscovery#doTurnDiscovery --> TURN discovery response requires OK'
-        );
-
-        Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.TURN_DISCOVERY_REQUIRES_OK, {
-          correlation_id: meeting.correlationId,
-          locus_id: meeting.locusUrl.split('/').pop(),
-        });
       }
 
       this.defer = undefined;
@@ -371,19 +549,7 @@ export default class TurnDiscovery {
 
       return {turnServerInfo: this.turnInfo, turnDiscoverySkippedReason: undefined};
     } catch (e) {
-      // we catch any errors and resolve with no turn information so that the normal call join flow can continue without TURN
-      LoggerProxy.logger.info(
-        `Roap:turnDiscovery#doTurnDiscovery --> TURN discovery failed, continuing without TURN: ${e}`
-      );
-
-      Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.TURN_DISCOVERY_FAILURE, {
-        correlation_id: meeting.correlationId,
-        locus_id: meeting.locusUrl.split('/').pop(),
-        reason: e.message,
-        stack: e.stack,
-      });
-
-      return {turnServerInfo: undefined, turnDiscoverySkippedReason: undefined};
+      return this.handleTurnDiscoveryFailure(meeting, e);
     }
   }
 }