@webex/plugin-meetings 3.3.1 → 3.4.0-next.10

package/src/reachability/index.ts

@@ -3,8 +3,9 @@
  */
 
 /* eslint-disable class-methods-use-this */
-import {mapValues} from 'lodash';
+import {isEqual, mapValues, mean} from 'lodash';
 
+import {Defer} from '@webex/common';
 import LoggerProxy from '../common/logs/logger-proxy';
 import MeetingUtil from '../meeting/util';
 
@@ -12,10 +13,16 @@ import {REACHABILITY} from '../constants';
 
 import ReachabilityRequest, {ClusterList} from './request';
 import {
+  ClientMediaIpsUpdatedEventData,
   ClusterReachability,
   ClusterReachabilityResult,
+  Events,
+  ResultEventData,
   TransportResult,
 } from './clusterReachability';
+import EventsScope from '../common/events/events-scope';
+import BEHAVIORAL_METRICS from '../metrics/constants';
+import Metrics from '../metrics';
 
 export type ReachabilityMetrics = {
   reachability_public_udp_success: number;
@@ -60,11 +67,16 @@ export type ReachabilityResults = Record<
   }
 >;
 
+// timeouts in seconds
+const DEFAULT_TIMEOUT = 3;
+const VIDEO_MESH_TIMEOUT = 1;
+const OVERALL_TIMEOUT = 15;
+
 /**
  * @class Reachability
  * @export
  */
