@webex/plugin-meetings 3.10.0-next.27 → 3.10.0-next.29

package/dist/types/reachability/clusterReachability.d.ts

@@ -23,26 +23,53 @@ export declare const Events: {
 export type Events = Enum<typeof Events>;
 /**
  * A class that handles reachability checks for a single cluster.
- * Creates and orchestrates a ReachabilityPeerConnection instance.
+ * Creates and orchestrates ReachabilityPeerConnection instance(s).
  * Listens to events and emits them to consumers.
+ *
+ * When enablePerUdpUrlReachability is true:
+ *   - Creates one ReachabilityPeerConnection for each UDP URL
+ *   - Creates one ReachabilityPeerConnection for all TCP and TLS URLs together
+ * Otherwise:
+ *   - Creates a single ReachabilityPeerConnection for all URLs
  */
 export declare class ClusterReachability extends EventsScope {
     private reachabilityPeerConnection;
+    private reachabilityPeerConnectionsForUdp;
     readonly isVideoMesh: boolean;
     readonly name: any;
     readonly reachedSubnets: Set<string>;
+    private enablePerUdpUrlReachability;
+    private udpResultEmitted;
     /**
      * Constructor for ClusterReachability
      * @param {string} name cluster name
      * @param {ClusterNode} clusterInfo information about the media cluster
+     * @param {boolean} enablePerUdpUrlReachability whether to create separate peer connections per UDP URL
      */
-    constructor(name: string, clusterInfo: ClusterNode);
+    constructor(name: string, clusterInfo: ClusterNode, enablePerUdpUrlReachability?: boolean);
     /**
-     * Sets up event listeners for the ReachabilityPeerConnection instance
+     * Initializes a single ReachabilityPeerConnection for all protocols
+     * @param {ClusterNode} clusterInfo information about the media cluster
+     * @returns {void}
+     */
+    private initializeSingleReachabilityPeerConnection;
+    /**
+     * Initializes per-URL UDP reachability checks:
+     * - One ReachabilityPeerConnection per UDP URL
+     * - One ReachabilityPeerConnection for all TCP and TLS URLs together
+     * @param {ClusterNode} clusterInfo information about the media cluster
+     * @returns {void}
+     */
+    private initializePerUdpUrlReachabilityCheck;
+    /**
+     * Sets up event listeners for a ReachabilityPeerConnection instance
+     * @param {ReachabilityPeerConnection} rpc the ReachabilityPeerConnection instance
+     * @param {boolean} isUdpPerUrl whether this is a per-URL UDP instance
      * @returns {void}
      */
     private setupReachabilityPeerConnectionEventListeners;
     /**
+     * Gets the aggregated reachability result for this cluster.
      * @returns {ClusterReachabilityResult} reachability result for this cluster
      */
     getResult(): ClusterReachabilityResult;

package/dist/webinar/index.js

@@ -448,7 +448,7 @@ var Webinar = _webexCore.WebexPlugin.extend({
       }, _callee7);
     }))();
   },
-  version: "3.10.0-next.27"
+  version: "3.10.0-next.29"
 });
 var _default = exports.default = Webinar;
 //# sourceMappingURL=index.js.map

package/package.json

@@ -93,5 +93,5 @@
   "//": [
     "TODO: upgrade jwt-decode when moving to node 18"
   ],
-  "version": "3.10.0-next.27"
+  "version": "3.10.0-next.29"
 }

package/src/config.ts

@@ -100,5 +100,6 @@ export default {
     logUploadIntervalMultiplicationFactor: 0, // if set to 0 or undefined, logs won't be uploaded periodically, if you want periodic logs, recommended value is 1
     stopIceGatheringAfterFirstRelayCandidate: false,
     enableAudioTwccForMultistream: false,
+    enablePerUdpUrlReachability: false, // true: separate peer connection per each UDP URL; false: single peer connection for all URLs
   },
 };

package/src/hashTree/hashTreeParser.ts

