@webex/plugin-meetings 3.12.0-next.60 → 3.12.0-next.62

package/dist/types/hashTree/constants.d.ts

@@ -8,3 +8,4 @@ export declare const DataSetNames: {
     UNJOINED: string;
 };
 export declare const DATA_SET_INIT_PRIORITY: string[];
+export declare const LLM_DATASET_NAMES: string[];

package/dist/types/hashTree/hashTreeParser.d.ts

@@ -2,6 +2,11 @@ import HashTree from './hashTree';
 import { Enum } from '../constants';
 import { HtMeta, HashTreeObject } from './types';
 import { LocusDTO } from '../locus-info/types';
+export declare enum SyncAllBackoffType {
+    NONE = "none",
+    ONLY_LLM = "onlyLLM",
+    ALL = "all"
+}
 export interface DataSet {
     url: string;
     root: string;
@@ -88,7 +93,8 @@ declare class HashTreeParser {
     state: 'active' | 'stopped';
     private syncQueue;
     private isSyncInProgress;
-    private isSyncAllInProgress;
+    private syncAllBackoffType;
+    private dataSetsSyncedDuringBackoff;
     private syncQueueProcessingPromise;
     /**
      * Constructor for HashTreeParser
@@ -341,6 +347,21 @@ declare class HashTreeParser {
      * @returns {void}
      */
     private cancelPendingSyncsForDataSets;
+    /**
+     * If a syncAllDatasets backoff sleep is in progress, marks the given data sets to be skipped
+     * after the sleep completes.
+     *
+     * @param {string[]} dataSetNames - The names of the data sets to mark
+     * @returns {void}
+     */
+    private markDataSetsForSyncAllBackoffSkip;
+    /**
+     * Aborts any in-flight sync HTTP requests for the specified data sets.
+     *
+     * @param {string[]} dataSetNames - The names of the data sets whose syncs should be aborted
+     * @returns {void}
+     */
+    private abortInFlightSyncs;
     /**
      * Enqueues a sync for the given data set. If the data set is already in the queue, the request is ignored.
      * This ensures that all syncs are executed sequentially and no more than 1 sync runs at a time.
@@ -357,14 +378,44 @@ declare class HashTreeParser {
      * @returns {Promise<void>}
      */
     private processSyncQueue;
+    /**
+     * sets the backoff type for syncAllDatasets calls, which determines the scope of datasets that will be synced after the backoff delay.
+     *
+     * @param {boolean} onlyLLM - Whether the backoff is for a syncAllDatasets call that is syncing only LLM datasets
+     * @returns {void}
+     */
+    private setSyncAllBackoffType;
+    /**
+     * Checks if a syncAll backoff is already in progress. If so, upgrades the scope from
+     * onlyLLM to all datasets when the new call has a broader scope.
+     *
+     * @param {boolean} onlyLLM - Whether the current call is for LLM datasets only
+     * @returns {boolean} true if a backoff is already pending (caller should return early)
+     */
+    private tryUpgradePendingBackoff;
     /**
      * Syncs all data sets that have hash trees, one by one in sequence, using the priority order
-     * provided by sortByInitPriority(). Does nothing if the parser is stopped or if a syncAllDatasets
-     * call is already in progress.
+     * provided by sortByInitPriority().
+     *
+     * If a call is already waiting in the backoff delay phase, a new call with a broader scope
+     * (onlyLLM=false) will upgrade the pending scope, and the dataset list will be computed after
+     * the backoff using the upgraded scope. After the backoff, the sync queue handles deduplication
+     * so no guard is needed.
      *
+     * @param {Object} [options={}] - Options for syncing
+     * @param {boolean} [options.onlyLLM=false] - Whether to sync only LLM based data sets
      * @returns {Promise<void>}
      */
-    syncAllDatasets(): Promise<void>;
+    syncAllDatasets(options?: {
+        onlyLLM?: boolean;
+    }): Promise<void>;
+    /**
+     * Returns the list of data sets that have hash trees, sorted by the priority order provided by sortByInitPriority().
+     *
+     * @param {boolean} onlyLLM - Whether to include only LLM based data sets
+     * @returns {Array<{name: string, backoff: {maxMs: number, exponent: number}}>} The sorted list of data sets with their backoff configurations
+     */
+    private getSortedDataSetsWithHashTrees;
     /**
      * Runs the sync algorithm for the given data set.
      *

package/dist/types/hashTree/utils.d.ts

@@ -31,3 +31,10 @@ export declare const deleteNestedObjectsWithHtMeta: (currentLocusPart: any, pare
 export declare function sortByInitPriority<T extends {
     name: string;
 }>(items: T[], priority: string[]): T[];
+/**
+ * Sleeps for the specified amount of milliseconds
+ *
+ * @param {number} ms amount of milliseconds to sleep
+ * @returns {Promise<void>} A promise that resolves after the specified delay
+ */
+export declare function sleep(ms: number): Promise<void>;

package/dist/types/locus-info/index.d.ts

@@ -215,9 +215,13 @@ export default class LocusInfo extends EventsScope {
      * Triggers a sync of all hash tree datasets for all hash tree parsers associated with this meeting.
      * The syncs are executed sequentially within each parser.
      *
+     * @param {Object} [options={}] - Options for syncing
+     * @param {boolean} [options.onlyLLM=false] - Whether to sync only LLM based data sets
      * @returns {Promise<void>}
      */
-    syncAllHashTreeDatasets(): Promise<void>;
+    syncAllHashTreeDatasets(options?: {
+        onlyLLM?: boolean;
+    }): Promise<void>;
     /**
      * Callback registered with HashTreeParser to receive locus info updates.
      * Updates our locus info based on the data parsed by the hash tree parser.

package/dist/webinar/index.js

@@ -774,7 +774,7 @@ var Webinar = _webexCore.WebexPlugin.extend({
       }, _callee1);
     }))();
   },
-  version: "3.12.0-next.60"
+  version: "3.12.0-next.62"
 });
 var _default = exports.default = Webinar;
 //# sourceMappingURL=index.js.map

package/package.json

@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@webex/common": "3.12.0-next.1",
-    "@webex/internal-media-core": "2.24.1",
+    "@webex/internal-media-core": "2.25.1",
     "@webex/internal-plugin-conversation": "3.12.0-next.17",
     "@webex/internal-plugin-device": "3.12.0-next.15",
     "@webex/internal-plugin-llm": "3.12.0-next.18",
@@ -71,7 +71,7 @@
     "@webex/internal-plugin-support": "3.12.0-next.17",
     "@webex/internal-plugin-user": "3.12.0-next.16",
     "@webex/internal-plugin-voicea": "3.12.0-next.18",
-    "@webex/media-helpers": "3.12.0-next.3",
+    "@webex/media-helpers": "3.12.0-next.4",
     "@webex/plugin-people": "3.12.0-next.16",
     "@webex/plugin-rooms": "3.12.0-next.17",
     "@webex/ts-sdp": "^1.8.1",
@@ -94,5 +94,5 @@
   "//": [
     "TODO: upgrade jwt-decode when moving to node 18"
   ],
-  "version": "3.12.0-next.60"
+  "version": "3.12.0-next.62"
 }

package/src/hashTree/constants.ts

@@ -17,3 +17,10 @@ export const DataSetNames = {
 // participant object for webinar attendees. If SELF were initialized first, locus.info
 // would not yet be populated and the attendee participant would be skipped.
 export const DATA_SET_INIT_PRIORITY: string[] = [DataSetNames.MAIN, DataSetNames.SELF];
+
+// Data sets for which we normally receive events over LLM connection
+export const LLM_DATASET_NAMES = [
+  DataSetNames.MAIN,
+  DataSetNames.ATD_ACTIVE,
+  DataSetNames.ATD_UNMUTED,
+];

package/src/hashTree/hashTreeParser.ts

@@ -4,10 +4,16 @@ import LoggerProxy from '../common/logs/logger-proxy';
 import Metrics from '../metrics';
 import BEHAVIORAL_METRICS from '../metrics/constants';
 import {Enum, HTTP_VERBS} from '../constants';
-import {DataSetNames, DATA_SET_INIT_PRIORITY, EMPTY_HASH} from './constants';
+import {DataSetNames, DATA_SET_INIT_PRIORITY, EMPTY_HASH, LLM_DATASET_NAMES} from './constants';
 import {ObjectType, HtMeta, HashTreeObject} from './types';
 import {LocusDTO, LocusErrorCodes} from '../locus-info/types';
-import {deleteNestedObjectsWithHtMeta, isMetadata, sortByInitPriority} from './utils';
+import {deleteNestedObjectsWithHtMeta, isMetadata, sleep, sortByInitPriority} from './utils';
+
+export enum SyncAllBackoffType {
+  NONE = 'none',
+  ONLY_LLM = 'onlyLLM',
+  ALL = 'all',
+}
 
 export interface DataSet {
   url: string;
@@ -122,7 +128,10 @@ class HashTreeParser {
   state: 'active' | 'stopped';
   private syncQueue: Array<{dataSetName: string; reason: string; isInitialization?: boolean}> = [];
   private isSyncInProgress = false;
-  private isSyncAllInProgress = false;
+  // tracks whether syncAllDatasets is currently in its backoff delay phase and with what scope
+  private syncAllBackoffType: SyncAllBackoffType = SyncAllBackoffType.NONE;
+  // datasets that received messages during the syncAllDatasets backoff sleep and should be skipped
+  private dataSetsSyncedDuringBackoff: Set<string> = new Set();
   private syncQueueProcessingPromise: Promise<void> = Promise.resolve();
 
   /**
@@ -1342,8 +1351,14 @@ class HashTreeParser {
         // parseMessage() -> cancelPendingSyncsForDataSets() doesn't log a
         // misleading "aborting sync" message for this already-completed sync
         dataSet.syncAbortController = undefined;
+
         // the format of sync response is the same as messages, so we can reuse the same handler
-        this.handleMessage(syncResponse, 'via sync API');
+        this.handleMessage(
+          syncResponse,
+          `via sync API (${
+            isInitialization ? 'init' : `${Object.keys(leavesData).length} mismatched leaves`
+          })`
+        );
       }
     } catch (error) {
       if (!this.handleSyncErrors(error)) {
@@ -1377,6 +1392,32 @@ class HashTreeParser {
       );
     }
 
+    this.markDataSetsForSyncAllBackoffSkip(dataSetNames);
+    this.abortInFlightSyncs(dataSetNames);
+  }
+
+  /**
+   * If a syncAllDatasets backoff sleep is in progress, marks the given data sets to be skipped
+   * after the sleep completes.
+   *
+   * @param {string[]} dataSetNames - The names of the data sets to mark
+   * @returns {void}
+   */
+  private markDataSetsForSyncAllBackoffSkip(dataSetNames: string[]): void {
+    if (this.syncAllBackoffType !== SyncAllBackoffType.NONE) {
+      for (const name of dataSetNames) {
+        this.dataSetsSyncedDuringBackoff.add(name);
+      }
+    }
+  }
+
+  /**
+   * Aborts any in-flight sync HTTP requests for the specified data sets.
+   *
+   * @param {string[]} dataSetNames - The names of the data sets whose syncs should be aborted
+   * @returns {void}
+   */
+  private abortInFlightSyncs(dataSetNames: string[]): void {
     for (const name of dataSetNames) {
       if (this.dataSets[name]?.syncAbortController) {
         LoggerProxy.logger.info(
@@ -1451,39 +1492,129 @@ class HashTreeParser {
     }
   }
 
+  /**
+   * sets the backoff type for syncAllDatasets calls, which determines the scope of datasets that will be synced after the backoff delay.
+   *
+   * @param {boolean} onlyLLM - Whether the backoff is for a syncAllDatasets call that is syncing only LLM datasets
+   * @returns {void}
+   */
+  private setSyncAllBackoffType(onlyLLM: boolean): void {
+    this.syncAllBackoffType = onlyLLM ? SyncAllBackoffType.ONLY_LLM : SyncAllBackoffType.ALL;
+  }
+
+  /**
+   * Checks if a syncAll backoff is already in progress. If so, upgrades the scope from
+   * onlyLLM to all datasets when the new call has a broader scope.
+   *
+   * @param {boolean} onlyLLM - Whether the current call is for LLM datasets only
+   * @returns {boolean} true if a backoff is already pending (caller should return early)
+   */
+  private tryUpgradePendingBackoff(onlyLLM: boolean): boolean {
+    if (this.syncAllBackoffType !== SyncAllBackoffType.NONE) {
+      if (!onlyLLM && this.syncAllBackoffType === SyncAllBackoffType.ONLY_LLM) {
+        this.setSyncAllBackoffType(false);
+        LoggerProxy.logger.info(
+          `HashTreeParser#syncAllDatasets --> ${this.debugId} upgraded pending syncAll from onlyLLM to all datasets`
+        );
+      }
+
+      return true;
+    }
+
+    return false;
+  }
+
   /**
    * Syncs all data sets that have hash trees, one by one in sequence, using the priority order
-   * provided by sortByInitPriority(). Does nothing if the parser is stopped or if a syncAllDatasets
-   * call is already in progress.
+   * provided by sortByInitPriority().
    *
+   * If a call is already waiting in the backoff delay phase, a new call with a broader scope
+   * (onlyLLM=false) will upgrade the pending scope, and the dataset list will be computed after
+   * the backoff using the upgraded scope. After the backoff, the sync queue handles deduplication
+   * so no guard is needed.
+   *
+   * @param {Object} [options={}] - Options for syncing
+   * @param {boolean} [options.onlyLLM=false] - Whether to sync only LLM based data sets
    * @returns {Promise<void>}
    */
-  public async syncAllDatasets(): Promise<void> {
+  public async syncAllDatasets(options: {onlyLLM?: boolean} = {}): Promise<void> {
+    const {onlyLLM = false} = options;
     if (this.state === 'stopped') return;
-    if (this.isSyncAllInProgress) return;
 
-    this.isSyncAllInProgress = true;
-    try {
-      const dataSetsWithHashTrees = Object.values(this.dataSets)
-        .filter((dataSet) => dataSet?.hashTree)
-        .map((dataSet) => ({name: dataSet.name}));
+    // if we're already in the backoff delay phase, try to upgrade the scope instead of starting a new one
+    if (this.tryUpgradePendingBackoff(onlyLLM)) {
+      return;
+    }
+
+    const dataSetsToSync = this.getSortedDataSetsWithHashTrees(onlyLLM);
+
+    if (dataSetsToSync.length === 0) return;
+
+    this.setSyncAllBackoffType(onlyLLM);
+
+    const delay = this.getWeightedBackoffTime(dataSetsToSync[0].backoff);
+
+    LoggerProxy.logger.info(
+      `HashTreeParser#syncAllDatasets --> ${this.debugId} starting backoff delay of ${delay}ms (onlyLLM=${onlyLLM})`
+    );
+
+    // delay the start of the syncs - this is a Locus requirement to avoid thundering herd issues
+    await sleep(delay);
+
+    // read the (possibly upgraded) scope and clear the backoff flag
+    const effectiveBackoffType = this.syncAllBackoffType;
+    const skippedDataSets = this.dataSetsSyncedDuringBackoff;
+
+    this.syncAllBackoffType = SyncAllBackoffType.NONE;
+    this.dataSetsSyncedDuringBackoff = new Set();
 
-      const sorted = sortByInitPriority(dataSetsWithHashTrees, DATA_SET_INIT_PRIORITY);
+    if ((this.state as string) === 'stopped') return;
 
+    // re-evaluate the dataset list after the sleep, since the scope may have been upgraded
+    // and exclude datasets that received messages during the backoff sleep
+    const effectiveDataSetsToSync = this.getSortedDataSetsWithHashTrees(
+      effectiveBackoffType === SyncAllBackoffType.ONLY_LLM
+    ).filter((ds) => !skippedDataSets.has(ds.name));
+
+    if (skippedDataSets.size > 0) {
       LoggerProxy.logger.info(
-        `HashTreeParser#syncAllDatasets --> ${this.debugId} syncing datasets: ${sorted
-          .map((ds) => ds.name)
-          .join(', ')}`
+        `HashTreeParser#syncAllDatasets --> ${
+          this.debugId
+        } skipping datasets that received messages during backoff: ${[...skippedDataSets].join(
+          ', '
+        )}`
       );
+    }
 
-      for (const ds of sorted) {
-        this.enqueueSyncForDataset(ds.name, 'syncAllDatasets');
-      }
+    LoggerProxy.logger.info(
+      `HashTreeParser#syncAllDatasets --> ${this.debugId} syncing ${
+        effectiveBackoffType === SyncAllBackoffType.ONLY_LLM ? 'only LLM' : 'all'
+      } datasets: ${effectiveDataSetsToSync.map((ds) => ds.name).join(', ')}`
+    );
 
-      await this.syncQueueProcessingPromise;
-    } finally {
-      this.isSyncAllInProgress = false;
+    for (const ds of effectiveDataSetsToSync) {
+      this.enqueueSyncForDataset(ds.name, 'syncAllDatasets');
+    }
+
+    await this.syncQueueProcessingPromise;
+  }
+
+  /**
+   * Returns the list of data sets that have hash trees, sorted by the priority order provided by sortByInitPriority().
+   *
+   * @param {boolean} onlyLLM - Whether to include only LLM based data sets
+   * @returns {Array<{name: string, backoff: {maxMs: number, exponent: number}}>} The sorted list of data sets with their backoff configurations
+   */
+  private getSortedDataSetsWithHashTrees(onlyLLM: boolean) {
+    let dataSets = Object.values(this.dataSets)
+      .filter((dataSet) => dataSet?.hashTree)
+      .map((dataSet) => ({name: dataSet.name, backoff: dataSet.backoff}));
+
+    if (onlyLLM) {
+      dataSets = dataSets.filter((ds) => LLM_DATASET_NAMES.includes(ds.name));
     }
+
+    return sortByInitPriority(dataSets, DATA_SET_INIT_PRIORITY);
   }
 
   /**
@@ -1623,6 +1754,8 @@ class HashTreeParser {
     );
     this.stopAllTimers();
     this.syncQueue = [];
+    this.syncAllBackoffType = SyncAllBackoffType.NONE;
+    this.dataSetsSyncedDuringBackoff = new Set();
     Object.values(this.dataSets).forEach((dataSet) => {
       dataSet.syncAbortController?.abort();
       dataSet.syncAbortController = undefined;

package/src/hashTree/utils.ts

@@ -77,3 +77,22 @@ export function sortByInitPriority<T extends {name: string}>(items: T[], priorit
 
   return [...prioritized, ...rest];
 }
+
+/**
+ * Sleeps for the specified amount of milliseconds
+ *
+ * @param {number} ms amount of milliseconds to sleep
+ * @returns {Promise<void>} A promise that resolves after the specified delay
+ */
+export function sleep(ms: number): Promise<void> {
+  if (ms <= 0) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    // start a timer that will resolve the promise after the specified delay
+    setTimeout(() => {
+      resolve();
+    }, ms);
+  });
+}

package/src/locus-info/index.ts

@@ -1203,13 +1203,15 @@ export default class LocusInfo extends EventsScope {
    * Triggers a sync of all hash tree datasets for all hash tree parsers associated with this meeting.
    * The syncs are executed sequentially within each parser.
    *
+   * @param {Object} [options={}] - Options for syncing
+   * @param {boolean} [options.onlyLLM=false] - Whether to sync only LLM based data sets
    * @returns {Promise<void>}
    */
-  async syncAllHashTreeDatasets(): Promise<void> {
+  async syncAllHashTreeDatasets(options: {onlyLLM?: boolean} = {}): Promise<void> {
     for (const [, entry] of this.hashTreeParsers) {
       if (entry.parser) {
         // eslint-disable-next-line no-await-in-loop
-        await entry.parser.syncAllDatasets();
+        await entry.parser.syncAllDatasets(options);
       }
     }
   }

package/src/meeting/index.ts

@@ -6135,6 +6135,7 @@ export default class Meeting extends StatelessWebexPlugin {
    */
   private handleLLMOnline = (): void => {
     this.restoreLLMSubscriptionsIfNeeded();
+    this.locusInfo.syncAllHashTreeDatasets({onlyLLM: true});
 
     Trigger.trigger(
       this,
@@ -6687,6 +6688,7 @@ export default class Meeting extends StatelessWebexPlugin {
     return this.webex.internal.llm
       .registerAndConnect(url, dataChannelUrl, datachannelToken)
       .then((registerAndConnectResult) => {
+        this.locusInfo.syncAllHashTreeDatasets({onlyLLM: true});
         // Record ownership of the default LLM session for this meeting so
         // subsequent cross-meeting `updateLLMConnection` / `cleanupLLMConneciton`
         // calls can detect and skip work that doesn't belong to them.