-export default class Reachability {
+export default class Reachability extends EventsScope {
   namespace = REACHABILITY.namespace;
   webex: object;
   reachabilityRequest: ReachabilityRequest;
@@ -72,12 +84,24 @@ export default class Reachability {
     [key: string]: ClusterReachability;
   };
 
+  reachabilityDefer?: Defer;
+
+  vmnTimer?: ReturnType<typeof setTimeout>;
+  publicCloudTimer?: ReturnType<typeof setTimeout>;
+  overallTimer?: ReturnType<typeof setTimeout>;
+
+  expectedResultsCount = {videoMesh: {udp: 0}, public: {udp: 0, tcp: 0, xtls: 0}};
+  resultsCount = {videoMesh: {udp: 0}, public: {udp: 0, tcp: 0, xtls: 0}};
+
+  protected lastTrigger?: string;
+
   /**
    * Creates an instance of Reachability.
    * @param {object} webex
    * @memberof Reachability
    */
   constructor(webex: object) {
+    super();
     this.webex = webex;
 
     /**
@@ -92,28 +116,51 @@ export default class Reachability {
     this.clusterReachability = {};
   }
 
+  /**
+   * Fetches the list of media clusters from the backend
+   * @param {boolean} isRetry
+   * @private
+   * @returns {Promise<{clusters: ClusterList, joinCookie: any}>}
+   */
+  async getClusters(isRetry = false): Promise<{clusters: ClusterList; joinCookie: any}> {
+    try {
+      const {clusters, joinCookie} = await this.reachabilityRequest.getClusters(
+        MeetingUtil.getIpVersion(this.webex)
+      );
+
+      return {clusters, joinCookie};
+    } catch (error) {
+      if (isRetry) {
+        throw error;
+      }
+
+      LoggerProxy.logger.error(
+        `Reachability:index#getClusters --> Failed with error: ${error}, retrying...`
+      );
+
+      return this.getClusters(true);
+    }
+  }
+
   /**
    * Gets a list of media clusters from the backend and performs reachability checks on all the clusters
+   * @param {string} trigger - explains the reason for starting reachability
    * @returns {Promise<ReachabilityResults>} reachability results
    * @public
    * @memberof Reachability
    */
-  public async gatherReachability(): Promise<ReachabilityResults> {
+  public async gatherReachability(trigger: string): Promise<ReachabilityResults> {
     // Fetch clusters and measure latency
     try {
-      const {clusters, joinCookie} = await this.reachabilityRequest.getClusters(
-        MeetingUtil.getIpVersion(this.webex)
-      );
-
-      // Perform Reachability Check
-      const results = await this.performReachabilityChecks(clusters);
+      this.lastTrigger = trigger;
 
+      // kick off ip version detection. For now we don't await it, as we're doing it
+      // to gather the timings and send them with our reachability metrics
       // @ts-ignore
-      await this.webex.boundedStorage.put(
-        this.namespace,
-        REACHABILITY.localStorageResult,
-        JSON.stringify(results)
-      );
+      this.webex.internal.device.ipNetworkDetector.detect();
+
+      const {clusters, joinCookie} = await this.getClusters();
+
       // @ts-ignore
       await this.webex.boundedStorage.put(
         this.namespace,
@@ -121,11 +168,12 @@ export default class Reachability {
         JSON.stringify(joinCookie)
       );
 
-      LoggerProxy.logger.log(
-        'Reachability:index#gatherReachability --> Reachability checks completed'
-      );
+      this.reachabilityDefer = new Defer();
 
-      return results;
+      // Perform Reachability Check
+      await this.performReachabilityChecks(clusters);
+
+      return this.reachabilityDefer.promise;
     } catch (error) {
       LoggerProxy.logger.error(`Reachability:index#gatherReachability --> Error:`, error);
 
@@ -395,16 +443,221 @@ export default class Reachability {
     });
   }
 
+  /**
+   * Returns true if we've obtained all the reachability results for all the public clusters
+   * In other words, it means that all public clusters are reachable over each protocol,
+   * because we only get a "result" if we managed to reach a cluster
+   *
+   * @returns {boolean}
+   */
+  private areAllPublicClusterResultsReady() {
+    return isEqual(this.expectedResultsCount.public, this.resultsCount.public);
+  }
+
+  /**
+   * Returns true if we've obtained all the reachability results for all the clusters
+   *
+   * @returns {boolean}
+   */
+  private areAllResultsReady() {
+    return isEqual(this.expectedResultsCount, this.resultsCount);
+  }
+
+  /**
+   * Resolves the promise returned by gatherReachability() method
+   * @returns {void}
+   */
+  private resolveReachabilityPromise() {
+    if (this.vmnTimer) {
+      clearTimeout(this.vmnTimer);
+    }
+    if (this.publicCloudTimer) {
+      clearTimeout(this.publicCloudTimer);
+    }
+
+    this.logUnreachableClusters();
+    this.reachabilityDefer?.resolve();
+  }
+
+  /**
+   * Aborts all cluster reachability checks that are in progress
+   *
+   * @returns {void}
+   */
+  private abortClusterReachability() {
+    Object.values(this.clusterReachability).forEach((clusterReachability) => {
+      clusterReachability.abort();
+    });
+  }
+
+  /**
+   * Helper function for calculating min/max/average values of latency
+   *
+   * @param {Array<any>} results
+   * @param {string} protocol
+   * @param {boolean} isVideoMesh
+   * @returns {{min:number, max: number, average: number}}
+   */
+  protected getStatistics(
+    results: Array<ClusterReachabilityResult & {isVideoMesh: boolean}>,
+    protocol: 'udp' | 'tcp' | 'xtls',
+    isVideoMesh: boolean
+  ) {
+    const values = results
+      .filter((result) => result.isVideoMesh === isVideoMesh)
+      .filter((result) => result[protocol].result === 'reachable')
+      .map((result) => result[protocol].latencyInMilliseconds);
+
+    if (values.length === 0) {
+      return {
+        min: -1,
+        max: -1,
+        average: -1,
+      };
+    }
+
+    return {
+      min: Math.min(...values),
+      max: Math.max(...values),
+      average: mean(values),
+    };
+  }
+
+  /**
+   * Sends a metric with all the statistics about how long reachability took
+   *
+   * @returns {void}
+   */
+  protected async sendMetric() {
+    const results = [];
+
+    Object.values(this.clusterReachability).forEach((clusterReachability) => {
+      results.push({
+        ...clusterReachability.getResult(),
+        isVideoMesh: clusterReachability.isVideoMesh,
+      });
+    });
+
+    const stats = {
+      vmn: {
+        udp: this.getStatistics(results, 'udp', true),
+      },
+      public: {
+        udp: this.getStatistics(results, 'udp', false),
+        tcp: this.getStatistics(results, 'tcp', false),
+        xtls: this.getStatistics(results, 'xtls', false),
+      },
+      ipver: {
+        // @ts-ignore
+        firstIpV4: this.webex.internal.device.ipNetworkDetector.firstIpV4,
+        // @ts-ignore
+        firstIpV6: this.webex.internal.device.ipNetworkDetector.firstIpV6,
+        // @ts-ignore
+        firstMdns: this.webex.internal.device.ipNetworkDetector.firstMdns,
+        // @ts-ignore
+        totalTime: this.webex.internal.device.ipNetworkDetector.totalTime,
+      },
+      trigger: this.lastTrigger,
+    };
+    Metrics.sendBehavioralMetric(
+      BEHAVIORAL_METRICS.REACHABILITY_COMPLETED,
+      Metrics.prepareMetricFields(stats)
+    );
+  }
+
+  /**
+   * Starts all the timers used for various timeouts
+   *
+   * @returns {void}
+   */
+  private startTimers() {
+    this.vmnTimer = setTimeout(() => {
+      this.vmnTimer = undefined;
+      // if we are only missing VMN results, then we don't want to wait for them any longer
+      // as they are likely to fail if users are not on corporate network
+      if (this.areAllPublicClusterResultsReady()) {
+        LoggerProxy.logger.log(
+          'Reachability:index#startTimers --> Reachability checks timed out (VMN timeout)'
+        );
+
+        this.resolveReachabilityPromise();
+      }
+    }, VIDEO_MESH_TIMEOUT * 1000);
+
+    this.publicCloudTimer = setTimeout(() => {
+      this.publicCloudTimer = undefined;
+
+      LoggerProxy.logger.log(
+        `Reachability:index#startTimers --> Reachability checks timed out (${DEFAULT_TIMEOUT}s)`
+      );
+
+      // resolve the promise, so that the client won't be blocked waiting on meetings.register() for too long
+      this.resolveReachabilityPromise();
+    }, DEFAULT_TIMEOUT * 1000);
+
+    this.overallTimer = setTimeout(() => {
+      this.overallTimer = undefined;
+      this.abortClusterReachability();
+      this.emit(
+        {
+          file: 'reachability',
+          function: 'overallTimer timeout',
+        },
+        'reachability:done',
+        {}
+      );
+      this.sendMetric();
+
+      LoggerProxy.logger.log(
+        `Reachability:index#startTimers --> Reachability checks fully timed out (${OVERALL_TIMEOUT}s)`
+      );
+    }, OVERALL_TIMEOUT * 1000);
+  }
+
+  /**
+   * Stores given reachability results in local storage
+   *
+   * @param {ReachabilityResults} results
+   * @returns {Promise<void>}
+   */
+  private async storeResults(results: ReachabilityResults) {
+    // @ts-ignore
+    await this.webex.boundedStorage.put(
+      this.namespace,
+      REACHABILITY.localStorageResult,
+      JSON.stringify(results)
+    );
+  }
+
+  /**
+   * Resets all the internal counters that keep track of the results
+   *
+   * @returns {void}
+   */
+  private resetResultCounters() {
+    this.expectedResultsCount.videoMesh.udp = 0;
+    this.expectedResultsCount.public.udp = 0;
+    this.expectedResultsCount.public.tcp = 0;
+    this.expectedResultsCount.public.xtls = 0;
+
+    this.resultsCount.videoMesh.udp = 0;
+    this.resultsCount.public.udp = 0;
+    this.resultsCount.public.tcp = 0;
+    this.resultsCount.public.xtls = 0;
+  }
+
   /**
    * Performs reachability checks for all clusters
    * @param {ClusterList} clusterList
-   * @returns {Promise<ReachabilityResults>} reachability check results
+   * @returns {Promise<void>} promise that's resolved as soon as the checks are started
    */
-  private async performReachabilityChecks(clusterList: ClusterList): Promise<ReachabilityResults> {
+  private async performReachabilityChecks(clusterList: ClusterList) {
     const results: ReachabilityResults = {};
 
+    this.clusterReachability = {};
+
     if (!clusterList || !Object.keys(clusterList).length) {
-      return Promise.resolve(results);
+      return;
     }
 
     LoggerProxy.logger.log(
@@ -417,7 +670,11 @@ export default class Reachability {
       } reachability checks`
     );
 
-    const clusterReachabilityChecks = Object.keys(clusterList).map((key) => {
+    this.resetResultCounters();
+    this.startTimers();
+
+    // sanitize the urls in the clusterList
+    Object.keys(clusterList).forEach((key) => {
       const cluster = clusterList[key];
 
       // Linus doesn't support TCP reachability checks on video mesh nodes
@@ -429,6 +686,7 @@ export default class Reachability {
         cluster.tcp = [];
       }
 
+      // Linus doesn't support xTLS reachability checks on video mesh nodes
       const includeTlsReachability =
         // @ts-ignore
         this.webex.config.meetings.experimental.enableTlsReachability && !cluster.isVideoMesh;
@@ -437,18 +695,94 @@ export default class Reachability {
         cluster.xtls = [];
       }
 
-      this.clusterReachability[key] = new ClusterReachability(key, cluster);
+      // initialize the result for this cluster
+      results[key] = {
+        udp: {result: cluster.udp.length > 0 ? 'unreachable' : 'untested'},
+        tcp: {result: cluster.tcp.length > 0 ? 'unreachable' : 'untested'},
+        xtls: {result: cluster.xtls.length > 0 ? 'unreachable' : 'untested'},
+        isVideoMesh: cluster.isVideoMesh,
+      };
+
+      // update expected results counters to include this cluster
+      this.expectedResultsCount[cluster.isVideoMesh ? 'videoMesh' : 'public'].udp +=
+        cluster.udp.length;
+      if (!cluster.isVideoMesh) {
+        this.expectedResultsCount.public.tcp += cluster.tcp.length;
+        this.expectedResultsCount.public.xtls += cluster.xtls.length;
+      }
+    });
+
+    const isFirstResult = {
+      udp: true,
+      tcp: true,
+      xtls: true,
+    };
+
+    // save the initialized results (in case we don't get any "resultReady" events at all)
+    await this.storeResults(results);
+
+    // now start the reachability on all the clusters
+    Object.keys(clusterList).forEach((key) => {
+      const cluster = clusterList[key];
 
-      return this.clusterReachability[key].start().then((result) => {
-        results[key] = result;
-        results[key].isVideoMesh = cluster.isVideoMesh;
+      this.clusterReachability[key] = new ClusterReachability(key, cluster);
+      this.clusterReachability[key].on(Events.resultReady, async (data: ResultEventData) => {
+        const {protocol, result, clientMediaIPs, latencyInMilliseconds} = data;
+
+        if (isFirstResult[protocol]) {
+          this.emit(
+            {
+              file: 'reachability',
+              function: 'resultReady event handler',
+            },
+            'reachability:firstResultAvailable',
+            {
+              protocol,
+            }
+          );
+          isFirstResult[protocol] = false;
+        }
+        this.resultsCount[cluster.isVideoMesh ? 'videoMesh' : 'public'][protocol] += 1;
+
+        const areAllResultsReady = this.areAllResultsReady();
+
+        results[key][protocol].result = result;
+        results[key][protocol].clientMediaIPs = clientMediaIPs;
+        results[key][protocol].latencyInMilliseconds = latencyInMilliseconds;
+
+        await this.storeResults(results);
+
+        if (areAllResultsReady) {
+          clearTimeout(this.overallTimer);
+          this.overallTimer = undefined;
+          this.emit(
+            {
+              file: 'reachability',
+              function: 'performReachabilityChecks',
+            },
+            'reachability:done',
+            {}
+          );
+          this.sendMetric();
+
+          LoggerProxy.logger.log(
+            `Reachability:index#gatherReachability --> Reachability checks fully completed`
+          );
+          this.resolveReachabilityPromise();
+        }
       });
-    });
 
-    await Promise.all(clusterReachabilityChecks);
+      // clientMediaIps can be updated independently from the results, so we need to listen for them too
+      this.clusterReachability[key].on(
+        Events.clientMediaIpsUpdated,
+        async (data: ClientMediaIpsUpdatedEventData) => {
+          results[key][data.protocol].clientMediaIPs = data.clientMediaIPs;
 
-    this.logUnreachableClusters();
+          await this.storeResults(results);
+        }
+      );
 
-    return results;
+      this.clusterReachability[key].start(); // not awaiting on purpose
+    });
   }
 }

