@webex/plugin-meetings 3.0.0-beta.186 → 3.0.0-beta.187

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

@@ -1,15 +1,25 @@
-import SimpleQueue from '../common/queue';
+/// <reference types="node" />
+import SortedQueue from '../common/queue';
+type LocusDeltaDto = {
+    baseSequence: {
+        rangeStart: number;
+        rangeEnd: number;
+        entries: number[];
+    };
+    sequence: {
+        rangeStart: number;
+        rangeEnd: number;
+        entries: number[];
+    };
+    syncUrl: string;
+};
 /**
  * Locus Delta Parser
  * @private
  * https://sqbu-github.cisco.com/WebExSquared/cloud-apps/wiki/Locus-Delta-Events
  */
 export default class Parser {
-    static status: {
-        IDLE: string;
-        PAUSED: string;
-        WORKING: string;
-    };
+    status: 'IDLE' | 'PAUSED' | 'WORKING' | 'BLOCKED';
     static loci: {
         EQ: string;
         GT: string;
@@ -17,14 +27,23 @@ export default class Parser {
         DESYNC: string;
         USE_INCOMING: string;
         USE_CURRENT: string;
+        WAIT: string;
         ERROR: string;
     };
-    queue: SimpleQueue;
+    queue: SortedQueue<LocusDeltaDto>;
     workingCopy: any;
+    syncTimer: null | number | NodeJS.Timeout;
     /**
      * @constructs Parser
      */
     constructor();
+    /**
+     * Returns a debug string representing a locus delta - useful for logging
+     *
+     * @param {LocusDeltaDto} locus Locus delta
+     * @returns {string}
+     */
+    static locus2string(locus: LocusDeltaDto): string;
     /**
      * Checks if two sequences overlap in time,
      * the sequence with the higher minimum value is greater.
@@ -206,6 +225,29 @@ export default class Parser {
      * @returns {undefined}
      */
     pause(): void;
+    /**
+     * Triggers a sync with Locus
+     *
+     * @param {string} reason used just for logging
+     * @returns {undefined}
+     */
+    private triggerSync;
+    /**
+     * Starts a timer with a random delay. When that timer expires we will do a sync.
+     *
+     * The main purpose of this timer is to handle a case when we get some out-of-order deltas,
+     * so we start waiting to receive the missing delta. If that delta never arrives, this timer
+     * will trigger a sync with Locus.
+     *
+     * @returns {undefined}
+     */
+    private startSyncTimer;
+    /**
+     * Stops the timer for triggering a sync
+     *
+     * @returns {undefined}
+     */
+    private stopSyncTimer;
     /**
      * Processes next locus delta in the queue,
      * continues until the queue is empty
@@ -226,3 +268,4 @@ export default class Parser {
      */
     static getDebugMessage(debugCode: string, comparison: string): any;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webex/plugin-meetings",
-  "version": "3.0.0-beta.186",
+  "version": "3.0.0-beta.187",
   "description": "",
   "license": "Cisco EULA (https://www.cisco.com/c/en/us/products/end-user-license-agreement.html)",
   "contributors": [
@@ -32,12 +32,12 @@
     "build": "yarn run -T tsc --declaration true --declarationDir ./dist/types"
   },
   "devDependencies": {
-    "@webex/plugin-meetings": "3.0.0-beta.186",
-    "@webex/test-helper-chai": "3.0.0-beta.186",
-    "@webex/test-helper-mocha": "3.0.0-beta.186",
-    "@webex/test-helper-mock-webex": "3.0.0-beta.186",
-    "@webex/test-helper-retry": "3.0.0-beta.186",
-    "@webex/test-helper-test-users": "3.0.0-beta.186",
+    "@webex/plugin-meetings": "3.0.0-beta.187",
+    "@webex/test-helper-chai": "3.0.0-beta.187",
+    "@webex/test-helper-mocha": "3.0.0-beta.187",
+    "@webex/test-helper-mock-webex": "3.0.0-beta.187",
+    "@webex/test-helper-retry": "3.0.0-beta.187",
+    "@webex/test-helper-test-users": "3.0.0-beta.187",
     "chai": "^4.3.4",
     "chai-as-promised": "^7.1.1",
     "jsdom-global": "3.0.2",
@@ -46,19 +46,19 @@
     "typescript": "^4.7.4"
   },
   "dependencies": {
-    "@webex/common": "3.0.0-beta.186",
+    "@webex/common": "3.0.0-beta.187",
     "@webex/internal-media-core": "1.39.1",
-    "@webex/internal-plugin-conversation": "3.0.0-beta.186",
-    "@webex/internal-plugin-device": "3.0.0-beta.186",
-    "@webex/internal-plugin-llm": "3.0.0-beta.186",
-    "@webex/internal-plugin-mercury": "3.0.0-beta.186",
-    "@webex/internal-plugin-metrics": "3.0.0-beta.186",
-    "@webex/internal-plugin-support": "3.0.0-beta.186",
-    "@webex/internal-plugin-user": "3.0.0-beta.186",
-    "@webex/media-helpers": "3.0.0-beta.186",
-    "@webex/plugin-people": "3.0.0-beta.186",
-    "@webex/plugin-rooms": "3.0.0-beta.186",
-    "@webex/webex-core": "3.0.0-beta.186",
+    "@webex/internal-plugin-conversation": "3.0.0-beta.187",
+    "@webex/internal-plugin-device": "3.0.0-beta.187",
+    "@webex/internal-plugin-llm": "3.0.0-beta.187",
+    "@webex/internal-plugin-mercury": "3.0.0-beta.187",
+    "@webex/internal-plugin-metrics": "3.0.0-beta.187",
+    "@webex/internal-plugin-support": "3.0.0-beta.187",
+    "@webex/internal-plugin-user": "3.0.0-beta.187",
+    "@webex/media-helpers": "3.0.0-beta.187",
+    "@webex/plugin-people": "3.0.0-beta.187",
+    "@webex/plugin-rooms": "3.0.0-beta.187",
+    "@webex/webex-core": "3.0.0-beta.187",
     "ampersand-collection": "^2.0.2",
     "bowser": "^2.11.0",
     "btoa": "^1.2.1",

package/src/common/queue.ts

@@ -1,13 +1,18 @@
 /**
- * Simple queue
+ * Simple queue in which the elements are always sorted
  */
-export default class SimpleQueue {
-  queue: any[];
+export default class SortedQueue<ItemType> {
+  queue: ItemType[];
+  // returns -1 if left < right, 0 if left === right, +1 if left > right
+  compareFunc: (left: ItemType, right: ItemType) => number;
+
   /**
-   * @constructs SimpleQueue
+   * @constructs SortedQueue
+   * @param {Function} compareFunc comparison function used for sorting the elements of the queue
    */
-  constructor() {
+  constructor(compareFunc: (left: ItemType, right: ItemType) => number) {
     this.queue = [];
+    this.compareFunc = compareFunc;
   }
 
   /**
@@ -23,8 +28,17 @@ export default class SimpleQueue {
    * @param {object} item
    * @returns {undefined}
    */
-  enqueue(item: object) {
-    this.queue.push(item);
+  enqueue(item: ItemType) {
+    // Find the index of the first item in the queue that's greater or equal to the new item.
+    // That's where we want to insert the new item.
+    const idx = this.queue.findIndex((existingItem) => {
+      return this.compareFunc(existingItem, item) >= 0;
+    });
+    if (idx >= 0) {
+      this.queue.splice(idx, 0, item);
+    } else {
+      this.queue.push(item);
+    }
   }
 
   /**
@@ -32,7 +46,7 @@ export default class SimpleQueue {
    * Returns null if the queue is empty.
    * @returns {(object|null)} Queue item or null.
    */
-  dequeue() {
+  dequeue(): ItemType {
     if (this.queue.length === 0) {
       return null;
     }

package/src/locus-info/index.ts

@@ -108,23 +108,26 @@ export default class LocusInfo extends EventsScope {
     );
 
     // return value ignored on purpose
-    meeting.meetingRequest.getLocusDTO({url}).then((res) => {
-      if (isDelta) {
-        if (!isEmpty(res.body)) {
-          meeting.locusInfo.onDeltaLocus(res.body);
+    meeting.meetingRequest
+      .getLocusDTO({url})
+      .then((res) => {
+        if (isDelta) {
+          if (!isEmpty(res.body)) {
+            meeting.locusInfo.handleLocusDelta(res.body, meeting);
+          } else {
+            LoggerProxy.logger.info(
+              'Locus-info:index#doLocusSync --> received empty body from syncUrl, so we already have latest Locus DTO'
+            );
+          }
         } else {
-          LoggerProxy.logger.info(
-            'Locus-info:index#doLocusSync --> received empty body from syncUrl, so we already have latest Locus DTO'
-          );
+          meeting.locusInfo.onFullLocus(res.body);
         }
-      } else {
-        meeting.locusInfo.onFullLocus(res.body);
-      }
-
-      // Notify parser to resume processing delta events.
-      // Any deltas in the queue that have now been superseded by this sync will simply be ignored
-      this.locusParser.resume();
-    });
+      })
+      .finally(() => {
+        // Notify parser to resume processing delta events.
+        // Any deltas in the queue that have now been superseded by this sync will simply be ignored
+        this.locusParser.resume();
+      });
   }
 
   /**
@@ -135,13 +138,14 @@ export default class LocusInfo extends EventsScope {
    * @returns {undefined}
    */
   applyLocusDeltaData(action: string, locus: any, meeting: any) {
-    const {DESYNC, USE_CURRENT, USE_INCOMING} = LocusDeltaParser.loci;
+    const {DESYNC, USE_CURRENT, USE_INCOMING, WAIT} = LocusDeltaParser.loci;
 
     switch (action) {
       case USE_INCOMING:
         meeting.locusInfo.onDeltaLocus(locus);
         break;
       case USE_CURRENT:
+      case WAIT:
         // do nothing
         break;
       case DESYNC:
@@ -314,6 +318,7 @@ export default class LocusInfo extends EventsScope {
 
       return;
     }
+
     this.updateParticipantDeltas(locus.participants);
     this.scheduledMeeting = locus.meeting || null;
     this.participants = locus.participants;

package/src/locus-info/parser.ts

@@ -1,8 +1,26 @@
 import {difference} from 'lodash';
 
-import SimpleQueue from '../common/queue';
+import SortedQueue from '../common/queue';
 import LoggerProxy from '../common/logs/logger-proxy';
 
+const MAX_OOO_DELTA_COUNT = 5; // when we receive an out-of-order delta and the queue builds up to MAX_OOO_DELTA_COUNT, we do a sync with Locus
+const OOO_DELTA_WAIT_TIME = 10000; // [ms] minimum wait time before we do a sync if we get out-of-order deltas
+const OOO_DELTA_WAIT_TIME_RANDOM_DELAY = 5000; // [ms] max random delay added to OOO_DELTA_WAIT_TIME
+
+type LocusDeltaDto = {
+  baseSequence: {
+    rangeStart: number;
+    rangeEnd: number;
+    entries: number[];
+  };
+  sequence: {
+    rangeStart: number;
+    rangeEnd: number;
+    entries: number[];
+  };
+  syncUrl: string;
+};
+
 /**
  * Locus Delta Parser
  * @private
@@ -10,11 +28,11 @@ import LoggerProxy from '../common/logs/logger-proxy';
  */
 export default class Parser {
   // processing status
-  static status = {
-    IDLE: 'IDLE',
-    PAUSED: 'PAUSED',
-    WORKING: 'WORKING',
-  };
+  status:
+    | 'IDLE' // not doing anything
+    | 'PAUSED' // paused, because we are doing a sync
+    | 'WORKING' // processing a delta event
+    | 'BLOCKED'; // received an out-of-order delta, so waiting for the missing one
 
   // loci comparison states
   static loci = {
@@ -24,21 +42,59 @@ export default class Parser {
     DESYNC: 'DESYNC',
     USE_INCOMING: 'USE_INCOMING',
     USE_CURRENT: 'USE_CURRENT',
+    WAIT: 'WAIT',
     ERROR: 'ERROR',
   };
 
-  queue: SimpleQueue;
+  queue: SortedQueue<LocusDeltaDto>;
   workingCopy: any;
+  syncTimer: null | number | NodeJS.Timeout;
 
   /**
    * @constructs Parser
    */
   constructor() {
-    this.queue = new SimpleQueue();
-    // @ts-ignore - This is declared as static class member and again being initialized here from same
-    this.status = Parser.status.IDLE;
+    const deltaCompareFunc = (left: LocusDeltaDto, right: LocusDeltaDto) => {
+      const {LT, GT} = Parser.loci;
+      const {extractComparisonState: extract} = Parser;
+
+      if (Parser.isSequenceEmpty(left)) {
+        return -1;
+      }
+      if (Parser.isSequenceEmpty(right)) {
+        return 1;
+      }
+      const result = extract(Parser.compareSequence(left.baseSequence, right.baseSequence));
+
+      if (result === LT) {
+        return -1;
+      }
+      if (result === GT) {
+        return 1;
+      }
+
+      return 0;
+    };
+
+    this.queue = new SortedQueue<LocusDeltaDto>(deltaCompareFunc);
+    this.status = 'IDLE';
     this.onDeltaAction = null;
     this.workingCopy = null;
+    this.syncTimer = null;
+  }
+
+  /**
+   * Returns a debug string representing a locus delta - useful for logging
+   *
+   * @param {LocusDeltaDto} locus Locus delta
+   * @returns {string}
+   */
+  static locus2string(locus: LocusDeltaDto) {
+    if (!locus.sequence?.entries) {
+      return 'invalid';
+    }
+
+    return locus.sequence.entries.length ? `seq=${locus.sequence.entries.at(-1)}` : 'empty';
   }
 
   /**
@@ -208,7 +264,7 @@ export default class Parser {
    * @returns {string} loci comparison state
    */
   private static compareDelta(current, incoming) {
-    const {LT, GT, EQ, DESYNC, USE_INCOMING} = Parser.loci;
+    const {LT, GT, EQ, DESYNC, USE_INCOMING, WAIT} = Parser.loci;
 
     const {extractComparisonState: extract} = Parser;
     const {packComparisonResult: pack} = Parser;
@@ -228,6 +284,17 @@ export default class Parser {
         comparison = USE_INCOMING;
         break;
 
+      case LT:
+        if (extract(Parser.compareSequence(incoming.baseSequence, incoming.sequence)) === EQ) {
+          // special case where Locus sends a delta with baseSequence === sequence to trigger a sync,
+          // because the delta event is too large to be sent over mercury connection
+          comparison = DESYNC;
+        } else {
+          // the incoming locus has baseSequence from the future, so it is out-of-order,
+          // we are missing 1 or more locus that should be in front of it, we need to wait for it
+          comparison = WAIT;
+        }
+        break;
       default:
         comparison = DESYNC;
     }
@@ -436,17 +503,10 @@ export default class Parser {
    */
   isValidLocus(newLoci) {
     let isValid = false;
-    const {IDLE} = Parser.status;
     const {isLoci} = Parser;
-    // @ts-ignore
-    const setStatus = (status) => {
-      // @ts-ignore
-      this.status = status;
-    };
 
     // one or both objects are not locus delta events
     if (!isLoci(this.workingCopy) || !isLoci(newLoci)) {
-      setStatus(IDLE);
       LoggerProxy.logger.info(
         'Locus-info:parser#processDeltaEvent --> Ignoring non-locus object. workingCopy:',
         this.workingCopy,
@@ -498,19 +558,25 @@ export default class Parser {
    * @returns {undefined}
    */
   nextEvent() {
-    // @ts-ignore
-    if (this.status === Parser.status.PAUSED) {
+    if (this.status === 'PAUSED') {
       LoggerProxy.logger.info('Locus-info:parser#nextEvent --> Locus parser paused.');
 
       return;
     }
 
+    if (this.status === 'BLOCKED') {
+      LoggerProxy.logger.info(
+        'Locus-info:parser#nextEvent --> Locus parser blocked by out-of-order delta.'
+      );
+
+      return;
+    }
+
     // continue processing until queue is empty
     if (this.queue.size() > 0) {
       this.processDeltaEvent();
     } else {
-      // @ts-ignore
-      this.status = Parser.status.IDLE;
+      this.status = 'IDLE';
     }
   }
 
@@ -532,15 +598,20 @@ export default class Parser {
   onDeltaEvent(loci) {
     // enqueue the new loci
     this.queue.enqueue(loci);
-    // start processing events in the queue if idle
-    // and a function handler is defined
-    // @ts-ignore
-    if (this.status === Parser.status.IDLE && this.onDeltaAction) {
-      // Update status, ensure we only process one event at a time.
-      // @ts-ignore
-      this.status = Parser.status.WORKING;
 
-      this.processDeltaEvent();
+    if (this.onDeltaAction) {
+      if (this.status === 'BLOCKED') {
+        if (this.queue.size() > MAX_OOO_DELTA_COUNT) {
+          this.triggerSync('queue too big, blocked on out-of-order delta');
+        } else {
+          this.processDeltaEvent();
+        }
+      } else if (this.status === 'IDLE') {
+        // Update status, ensure we only process one event at a time.
+        this.status = 'WORKING';
+
+        this.processDeltaEvent();
+      }
     }
   }
 
@@ -559,11 +630,55 @@ export default class Parser {
    * @returns {undefined}
    */
   pause() {
-    // @ts-ignore
-    this.status = Parser.status.PAUSED;
+    this.status = 'PAUSED';
     LoggerProxy.logger.info('Locus-info:parser#pause --> Locus parser paused.');
   }
 
+  /**
+   * Triggers a sync with Locus
+   *
+   * @param {string} reason used just for logging
+   * @returns {undefined}
+   */
+  private triggerSync(reason: string) {
+    LoggerProxy.logger.info(`Locus-info:parser#triggerSync --> doing sync, reason: ${reason}`);
+    this.stopSyncTimer();
+    this.pause();
+    this.onDeltaAction(Parser.loci.DESYNC, this.workingCopy);
+  }
+
+  /**
+   * Starts a timer with a random delay. When that timer expires we will do a sync.
+   *
+   * The main purpose of this timer is to handle a case when we get some out-of-order deltas,
+   * so we start waiting to receive the missing delta. If that delta never arrives, this timer
+   * will trigger a sync with Locus.
+   *
+   * @returns {undefined}
+   */
+  private startSyncTimer() {
+    if (this.syncTimer === null) {
+      const timeout = OOO_DELTA_WAIT_TIME + Math.random() * OOO_DELTA_WAIT_TIME_RANDOM_DELAY;
+
+      this.syncTimer = setTimeout(() => {
+        this.syncTimer = null;
+        this.triggerSync('timer expired, blocked on out-of-order delta');
+      }, timeout);
+    }
+  }
+
+  /**
+   * Stops the timer for triggering a sync
+   *
+   * @returns {undefined}
+   */
+  private stopSyncTimer() {
+    if (this.syncTimer !== null) {
+      clearTimeout(this.syncTimer);
+      this.syncTimer = null;
+    }
+  }
+
   /**
    * Processes next locus delta in the queue,
    * continues until the queue is empty
@@ -571,11 +686,13 @@ export default class Parser {
    * @returns {undefined}
    */
   processDeltaEvent() {
-    const {DESYNC, USE_INCOMING} = Parser.loci;
+    const {DESYNC, USE_INCOMING, WAIT} = Parser.loci;
     const {extractComparisonState: extract} = Parser;
     const newLoci = this.queue.dequeue();
 
     if (!this.isValidLocus(newLoci)) {
+      this.nextEvent();
+
       return;
     }
 
@@ -586,6 +703,8 @@ export default class Parser {
     // for full debugging.
     LoggerProxy.logger.debug(`Locus-info:parser#processDeltaEvent --> Locus Debug: ${result}`);
 
+    let needToWait = false;
+
     if (lociComparison === DESYNC) {
       // wait for desync response
       this.pause();
@@ -594,15 +713,39 @@ export default class Parser {
       // Note: The working copy of parser gets updated in .onFullLocus()
       // and here when USE_INCOMING locus.
       this.workingCopy = newLoci;
+    } else if (lociComparison === WAIT) {
+      // we've taken newLoci from the front of the queue, so put it back there as we have to wait
+      // for the one that should be in front of it, before we can process it
+      this.queue.enqueue(newLoci);
+      needToWait = true;
+    }
+
+    if (needToWait) {
+      this.status = 'BLOCKED';
+      this.startSyncTimer();
+    } else {
+      this.stopSyncTimer();
+
+      if (this.status === 'BLOCKED') {
+        // we are not blocked anymore
+        this.status = 'WORKING';
+
+        LoggerProxy.logger.info(
+          `Locus-info:parser#processDeltaEvent --> received delta that we were waiting for ${Parser.locus2string(
+            newLoci
+          )}, not blocked anymore`
+        );
+      }
     }
 
     if (this.onDeltaAction) {
       LoggerProxy.logger.info(
-        `Locus-info:parser#processDeltaEvent --> Locus Delta Action: ${lociComparison}`
+        `Locus-info:parser#processDeltaEvent --> Locus Delta ${Parser.locus2string(
+          newLoci
+        )}, Action: ${lociComparison}`
       );
 
-      // eslint-disable-next-line no-useless-call
-      this.onDeltaAction.call(this, lociComparison, newLoci);
+      this.onDeltaAction(lociComparison, newLoci);
     }
 
     this.nextEvent();
@@ -614,8 +757,7 @@ export default class Parser {
    */
   resume() {
     LoggerProxy.logger.info('Locus-info:parser#resume --> Locus parser resumed.');
-    // @ts-ignore
-    this.status = Parser.status.WORKING;
+    this.status = 'WORKING';
     this.nextEvent();
   }
 

package/test/unit/spec/common/queue.js

@@ -1,5 +1,5 @@
 import {assert} from '@webex/test-helper-chai';
-import SimpleQueue from '@webex/plugin-meetings/src/common/queue';
+import SortedQueue from '@webex/plugin-meetings/src/common/queue';
 
 describe('common/queue', () => {
   let fifo = null;
@@ -11,7 +11,15 @@ describe('common/queue', () => {
   };
 
   beforeEach(() => {
-    fifo = new SimpleQueue();
+    fifo = new SortedQueue((left, right) => {
+      if (left.text > right.text) {
+        return 1;
+      }
+      if (left.text < right.text) {
+        return -1;
+      }
+      return 0;
+    });
   });
 
   afterEach(() => {
@@ -66,4 +74,25 @@ describe('common/queue', () => {
   it('Returns null if the queue is empty.', () => {
     assert.equal(fifo.dequeue(), null);
   });
+
+  it('Implement lifo', () => {
+    const lifo = new SortedQueue((left, right) => {
+      if (left.text < right.text) {
+        return 1;
+      }
+      if (left.text > right.text) {
+        return -1;
+      }
+      return 0;
+    });
+
+    const item1 = {text: 'fake item1'};
+    const item2 = {text: 'fake item2'};
+
+    lifo.enqueue(item1);
+    lifo.enqueue(item2);
+
+    assert.equal(lifo.dequeue(), item2);
+    assert.equal(lifo.dequeue(), item1);
+  });
 });