@webex/plugin-meetings 3.0.0-beta.4 → 3.0.0-beta.400

package/src/reachability/clusterReachability.ts

@@ -0,0 +1,320 @@
+import {Defer} from '@webex/common';
+
+import LoggerProxy from '../common/logs/logger-proxy';
+import {ClusterNode} from './request';
+import {convertStunUrlToTurn} from './util';
+
+import {ICE_GATHERING_STATE, CONNECTION_STATE} from '../constants';
+
+const DEFAULT_TIMEOUT = 3000;
+const VIDEO_MESH_TIMEOUT = 1000;
+
+// result for a specific transport protocol (like udp or tcp)
+export type TransportResult = {
+  result: 'reachable' | 'unreachable' | 'untested';
+  latencyInMilliseconds?: number; // amount of time it took to get the first ICE candidate
+  clientMediaIPs?: string[];
+};
+
+// reachability result for a specific media cluster
+export type ClusterReachabilityResult = {
+  udp: TransportResult;
+  tcp: TransportResult;
+  xtls: TransportResult;
+};
+
+/**
+ * A class that handles reachability checks for a single cluster.
+ */
+export class ClusterReachability {
+  private numUdpUrls: number;
+  private numTcpUrls: number;
+  private result: ClusterReachabilityResult;
+  private pc?: RTCPeerConnection;
+  private defer: Defer; // this defer is resolved once reachability checks for this cluster are completed
+  private startTimestamp: number;
+  public readonly isVideoMesh: boolean;
+  public readonly name;
+
+  /**
+   * Constructor for ClusterReachability
+   * @param {string} name cluster name
+   * @param {ClusterNode} clusterInfo information about the media cluster
+   */
+  constructor(name: string, clusterInfo: ClusterNode) {
+    this.name = name;
+    this.isVideoMesh = clusterInfo.isVideoMesh;
+    this.numUdpUrls = clusterInfo.udp.length;
+    this.numTcpUrls = clusterInfo.tcp.length;
+
+    this.pc = this.createPeerConnection(clusterInfo);
+
+    this.defer = new Defer();
+    this.result = {
+      udp: {
+        result: 'untested',
+      },
+      tcp: {
+        result: 'untested',
+      },
+      xtls: {
+        result: 'untested',
+      },
+    };
+  }
+
+  /**
+   * Gets total elapsed time, can be called only after start() is called
+   * @returns {Number} Milliseconds
+   */
+  private getElapsedTime() {
+    return Math.round(performance.now() - this.startTimestamp);
+  }
+
+  /**
+   * Generate peerConnection config settings
+   * @param {ClusterNode} cluster
+   * @returns {RTCConfiguration} peerConnectionConfig
+   */
+  private buildPeerConnectionConfig(cluster: ClusterNode): RTCConfiguration {
+    const udpIceServers = cluster.udp.map((url) => ({
+      username: '',
+      credential: '',
+      urls: [url],
+    }));
+
+    // STUN servers are contacted only using UDP, so in order to test TCP reachability
+    // we pretend that Linus is a TURN server, because we can explicitly say "transport=tcp" in TURN urls.
+    // We then check for relay candidates to know if TURN-TCP worked (see registerIceCandidateListener()).
+    const tcpIceServers = cluster.tcp.map((urlString: string) => {
+      return {
+        username: 'webexturnreachuser',
+        credential: 'webexturnreachpwd',
+        urls: [convertStunUrlToTurn(urlString, 'tcp')],
+      };
+    });
+
+    return {
+      iceServers: [...udpIceServers, ...tcpIceServers],
+      iceCandidatePoolSize: 0,
+      iceTransportPolicy: 'all',
+    };
+  }
+
+  /**
+   * Creates an RTCPeerConnection
+   * @param {ClusterNode} clusterInfo information about the media cluster
+   * @returns {RTCPeerConnection} peerConnection
+   */
+  private createPeerConnection(clusterInfo: ClusterNode) {
+    try {
+      const config = this.buildPeerConnectionConfig(clusterInfo);
+
+      const peerConnection = new RTCPeerConnection(config);
+
+      return peerConnection;
+    } catch (peerConnectionError) {
+      LoggerProxy.logger.warn(
+        `Reachability:index#createPeerConnection --> Error creating peerConnection:`,
+        peerConnectionError
+      );
+
+      return undefined;
+    }
+  }
+
+  /**
+   * @returns {ClusterReachabilityResult} reachability result for this cluster
+   */
+  getResult() {
+    return this.result;
+  }
+
+  /**
+   * Closes the peerConnection
+   *
+   * @returns {void}
+   */
+  private closePeerConnection() {
+    if (this.pc) {
+      this.pc.onicecandidate = null;
+      this.pc.onicegatheringstatechange = null;
+      this.pc.close();
+    }
+  }
+
+  /**
+   * Resolves the defer, indicating that reachability checks for this cluster are completed
+   *
+   * @returns {void}
+   */
+  private finishReachabilityCheck() {
+    this.defer.resolve();
+  }
+
+  /**
+   * Adds public IP (client media IPs)
+   * @param {string} protocol
+   * @param {string} publicIP
+   * @returns {void}
+   */
+  private addPublicIP(protocol: 'udp' | 'tcp', publicIP?: string | null) {
+    const result = this.result[protocol];
+
+    if (publicIP) {
+      if (result.clientMediaIPs) {
+        if (!result.clientMediaIPs.includes(publicIP)) {
+          result.clientMediaIPs.push(publicIP);
+        }
+      } else {
+        result.clientMediaIPs = [publicIP];
+      }
+    }
+  }
+
+  /**
+   * Registers a listener for the iceGatheringStateChange event
+   *
+   * @returns {void}
+   */
+  private registerIceGatheringStateChangeListener() {
+    this.pc.onicegatheringstatechange = () => {
+      const {COMPLETE} = ICE_GATHERING_STATE;
+
+      if (this.pc.iceConnectionState === COMPLETE) {
+        this.closePeerConnection();
+        this.finishReachabilityCheck();
+      }
+    };
+  }
+
+  /**
+   * Checks if we have the results for all the protocols (UDP and TCP)
+   *
+   * @returns {boolean} true if we have all results, false otherwise
+   */
+  private haveWeGotAllResults(): boolean {
+    return ['udp', 'tcp'].every(
+      (protocol) =>
+        this.result[protocol].result === 'reachable' || this.result[protocol].result === 'untested'
+    );
+  }
+
+  /**
+   * Stores the latency in the result for the given protocol and marks it as reachable
+   *
+   * @param {string} protocol
+   * @param {number} latency
+   * @returns {void}
+   */
+  private storeLatencyResult(protocol: 'udp' | 'tcp', latency: number) {
+    const result = this.result[protocol];
+
+    if (result.latencyInMilliseconds === undefined) {
+      LoggerProxy.logger.log(
+        // @ts-ignore
+        `Reachability:index#storeLatencyResult --> Successfully reached ${this.name} over ${protocol}: ${latency}ms`
+      );
+      result.latencyInMilliseconds = latency;
+      result.result = 'reachable';
+    }
+  }
+
+  /**
+   * Registers a listener for the icecandidate event
+   *
+   * @returns {void}
+   */
+  private registerIceCandidateListener() {
+    this.pc.onicecandidate = (e) => {
+      const CANDIDATE_TYPES = {
+        SERVER_REFLEXIVE: 'srflx',
+        RELAY: 'relay',
+      };
+
+      if (e.candidate) {
+        if (e.candidate.type === CANDIDATE_TYPES.SERVER_REFLEXIVE) {
+          this.storeLatencyResult('udp', this.getElapsedTime());
+          this.addPublicIP('udp', e.candidate.address);
+        }
+
+        if (e.candidate.type === CANDIDATE_TYPES.RELAY) {
+          this.storeLatencyResult('tcp', this.getElapsedTime());
+          // we don't add public IP for TCP, because in the case of relay candidates
+          // e.candidate.address is the TURN server address, not the client's public IP
+        }
+
+        if (this.haveWeGotAllResults()) {
+          this.closePeerConnection();
+          this.finishReachabilityCheck();
+        }
+      }
+    };
+  }
+
+  /**
+   * Starts the process of doing UDP and TCP reachability checks on the media cluster.
+   * XTLS reachability checking is not supported.
+   *
+   * @returns {Promise}
+   */
+  async start(): Promise<ClusterReachabilityResult> {
+    if (!this.pc) {
+      LoggerProxy.logger.warn(
+        `Reachability:ClusterReachability#start --> Error: peerConnection is undefined`
+      );
+
+      return this.result;
+    }
+
+    // Initialize this.result as saying that nothing is reachable.
+    // It will get updated as we go along and successfully gather ICE candidates.
+    this.result.udp = {
+      result: this.numUdpUrls > 0 ? 'unreachable' : 'untested',
+    };
+    this.result.tcp = {
+      result: this.numTcpUrls > 0 ? 'unreachable' : 'untested',
+    };
+
+    try {
+      const offer = await this.pc.createOffer({offerToReceiveAudio: true});
+
+      this.startTimestamp = performance.now();
+
+      // not awaiting the next call on purpose, because we're not sending the offer anywhere and there won't be any answer
+      // we just need to make this call to trigger the ICE gathering process
+      this.pc.setLocalDescription(offer);
+
+      await this.gatherIceCandidates();
+    } catch (error) {
+      LoggerProxy.logger.warn(`Reachability:ClusterReachability#start --> Error: `, error);
+    }
+
+    return this.result;
+  }
+
+  /**
+   * Starts the process of gathering ICE candidates
+   *
+   * @returns {Promise} promise that's resolved once reachability checks for this cluster are completed or timeout is reached
+   */
+  private gatherIceCandidates() {
+    const timeout = this.isVideoMesh ? VIDEO_MESH_TIMEOUT : DEFAULT_TIMEOUT;
+
+    this.registerIceGatheringStateChangeListener();
+    this.registerIceCandidateListener();
+
+    // Set maximum timeout
+    setTimeout(() => {
+      const {CLOSED} = CONNECTION_STATE;
+
+      // Close any open peerConnections
+      if (this.pc.connectionState !== CLOSED) {
+        this.closePeerConnection();
+        this.finishReachabilityCheck();
+      }
+    }, timeout);
+
+    return this.defer.promise;
+  }
+}