@@ -3,9 +3,9 @@ import HashTree, {LeafDataItem} from './hashTree';
 import LoggerProxy from '../common/logs/logger-proxy';
 import {Enum, HTTP_VERBS} from '../constants';
 import {DataSetNames, EMPTY_HASH} from './constants';
-import {ObjectType, HtMeta} from './types';
+import {ObjectType, HtMeta, HashTreeObject} from './types';
 import {LocusDTO} from '../locus-info/types';
-import {deleteNestedObjectsWithHtMeta} from './utils';
+import {deleteNestedObjectsWithHtMeta, isSelf} from './utils';
 
 export interface DataSet {
   url: string;
@@ -20,11 +20,6 @@ export interface DataSet {
   };
 }
 
-export interface HashTreeObject {
-  htMeta: HtMeta;
-  data: Record<string, any>;
-}
-
 export interface RootHashMessage {
   dataSets: Array<DataSet>;
 }
@@ -60,15 +55,6 @@ export type LocusInfoUpdateCallback = (
  */
 class MeetingEndedError extends Error {}
 
-/**
- * Checks if the given hash tree object is of type "self"
- * @param {HashTreeObject} object object to check
- * @returns {boolean} True if the object is of type "self", false otherwise
- */
-export function isSelf(object: HashTreeObject) {
-  return object.htMeta.elementId.type.toLowerCase() === ObjectType.self;
-}
-
 /**
  * Parses hash tree eventing locus data
  */

package/src/hashTree/types.ts

@@ -32,3 +32,8 @@ export interface HtMeta {
   };
   dataSetNames: string[];
 }
+
+export interface HashTreeObject {
+  htMeta: HtMeta;
+  data: Record<string, any>;
+}

package/src/hashTree/utils.ts

@@ -1,5 +1,16 @@
 /* eslint-disable import/prefer-default-export */
 