package/src/reconnection-manager/index.ts

@@ -342,7 +342,7 @@ export default class ReconnectionManager {
       }
 
       try {
-        await this.webex.meetings.startReachability();
+        await this.webex.meetings.startReachability('reconnection');
       } catch (err) {
         LoggerProxy.logger.info(
           'ReconnectionManager:index#reconnect --> Reachability failed, continuing with reconnection attempt, err: ',

package/src/rtcMetrics/index.ts

@@ -34,6 +34,8 @@ export default class RtcMetrics {
 
   connectionId: string;
 
+  shouldSendMetricsOnNextStatsReport: boolean;
+
   /**
    * Initialize the interval.
    *
@@ -47,9 +49,7 @@ export default class RtcMetrics {
     this.meetingId = meetingId;
     this.webex = webex;
     this.correlationId = correlationId;
-    this.setNewConnectionId();
-    // Send the first set of metrics at 5 seconds in the case of a user leaving the call shortly after joining.
-    setTimeout(this.sendMetricsInQueue.bind(this), 5 * 1000);
+    this.resetConnection();
   }
 
   /**
@@ -64,6 +64,18 @@ export default class RtcMetrics {
     }
   }
 
+  /**
+   * Forces sending metrics when we get the next stats-report
+   *
+   * This is useful for cases when something important happens that affects the media connection,
+   * for example when we move from lobby into the meeting.
+   *
+   * @returns {void}
+   */
+  public sendNextMetrics() {
+    this.shouldSendMetricsOnNextStatsReport = true;
+  }
+
   /**
    * Add metrics items to the metrics queue.
    *
@@ -79,6 +91,13 @@ export default class RtcMetrics {
 
       this.metricsQueue.push(data);
 
+      if (this.shouldSendMetricsOnNextStatsReport && data.name === 'stats-report') {
+        // this is the first useful set of data (WCME gives it to us after 5s), send it out immediately
+        // in case the user is unhappy and closes the browser early
+        this.sendMetricsInQueue();
+        this.shouldSendMetricsOnNextStatsReport = false;
+      }
+
       try {
         // If a connection fails, send the rest of the metrics in queue and get a new connection id.
         const parsedPayload = parseJsonPayload(data.payload);
@@ -88,7 +107,7 @@ export default class RtcMetrics {
           parsedPayload.value === 'failed'
         ) {
           this.sendMetricsInQueue();
-          this.setNewConnectionId();
+          this.resetConnection();
         }
       } catch (e) {
         console.error(e);
@@ -130,8 +149,9 @@ export default class RtcMetrics {
    *
    * @returns {void}
    */
-  private setNewConnectionId() {
+  private resetConnection() {
     this.connectionId = uuid.v4();
+    this.shouldSendMetricsOnNextStatsReport = true;
   }
 
   /**

package/test/unit/spec/breakouts/index.ts

@@ -87,6 +87,7 @@ describe('plugin-meetings', () => {
       // @ts-ignore
       webex = new MockWebex({});
       webex.internal.llm.on = sinon.stub();
+      webex.internal.llm.isConnected = sinon.stub();
       webex.internal.mercury.on = sinon.stub();
       breakouts = new Breakouts({}, {parent: webex});
       breakouts.groupId = 'groupId';
@@ -225,38 +226,6 @@ describe('plugin-meetings', () => {
       });
     });
 
-    describe('#listenToBroadcastMessages', () => {
-      it('triggers message event when a message received', () => {
-        const call = webex.internal.llm.on.getCall(0);
-        const callback = call.args[1];
-
-        assert.equal(call.args[0], 'event:breakout.message');
-
-        let message;
-
-        breakouts.listenTo(breakouts, BREAKOUTS.EVENTS.MESSAGE, (event) => {
-          message = event;
-        });
-
-        breakouts.currentBreakoutSession.sessionId = 'sessionId';
-
-        callback({
-          data: {
-            senderUserId: 'senderUserId',
-            sentTime: 'sentTime',
-            message: 'message',
-          },
-        });
-
-        assert.deepEqual(message, {
-          senderUserId: 'senderUserId',
-          sentTime: 'sentTime',
-          message: 'message',
-          sessionId: 'sessionId',
-        });
-      });
-    });
-
     describe('#listenToBreakoutRosters', () => {
       it('triggers member update event when a roster received', () => {
         const call = webex.internal.mercury.on.getCall(0);
@@ -496,8 +465,58 @@ describe('plugin-meetings', () => {
     describe('#locusUrlUpdate', () => {
       it('sets the locus url', () => {
         breakouts.locusUrlUpdate('newUrl');
+        assert.equal(breakouts.locusUrl, 'newUrl');
+      });
+    });
+
+    describe('#listenToBroadcastMessages', () => {
+      it('do not subscribe message if llm not connected', () => {
+        webex.internal.llm.isConnected = sinon.stub().returns(false);
+        breakouts.listenTo = sinon.stub();
+        breakouts.locusUrlUpdate('newUrl');
+        assert.equal(breakouts.locusUrl, 'newUrl');
+        assert.notCalled(breakouts.listenTo);
+      });
 
+      it('do not subscribe message if already done', () => {
+        webex.internal.llm.isConnected = sinon.stub().returns(true);
+        breakouts.hasSubscribedToMessage = true;
+        breakouts.listenTo = sinon.stub();
+        breakouts.locusUrlUpdate('newUrl');
         assert.equal(breakouts.locusUrl, 'newUrl');
+        assert.notCalled(breakouts.listenTo);
+      });
+
+      it('triggers message event when a message received', () => {
+        webex.internal.llm.isConnected = sinon.stub().returns(true);
+        breakouts.locusUrlUpdate('newUrl');
+        const call = webex.internal.llm.on.getCall(0);
+        const callback = call.args[1];
+
+        assert.equal(call.args[0], 'event:breakout.message');
+
+        let message;
+
+        breakouts.listenTo(breakouts, BREAKOUTS.EVENTS.MESSAGE, (event) => {
+          message = event;
+        });
+
+        breakouts.currentBreakoutSession.sessionId = 'sessionId';
+
+        callback({
+          data: {
+            senderUserId: 'senderUserId',
+            sentTime: 'sentTime',
+            message: 'message',
+          },
+        });
+
+        assert.deepEqual(message, {
+          senderUserId: 'senderUserId',
+          sentTime: 'sentTime',
+          message: 'message',
+          sessionId: 'sessionId',
+        });
       });
     });