package/src/reachability/index.ts

@@ -0,0 +1,371 @@
+/*!
+ * Copyright (c) 2015-2020 Cisco Systems, Inc. See LICENSE file.
+ */
+
+/* eslint-disable class-methods-use-this */
+import {mapValues} from 'lodash';
+
+import LoggerProxy from '../common/logs/logger-proxy';
+import MeetingUtil from '../meeting/util';
+
+import {REACHABILITY} from '../constants';
+
+import ReachabilityRequest, {ClusterList} from './request';
+import {
+  ClusterReachability,
+  ClusterReachabilityResult,
+  TransportResult,
+} from './clusterReachability';
+
+export type ReachabilityMetrics = {
+  reachability_public_udp_success: number;
+  reachability_public_udp_failed: number;
+  reachability_public_tcp_success: number;
+  reachability_public_tcp_failed: number;
+  reachability_vmn_udp_success: number;
+  reachability_vmn_udp_failed: number;
+  reachability_vmn_tcp_success: number;
+  reachability_vmn_tcp_failed: number;
+};
+
+/**
+ * This is the type that matches what backend expects us to send to them. It is a bit weird, because
+ * it uses strings instead of booleans and numbers, but that's what they require.
+ */
+export type TransportResultForBackend = {
+  reachable?: 'true' | 'false';
+  latencyInMilliseconds?: string;
+  clientMediaIPs?: string[];
+  untested?: 'true';
+};
+
+export type ReachabilityResultForBackend = {
+  udp: TransportResultForBackend;
+  tcp: TransportResultForBackend;
+  xtls: TransportResultForBackend;
+};
+
+// this is the type that is required by the backend when we send them reachability results
+export type ReachabilityResultsForBackend = Record<string, ReachabilityResultForBackend>;
+
+// this is the type used by Reachability class internally and stored in local storage
+export type ReachabilityResults = Record<
+  string,
+  ClusterReachabilityResult & {
+    isVideoMesh?: boolean;
+  }
+>;
+
+/**
+ * @class Reachability
+ * @export
+ */
+export default class Reachability {
+  namespace = REACHABILITY.namespace;
+  webex: object;
+  reachabilityRequest: ReachabilityRequest;
+  clusterReachability: {
+    [key: string]: ClusterReachability;
+  };
+
+  /**
+   * Creates an instance of Reachability.
+   * @param {object} webex
+   * @memberof Reachability
+   */
+  constructor(webex: object) {
+    this.webex = webex;
+
+    /**
+     * internal request object for the server
+     * @instance
+     * @type {Array}
+     * @private
+     * @memberof Reachability
+     */
+    this.reachabilityRequest = new ReachabilityRequest(this.webex);
+
+    this.clusterReachability = {};
+  }
+
+  /**
+   * Gets a list of media clusters from the backend and performs reachability checks on all the clusters
+   * @returns {Promise<ReachabilityResults>} reachability results
+   * @public
+   * @memberof Reachability
+   */
+  public async gatherReachability(): 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);
+
+      // @ts-ignore
+      await this.webex.boundedStorage.put(
+        this.namespace,
+        REACHABILITY.localStorageResult,
+        JSON.stringify(results)
+      );
+      // @ts-ignore
+      await this.webex.boundedStorage.put(
+        this.namespace,
+        REACHABILITY.localStorageJoinCookie,
+        JSON.stringify(joinCookie)
+      );
+
+      LoggerProxy.logger.log(
+        'Reachability:index#gatherReachability --> Reachability checks completed'
+      );
+
+      return results;
+    } catch (error) {
+      LoggerProxy.logger.error(`Reachability:index#gatherReachability --> Error:`, error);
+
+      return {};
+    }
+  }
+
+  /**
+   * Returns statistics about last reachability results. The returned value is an object
+   * with a flat list of properties so that it can be easily sent with metrics
+   *
+   * @returns {Promise} Promise with metrics values, it never rejects/throws.
+   */
+  async getReachabilityMetrics(): Promise<ReachabilityMetrics> {
+    const stats: ReachabilityMetrics = {
+      reachability_public_udp_success: 0,
+      reachability_public_udp_failed: 0,
+      reachability_public_tcp_success: 0,
+      reachability_public_tcp_failed: 0,
+      reachability_vmn_udp_success: 0,
+      reachability_vmn_udp_failed: 0,
+      reachability_vmn_tcp_success: 0,
+      reachability_vmn_tcp_failed: 0,
+    };
+
+    const updateStats = (clusterType: 'public' | 'vmn', result: ClusterReachabilityResult) => {
+      if (result.udp && result.udp.result !== 'untested') {
+        const outcome = result.udp.result === 'reachable' ? 'success' : 'failed';
+        stats[`reachability_${clusterType}_udp_${outcome}`] += 1;
+      }
+      if (result.tcp && result.tcp.result !== 'untested') {
+        const outcome = result.tcp.result === 'reachable' ? 'success' : 'failed';
+        stats[`reachability_${clusterType}_tcp_${outcome}`] += 1;
+      }
+    };
+
+    try {
+      // @ts-ignore
+      const resultsJson = await this.webex.boundedStorage.get(
+        REACHABILITY.namespace,
+        REACHABILITY.localStorageResult
+      );
+
+      const results: ReachabilityResults = JSON.parse(resultsJson);
+
+      Object.values(results).forEach((result) => {
+        updateStats(result.isVideoMesh ? 'vmn' : 'public', result);
+      });
+    } catch (e) {
+      // empty storage, that's ok
+      LoggerProxy.logger.warn(
+        'Roap:request#getReachabilityMetrics --> Error parsing reachability data: ',
+        e
+      );
+    }
+
+    return stats;
+  }
+
+  /**
+   * Maps our internal transport result to the format that backend expects
+   * @param {TransportResult} transportResult
+   * @returns {TransportResultForBackend}
+   */
+  private mapTransportResultToBackendDataFormat(
+    transportResult: TransportResult
+  ): TransportResultForBackend {
+    const output: TransportResultForBackend = {};
+
+    for (const [key, value] of Object.entries(transportResult)) {
+      switch (key) {
+        case 'result':
+          switch (value) {
+            case 'reachable':
+              output.reachable = 'true';
+              break;
+            case 'unreachable':
+              output.reachable = 'false';
+              break;
+            case 'untested':
+              output.untested = 'true';
+              break;
+          }
+          break;
+        case 'latencyInMilliseconds':
+          output.latencyInMilliseconds = value.toString();
+          break;
+        default:
+          output[key] = value;
+      }
+    }
+
+    return output;
+  }
+
+  /**
+   * Reachability results as an object in the format that backend expects
+   *
+   * @returns {any} reachability results that need to be sent to the backend
+   */
+  async getReachabilityResults(): Promise<ReachabilityResultsForBackend | undefined> {
+    let results: ReachabilityResultsForBackend;
+
+    try {
+      // @ts-ignore
+      const resultsJson = await this.webex.boundedStorage.get(
+        REACHABILITY.namespace,
+        REACHABILITY.localStorageResult
+      );
+
+      const allClusterResults: ReachabilityResults = JSON.parse(resultsJson);
+
+      results = mapValues(allClusterResults, (clusterResult) => ({
+        udp: this.mapTransportResultToBackendDataFormat(clusterResult.udp || {result: 'untested'}),
+        tcp: this.mapTransportResultToBackendDataFormat(clusterResult.tcp || {result: 'untested'}),
+        xtls: this.mapTransportResultToBackendDataFormat(
+          clusterResult.xtls || {result: 'untested'}
+        ),
+      }));
+    } catch (e) {
+      // empty storage, that's ok
+      LoggerProxy.logger.warn(
+        'Roap:request#attachReachabilityData --> Error parsing reachability data: ',
+        e
+      );
+    }
+
+    return results;
+  }
+
+  /**
+   * fetches reachability data and checks for cluster reachability
+   * @returns {boolean}
+   * @public
+   * @memberof Reachability
+   */
+  async isAnyPublicClusterReachable() {
+    let reachable = false;
+    // @ts-ignore
+    const reachabilityData = await this.webex.boundedStorage
+      .get(this.namespace, REACHABILITY.localStorageResult)
+      .catch(() => {});
+
+    if (reachabilityData) {
+      try {
+        const reachabilityResults: ReachabilityResults = JSON.parse(reachabilityData);
+
+        reachable = Object.values(reachabilityResults).some(
+          (result) =>
+            !result.isVideoMesh &&
+            (result.udp?.result === 'reachable' || result.tcp?.result === 'reachable')
+        );
+      } catch (e) {
+        LoggerProxy.logger.error(
+          `Roap:request#attachReachabilityData --> Error in parsing reachability data: ${e}`
+        );
+      }
+    }
+
+    return reachable;
+  }
+
+  /**
+   * Get list of all unreachable clusters
+   * @returns {array} Unreachable clusters
+   * @private
+   * @memberof Reachability
+   */
+  private getUnreachableClusters(): Array<{name: string; protocol: string}> {
+    const unreachableList = [];
+
+    Object.entries(this.clusterReachability).forEach(([key, clusterReachability]) => {
+      const result = clusterReachability.getResult();
+
+      if (result.udp.result === 'unreachable') {
+        unreachableList.push({name: key, protocol: 'udp'});
+      }
+      if (result.tcp.result === 'unreachable') {
+        unreachableList.push({name: key, protocol: 'tcp'});
+      }
+    });
+
+    return unreachableList;
+  }
+
+  /**
+   * Make a log of unreachable clusters.
+   * @returns {undefined}
+   * @private
+   * @memberof Reachability
+   */
+  private logUnreachableClusters() {
+    const list = this.getUnreachableClusters();
+
+    list.forEach(({name, protocol}) => {
+      LoggerProxy.logger.log(
+        `Reachability:index#logUnreachableClusters --> failed to reach ${name} over ${protocol}`
+      );
+    });
+  }
+
+  /**
+   * Performs reachability checks for all clusters
+   * @param {ClusterList} clusterList
+   * @returns {Promise<ReachabilityResults>} reachability check results
+   */
+  private async performReachabilityChecks(clusterList: ClusterList): Promise<ReachabilityResults> {
+    const results: ReachabilityResults = {};
+
+    if (!clusterList || !Object.keys(clusterList).length) {
+      return Promise.resolve(results);
+    }
+
+    LoggerProxy.logger.log(
+      `Reachability:index#performReachabilityChecks --> doing UDP${
+        // @ts-ignore
+        this.webex.config.meetings.experimental.enableTcpReachability ? ' and TCP' : ''
+      } reachability checks`
+    );
+
+    const clusterReachabilityChecks = Object.keys(clusterList).map((key) => {
+      const cluster = clusterList[key];
+
+      // Linus doesn't support TCP reachability checks on video mesh nodes
+      const includeTcpReachability =
+        // @ts-ignore
+        this.webex.config.meetings.experimental.enableTcpReachability && !cluster.isVideoMesh;
+
+      if (!includeTcpReachability) {
+        cluster.tcp = [];
+      }
+
+      this.clusterReachability[key] = new ClusterReachability(key, cluster);
+
+      return this.clusterReachability[key].start().then((result) => {
+        results[key] = result;
+        results[key].isVideoMesh = cluster.isVideoMesh;
+      });
+    });
+
+    await Promise.all(clusterReachabilityChecks);
+
+    this.logUnreachableClusters();
+
+    return results;
+  }
+}