+import {ObjectType, HashTreeObject} from './types';
+
+/**
+ * Checks if the given hash tree object is of type "self"
+ * @param {HashTreeObject} object object to check
+ * @returns {boolean} True if the object is of type "self", false otherwise
+ */
+export function isSelf(object: HashTreeObject) {
+  return object.htMeta.elementId.type.toLowerCase() === ObjectType.self;
+}
+
 /**
  * Analyzes given part of Locus DTO recursively and delete any nested objects that have their own htMeta
  *

package/src/locus-info/index.ts

@@ -34,11 +34,10 @@ import BEHAVIORAL_METRICS from '../metrics/constants';
 import HashTreeParser, {
   DataSet,
   HashTreeMessage,
-  HashTreeObject,
-  isSelf,
   LocusInfoUpdateType,
 } from '../hashTree/hashTreeParser';
-import {ObjectType, ObjectTypeToLocusKeyMap} from '../hashTree/types';
+import {HashTreeObject, ObjectType, ObjectTypeToLocusKeyMap} from '../hashTree/types';
+import {isSelf} from '../hashTree/utils';
 import {Links, LocusDTO, LocusFullState} from './types';
 
 export type LocusLLMEvent = {

package/src/meetings/index.ts

@@ -67,6 +67,8 @@ import {SpaceIDDeprecatedError} from '../common/errors/webex-errors';
 import NoMeetingInfoError from '../common/errors/no-meeting-info';
 import JoinForbiddenError from '../common/errors/join-forbidden-error';
 import {HashTreeMessage} from '../hashTree/hashTreeParser';
+import {HashTreeObject} from '../hashTree/types';
+import {isSelf} from '../hashTree/utils';
 
 let mediaLogger;
 
@@ -420,31 +422,36 @@ export default class Meetings extends WebexPlugin {
    * @memberof Meetings
    */
   getCorrespondingMeetingByLocus(data: LocusEvent) {
-    if (
-      data.eventType === LOCUSEVENT.HASH_TREE_DATA_UPDATED &&
-      data.stateElementsMessage?.locusUrl
-    ) {
-      return this.meetingCollection.getByKey(
-        MEETING_KEY.LOCUS_URL,
-        data.stateElementsMessage.locusUrl
-      );
+    const locusUrl =
+      data.stateElementsMessage?.locusUrl || // hash tree event
+      data.locusUrl; // classic event
+
+    // first try to find by locusUrl - that's the simplest and quickest way
+    const existingMeeting = this.meetingCollection.getByKey(MEETING_KEY.LOCUS_URL, locusUrl);
+
+    if (existingMeeting) {
+      return existingMeeting;
     }
 
-    // getting meeting by correlationId. This will happen for the new event
-    // Either the locus
-    // TODO : Add check for the callBack Address
+    // if that didn't work, fallback to other fields like correlationId, sipUri, etc
+
+    // If the event is a hash tree event, we need to extract "self" object from it
+    // We don't care about the version, just need to find the meeting this event is for,
+    // so any hash tree object of type "self" will do
+    const hashTreeEventSelf = data.stateElementsMessage?.locusStateElements?.find(
+      (obj: HashTreeObject) => isSelf(obj)
+    )?.data;
+
+    const self = hashTreeEventSelf || data.locus?.self;
+
     return (
-      this.meetingCollection.getByKey(MEETING_KEY.LOCUS_URL, data.locusUrl) ||
       // @ts-ignore
       this.meetingCollection.getByKey(
         MEETING_KEY.CORRELATION_ID,
         // @ts-ignore
-        MeetingsUtil.checkForCorrelationId(this.webex.internal.device.url, data.locus)
-      ) ||
-      this.meetingCollection.getByKey(
-        MEETING_KEY.SIP_URI,
-        data.locus?.self?.callbackInfo?.callbackAddress
+        MeetingsUtil.getCorrelationIdForDevice(this.webex.internal.device.url, self)
       ) ||
+      this.meetingCollection.getByKey(MEETING_KEY.SIP_URI, self?.callbackInfo?.callbackAddress) ||
       (data.locus?.info?.isUnifiedSpaceMeeting
         ? undefined
         : this.meetingCollection.getByKey(

package/src/meetings/util.ts

@@ -117,15 +117,16 @@ MeetingsUtil.getMediaServerIp = (sdp) => {
   return mediaServerIp;
 };
 
-MeetingsUtil.checkForCorrelationId = (deviceUrl, locus) => {
-  let devices = [];
-
-  if (locus) {
-    if (locus && locus.self && locus.self.devices) {
-      devices = locus.self.devices;
-    }
-
-    const foundDevice = devices.find((device) => device.url === deviceUrl);
+/**
+ * Finds correlationId of a device from locus self devices array
+ * that matches the given deviceUrl
+ * @param {string} deviceUrl
+ * @param {object} locusSelf
+ * @returns {string|false} correlationId or false if not found
+ */
+MeetingsUtil.getCorrelationIdForDevice = (deviceUrl: string, locusSelf: any) => {
+  if (locusSelf?.devices) {
+    const foundDevice = locusSelf?.devices.find((device) => device.url === deviceUrl);
 
     if (foundDevice && foundDevice.correlationId) {
       return foundDevice.correlationId;

package/src/reachability/clusterReachability.ts

@@ -1,5 +1,6 @@
 import {ClusterNode} from './request';
 import EventsScope from '../common/events/events-scope';
+import LoggerProxy from '../common/logs/logger-proxy';
 
 import {Enum} from '../constants';
 import {
@@ -37,36 +38,117 @@ export type Events = Enum<typeof Events>;
 
 /**
  * A class that handles reachability checks for a single cluster.
- * Creates and orchestrates a ReachabilityPeerConnection instance.
+ * Creates and orchestrates ReachabilityPeerConnection instance(s).
  * Listens to events and emits them to consumers.
+ *
+ * When enablePerUdpUrlReachability is true:
+ *   - Creates one ReachabilityPeerConnection for each UDP URL
+ *   - Creates one ReachabilityPeerConnection for all TCP and TLS URLs together
+ * Otherwise:
+ *   - Creates a single ReachabilityPeerConnection for all URLs
  */
 export class ClusterReachability extends EventsScope {
-  private reachabilityPeerConnection: ReachabilityPeerConnection;
+  private reachabilityPeerConnection: ReachabilityPeerConnection | null = null;
+  private reachabilityPeerConnectionsForUdp: ReachabilityPeerConnection[] = [];
+
   public readonly isVideoMesh: boolean;
   public readonly name;
   public readonly reachedSubnets: Set<string> = new Set();
 
+  private enablePerUdpUrlReachability: boolean;
+  private udpResultEmitted = false;
+
   /**
    * Constructor for ClusterReachability
    * @param {string} name cluster name
    * @param {ClusterNode} clusterInfo information about the media cluster
+   * @param {boolean} enablePerUdpUrlReachability whether to create separate peer connections per UDP URL
    */
-  constructor(name: string, clusterInfo: ClusterNode) {
+  constructor(name: string, clusterInfo: ClusterNode, enablePerUdpUrlReachability = false) {
     super();
     this.name = name;
     this.isVideoMesh = clusterInfo.isVideoMesh;
+    this.enablePerUdpUrlReachability = enablePerUdpUrlReachability;
 
-    this.reachabilityPeerConnection = new ReachabilityPeerConnection(name, clusterInfo);
+    if (this.enablePerUdpUrlReachability) {
+      this.initializePerUdpUrlReachabilityCheck(clusterInfo);
+    } else {
+      this.initializeSingleReachabilityPeerConnection(clusterInfo);
+    }
+  }
 
-    this.setupReachabilityPeerConnectionEventListeners();
+  /**
+   * Initializes a single ReachabilityPeerConnection for all protocols
+   * @param {ClusterNode} clusterInfo information about the media cluster
+   * @returns {void}
+   */
+  private initializeSingleReachabilityPeerConnection(clusterInfo: ClusterNode) {
+    this.reachabilityPeerConnection = new ReachabilityPeerConnection(this.name, clusterInfo);
+    this.setupReachabilityPeerConnectionEventListeners(this.reachabilityPeerConnection);
   }
 
   /**
-   * Sets up event listeners for the ReachabilityPeerConnection instance
+   * Initializes per-URL UDP reachability checks:
+   * - One ReachabilityPeerConnection per UDP URL
+   * - One ReachabilityPeerConnection for all TCP and TLS URLs together
+   * @param {ClusterNode} clusterInfo information about the media cluster
    * @returns {void}
    */
-  private setupReachabilityPeerConnectionEventListeners() {
-    this.reachabilityPeerConnection.on(ReachabilityPeerConnectionEvents.resultReady, (data) => {
+  private initializePerUdpUrlReachabilityCheck(clusterInfo: ClusterNode) {
+    LoggerProxy.logger.log(
+      `ClusterReachability#initializePerUdpUrlReachabilityCheck --> cluster: ${this.name}, performing per-URL UDP reachability for ${clusterInfo.udp.length} URLs`
+    );
+
+    // Create one ReachabilityPeerConnection for each UDP URL
+    clusterInfo.udp.forEach((udpUrl) => {
+      const singleUdpClusterInfo: ClusterNode = {
+        isVideoMesh: clusterInfo.isVideoMesh,
+        udp: [udpUrl],
+        tcp: [],
+        xtls: [],
+      };
+      const rpc = new ReachabilityPeerConnection(this.name, singleUdpClusterInfo);
+      this.setupReachabilityPeerConnectionEventListeners(rpc, true);
+      this.reachabilityPeerConnectionsForUdp.push(rpc);
+    });
+
+    // Create one ReachabilityPeerConnection for all TCP and TLS URLs together
+    if (clusterInfo.tcp.length > 0 || clusterInfo.xtls.length > 0) {
+      const tcpTlsClusterInfo: ClusterNode = {
+        isVideoMesh: clusterInfo.isVideoMesh,
+        udp: [],
+        tcp: clusterInfo.tcp,
+        xtls: clusterInfo.xtls,
+      };
+      this.reachabilityPeerConnection = new ReachabilityPeerConnection(
+        this.name,
+        tcpTlsClusterInfo
+      );
+      this.setupReachabilityPeerConnectionEventListeners(this.reachabilityPeerConnection);
+    }
+  }
+
+  /**
+   * Sets up event listeners for a ReachabilityPeerConnection instance
+   * @param {ReachabilityPeerConnection} rpc the ReachabilityPeerConnection instance
+   * @param {boolean} isUdpPerUrl whether this is a per-URL UDP instance
+   * @returns {void}
+   */
+  private setupReachabilityPeerConnectionEventListeners(
+    rpc: ReachabilityPeerConnection,
+    isUdpPerUrl = false
+  ) {
+    rpc.on(ReachabilityPeerConnectionEvents.resultReady, (data) => {
+      // For per-URL UDP checks, only emit the first successful UDP result
+      if (isUdpPerUrl && data.protocol === 'udp') {
+        if (this.udpResultEmitted) {
+          return;
+        }
+        if (data.result === 'reachable') {
+          this.udpResultEmitted = true;
+        }
+      }
+
       this.emit(
         {
           file: 'clusterReachability',
@@ -77,21 +159,18 @@ export class ClusterReachability extends EventsScope {
       );
     });
 
-    this.reachabilityPeerConnection.on(
-      ReachabilityPeerConnectionEvents.clientMediaIpsUpdated,
-      (data) => {
-        this.emit(
-          {
-            file: 'clusterReachability',
-            function: 'setupReachabilityPeerConnectionEventListeners',
-          },
-          Events.clientMediaIpsUpdated,
-          data
-        );
-      }
-    );
+    rpc.on(ReachabilityPeerConnectionEvents.clientMediaIpsUpdated, (data) => {
+      this.emit(
+        {
+          file: 'clusterReachability',
+          function: 'setupReachabilityPeerConnectionEventListeners',
+        },
+        Events.clientMediaIpsUpdated,
+        data
+      );
+    });
 
-    this.reachabilityPeerConnection.on(ReachabilityPeerConnectionEvents.natTypeUpdated, (data) => {
+    rpc.on(ReachabilityPeerConnectionEvents.natTypeUpdated, (data) => {
       this.emit(
         {
           file: 'clusterReachability',
@@ -102,18 +181,54 @@ export class ClusterReachability extends EventsScope {
       );
     });
 
-    this.reachabilityPeerConnection.on(ReachabilityPeerConnectionEvents.reachedSubnets, (data) => {
-      data.subnets.forEach((subnet) => {
+    rpc.on(ReachabilityPeerConnectionEvents.reachedSubnets, (data) => {
+      data.subnets.forEach((subnet: string) => {
         this.reachedSubnets.add(subnet);
       });
     });
   }
 
   /**
+   * Gets the aggregated reachability result for this cluster.
    * @returns {ClusterReachabilityResult} reachability result for this cluster
    */
   getResult(): ClusterReachabilityResult {
-    return this.reachabilityPeerConnection.getResult();
+    if (!this.enablePerUdpUrlReachability) {
+      return (
+        this.reachabilityPeerConnection?.getResult() ?? {
+          udp: {result: 'untested'},
+          tcp: {result: 'untested'},
+          xtls: {result: 'untested'},
+        }
+      );
+    }
+
+    const result: ClusterReachabilityResult = {
+      udp: {result: 'untested'},
+      tcp: {result: 'untested'},
+      xtls: {result: 'untested'},
+    };
+
+    // Get the first reachable UDP result from per-URL instances
+    for (const rpc of this.reachabilityPeerConnectionsForUdp) {
+      const rpcResult = rpc.getResult();
+      if (rpcResult.udp.result === 'reachable') {
+        result.udp = rpcResult.udp;
+        break;
+      }
+      if (rpcResult.udp.result === 'unreachable' && result.udp.result === 'untested') {
+        result.udp = rpcResult.udp;
+      }
+    }
+
+    // Get TCP and TLS results from the main peer connection
+    if (this.reachabilityPeerConnection) {
+      const mainResult = this.reachabilityPeerConnection.getResult();
+      result.tcp = mainResult.tcp;
+      result.xtls = mainResult.xtls;
+    }
+
+    return result;
   }
 
   /**
@@ -121,7 +236,17 @@ export class ClusterReachability extends EventsScope {
    * @returns {Promise<ClusterReachabilityResult>}
    */
   async start(): Promise<ClusterReachabilityResult> {
-    await this.reachabilityPeerConnection.start();
+    const startPromises: Promise<ClusterReachabilityResult>[] = [];
+
+    this.reachabilityPeerConnectionsForUdp.forEach((rpc) => {
+      startPromises.push(rpc.start());
+    });
+
+    if (this.reachabilityPeerConnection) {
+      startPromises.push(this.reachabilityPeerConnection.start());
+    }
+
+    await Promise.all(startPromises);
 
     return this.getResult();
   }
@@ -131,6 +256,7 @@ export class ClusterReachability extends EventsScope {
    * @returns {void}
    */
   public abort() {
-    this.reachabilityPeerConnection.abort();
+    this.reachabilityPeerConnectionsForUdp.forEach((rpc) => rpc.abort());
+    this.reachabilityPeerConnection?.abort();
   }
 }

package/src/reachability/index.ts

@@ -961,7 +961,12 @@ export default class Reachability extends EventsScope {
     Object.keys(clusterList).forEach((key) => {
       const cluster = clusterList[key];
 
-      this.clusterReachability[key] = new ClusterReachability(key, cluster);
+      this.clusterReachability[key] = new ClusterReachability(
+        key,
+        cluster,
+        // @ts-ignore
+        this.webex.config.meetings.enablePerUdpUrlReachability
+      );
       this.clusterReachability[key].on(Events.resultReady, async (data: ResultEventData) => {
         const {protocol, result, clientMediaIPs, latencyInMilliseconds} = data;
 

package/src/reachability/reachabilityPeerConnection.ts

@@ -243,7 +243,9 @@ export class ReachabilityPeerConnection extends EventsScope {
     if (result.latencyInMilliseconds === undefined) {
       LoggerProxy.logger.log(
         // @ts-ignore
-        `Reachability:ReachabilityPeerConnection#saveResult --> Successfully reached ${this.clusterName} over ${protocol}: ${latency}ms`
+        `Reachability:ReachabilityPeerConnection#saveResult --> Successfully reached ${
+          this.clusterName
+        } over ${protocol}: ${latency}ms, serverIp=${serverIp || 'unknown'}`
       );
       result.latencyInMilliseconds = latency;
       result.result = 'reachable';

package/test/unit/spec/hashTree/utils.ts

@@ -1,4 +1,5 @@
-import {deleteNestedObjectsWithHtMeta} from '../../../../src/hashTree/utils';
+import {HashTreeObject, ObjectType} from '../../../../src/hashTree/types';
+import {deleteNestedObjectsWithHtMeta, isSelf} from '../../../../src/hashTree/utils';
 
 import {assert} from '@webex/test-helper-chai';
 
@@ -100,4 +101,40 @@ describe('Hash Tree Utils', () => {
       });
     });
   });
+
+  describe('#isSelf', () => {
+    ['self', 'SELF', 'Self'].forEach((type) => {
+      it(`should return true for object with type="${type}"`, () => {
+        const selfObject = {
+          htMeta: {
+            elementId: {
+              type,
+              id: 1,
+              version: 1,
+            },
+            dataSetNames: [],
+          },
+          data: {},
+        };
+
+        assert.isTrue(isSelf(selfObject as HashTreeObject));
+      });
+    });
+
+    it('should return false for non-self object', () => {
+      const participantObject = {
+        htMeta: {
+          elementId: {
+            type: ObjectType.participant,
+            id: 2,
+            version: 1,
+          },
+          dataSetNames: [],
+        },
+        data: {},
+      };
+
+      assert.isFalse(isSelf(participantObject));
+    });
+  });
 });