@webex/internal-plugin-dss 3.0.0-beta.4 → 3.0.0-beta.400

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webex/internal-plugin-dss",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.400",
   "description": "",
   "license": "MIT",
   "author": "Colin Read <coread@cisco.com>",
@@ -21,14 +21,17 @@
     ]
   },
   "dependencies": {
-    "@webex/internal-plugin-mercury": "3.0.0-beta.4",
-    "@webex/webex-core": "3.0.0-beta.4",
+    "@webex/common": "3.0.0-beta.400",
+    "@webex/common-timers": "3.0.0-beta.400",
+    "@webex/internal-plugin-mercury": "3.0.0-beta.400",
+    "@webex/webex-core": "3.0.0-beta.400",
     "lodash": "^4.17.21",
     "uuid": "^3.3.2"
   },
   "devDependencies": {
-    "@webex/internal-plugin-dss": "3.0.0-beta.4",
-    "@webex/test-helper-chai": "3.0.0-beta.4",
-    "@webex/test-helper-mock-webex": "3.0.0-beta.4"
+    "@webex/internal-plugin-dss": "3.0.0-beta.400",
+    "@webex/test-helper-chai": "3.0.0-beta.400",
+    "@webex/test-helper-mock-webex": "3.0.0-beta.400",
+    "sinon": "^9.2.4"
   }
 }

package/src/config.ts

@@ -0,0 +1,31 @@
+/*!
+ * Copyright (c) 2015-2022 Cisco Systems, Inc. See LICENSE file.
+ */
+
+export default {
+  dss: {
+    /**
+     * Timeout before DSS request fails, in milliseconds.
+     * @type {Number}
+     */
+    requestTimeout: 6000,
+
+    /**
+     * Debounce wait (ms) before sending a dss request (gap between lookups that will trigger a request)
+     * @type {Number}
+     */
+    batcherWait: 50,
+
+    /**
+     * Maximum queue size before sending a dss request
+     * @type {Number}
+     */
+    batcherMaxCalls: 50,
+
+    /**
+     * Debounce max wait (ms) before sending a dss request (time from first lookup that will trigger a request)
+     * @type {Number}
+     */
+    batcherMaxWait: 150,
+  },
+};

package/src/constants.ts

@@ -12,3 +12,8 @@ export const SEARCH_TYPES = {
   ROOM: 'ROOM',
   ROBOT: 'ROBOT',
 };
+export const LOOKUP_DATA_PATH = 'lookupResult.entities';
+export const LOOKUP_FOUND_PATH = 'lookupResult.entitiesFound';
+export const LOOKUP_NOT_FOUND_PATH = 'lookupResult.entitiesNotFound';
+export const LOOKUP_REQUEST_KEY = 'lookupValues';
+export const SEARCH_DATA_PATH = 'directoryEntities';

package/src/dss-batcher.ts

@@ -0,0 +1,129 @@
+/*!
+ * Copyright (c) 2015-2022 Cisco Systems, Inc. See LICENSE file.
+ */
+/* eslint-disable no-underscore-dangle */
+
+import {Batcher} from '@webex/webex-core';
+
+/**
+ * @class
+ */
+const DssBatcher = Batcher.extend({
+  namespace: 'DSS',
+
+  props: {
+    resource: {
+      type: 'string',
+      required: true,
+      setOnce: true,
+      allowNull: false,
+    },
+    dataPath: {
+      type: 'string',
+      required: true,
+      setOnce: true,
+      allowNull: false,
+    },
+    entitiesFoundPath: {
+      type: 'string',
+      required: true,
+      setOnce: true,
+      allowNull: false,
+    },
+    entitiesNotFoundPath: {
+      type: 'string',
+      required: true,
+      setOnce: true,
+      allowNull: false,
+    },
+    requestKey: {
+      type: 'string',
+      required: true,
+      setOnce: true,
+      allowNull: false,
+    },
+  },
+
+  /**
+   * Submits the DSS request
+   * @param {Object} payload
+   * @returns {Promise<Array>}
+   */
+  submitHttpRequest(payload: unknown) {
+    return this.parent._request({
+      dataPath: this.dataPath,
+      foundPath: this.entitiesFoundPath,
+      notFoundPath: this.entitiesNotFoundPath,
+      resource: this.resource,
+      params: {
+        lookupValues: payload,
+      },
+    });
+  },
+
+  /**
+   * Actions taken when the http request returns a success
+   * @param {Promise<Array>} res
+   * @returns {Promise<undefined>}
+   */
+  handleHttpSuccess(res) {
+    const successItems = res.foundArray.map((requestValue, index) => ({
+      requestValue,
+      entity: res.resultArray[index],
+    }));
+    const failureItems = res.notFoundArray.map((requestValue) => ({requestValue, entity: null}));
+
+    return Promise.all(successItems.concat(failureItems).map((item) => this.acceptItem(item)));
+  },
+
+  /**
+   * Checks if the item was found
+   * @param {Object} item
+   * @returns {Promise<Boolean>}
+   */
+  didItemFail(item) {
+    return Promise.resolve(item.entity === null);
+  },
+
+  /**
+   * Finds the Defer for the specified item and resolves its promise with null
+   * @param {Object} item
+   * @returns {Promise<undefined>}
+   */
+  handleItemFailure(item) {
+    return this.getDeferredForResponse(item).then((defer) => {
+      defer.resolve(null);
+    });
+  },
+
+  /**
+   * Finds the Defer for the specified item and resolves its promise
+   * @param {Object} item
+   * @returns {Promise<undefined>}
+   */
+  handleItemSuccess(item) {
+    return this.getDeferredForResponse(item).then((defer) => {
+      defer.resolve(item.entity);
+    });
+  },
+
+  /**
+   * Returns a promise with the unique key for the item
+   * @param {Object} item
+   * @returns {Promise}
+   */
+  fingerprintRequest(item) {
+    return Promise.resolve(item);
+  },
+
+  /**
+   * Returns a promise with the unique key for the item
+   * @param {Object} item
+   * @returns {Promise}
+   */
+  fingerprintResponse(item) {
+    return Promise.resolve(item.requestValue);
+  },
+});
+
+export default DssBatcher;

package/src/dss-errors.ts

@@ -0,0 +1,36 @@
+import {Exception} from '@webex/common';
+import {RequestOptions} from './types';
+
+interface DssTimeoutErrorParams extends Required<Pick<RequestOptions, 'resource' | 'params'>> {
+  requestId: string;
+  timeout: number;
+}
+
+/**
+ * Thrown when an expected DSS respond is not received in a timely manner.
+ */
+export class DssTimeoutError extends Exception {
+  /**
+   * Construct DssTimeoutError
+   * @param {DssTimeoutErrorParams} details
+   */
+  // eslint-disable-next-line no-useless-constructor
+  constructor(details: DssTimeoutErrorParams) {
+    super(details);
+  }
+
+  /**
+   * Parse Error details
+   *
+   * @param {DssTimeoutErrorParams} details
+   * @returns {string}
+   */
+  parse(details: DssTimeoutErrorParams) {
+    return (
+      `The DSS did not respond within ${details.timeout} ms.` +
+      `\n Request Id: ${details.requestId}` +
+      `\n Resource: ${details.resource}` +
+      `\n Params: ${JSON.stringify(details.params)}`
+    );
+  }
+}

package/src/dss.ts

@@ -2,12 +2,20 @@
 /*!
  * Copyright (c) 2015-2022 Cisco Systems, Inc. See LICENSE file.
  */
+/* eslint-disable no-underscore-dangle */
 import uuid from 'uuid';
 import {WebexPlugin} from '@webex/webex-core';
 import '@webex/internal-plugin-mercury';
 import {range, isEqual, get} from 'lodash';
-import type {SearchOptions, LookupDetailOptions, LookupOptions, LookupByEmailOptions} from './types';
 
+import {Timer} from '@webex/common-timers';
+import type {
+  SearchOptions,
+  LookupDetailOptions,
+  LookupOptions,
+  LookupByEmailOptions,
+  SearchPlaceOptions,
+} from './types';
 import {
   DSS_REGISTERED,
   DSS_UNREGISTERED,
@@ -16,7 +24,15 @@ import {
   DSS_SERVICE_NAME,
   DSS_SEARCH_MERCURY_EVENT,
   DSS_RESULT,
+  LOOKUP_DATA_PATH,
+  LOOKUP_FOUND_PATH,
+  LOOKUP_NOT_FOUND_PATH,
+  LOOKUP_REQUEST_KEY,
+  SEARCH_DATA_PATH,
 } from './constants';
+import DssBatcher from './dss-batcher';
+import {DssTimeoutError} from './dss-errors';
+import {BatcherOptions, RequestOptions, RequestResult} from './types';
 
 const DSS = WebexPlugin.extend({
   namespace: 'DSS',
@@ -29,6 +45,18 @@ const DSS = WebexPlugin.extend({
    */
   registered: false,
 
+  /**
+   * Initializer
+   * @private
+   * @param {Object} attrs
+   * @param {Object} options
+   * @returns {undefined}
+   */
+  initialize(...args) {
+    Reflect.apply(WebexPlugin.prototype.initialize, this, args);
+    this.batchers = {};
+  },
+
   /**
    * Explicitly sets up the DSS plugin by connecting to mercury, and listening for DSS events.
    * @returns {Promise}
@@ -48,7 +76,8 @@ const DSS = WebexPlugin.extend({
       return Promise.resolve();
     }
 
-    return this.webex.internal.mercury.connect()
+    return this.webex.internal.mercury
+      .connect()
       .then(() => {
         this.listenForEvents();
         this.trigger(DSS_REGISTERED);
@@ -76,11 +105,10 @@ const DSS = WebexPlugin.extend({
 
     this.stopListeningForEvents();
 
-    return this.webex.internal.mercury.disconnect()
-      .then(() => {
-        this.trigger(DSS_UNREGISTERED);
-        this.registered = false;
-      });
+    return this.webex.internal.mercury.disconnect().then(() => {
+      this.trigger(DSS_UNREGISTERED);
+      this.registered = false;
+    });
   },
 
   /**
@@ -108,6 +136,7 @@ const DSS = WebexPlugin.extend({
   },
 
   /**
+   * constructs the event name based on request id
    * @param {UUID} requestId the id of the request
    * @returns {string}
    */
@@ -116,6 +145,7 @@ const DSS = WebexPlugin.extend({
   },
 
   /**
+   * Takes incoming data and triggers correct events
    * @param {Object} data the event data
    * @returns {undefined}
    */
@@ -125,43 +155,81 @@ const DSS = WebexPlugin.extend({
   },
 
   /**
-    * Makes the request to the directory service
-    * @param {Object} options
-    * @param {string} options.resource the URL to query
-    * @param {string} options.params additional params for the body of the request
-    * @param {string} options.dataPath to path to get the data in the result object
-    * @returns {Promise} Resolves with an array of entities found
-  */
-  _request(options) {
-    const {resource, params, dataPath} = options;
+   * Makes the request to the directory service
+   * @param {Object} options
+   * @param {string} options.resource the URL to query
+   * @param {Mixed} options.params additional params for the body of the request
+   * @param {string} options.dataPath the path to get the data in the result object
+   * @param {string} [options.foundPath] the path to get the lookups of the found data
+   * @param {string} [options.notFoundPath] the path to get the lookups of the not found data
+   * @returns {Promise<Object>} result Resolves with an object
+   * @returns {Array} result.resultArray an array of entities found
+   * @returns {Array} result.foundArray an array of the lookups of the found entities (if foundPath provided)
+   * @returns {Array} result.notFoundArray an array of the lookups of the not found entities (if notFoundPath provided)
+   * @throws {DssTimeoutError} when server does not respond in the specified timeframe
+   */
+  _request(options: RequestOptions): Promise<RequestResult> {
+    const {resource, params, dataPath, foundPath, notFoundPath} = options;
 
+    const timeout = this.config.requestTimeout;
     const requestId = uuid.v4();
     const eventName = this._getResultEventName(requestId);
     const result = {};
-    let expectedSeqNums;
+    let expectedSeqNums: string[];
+    let notFoundArray: unknown[];
+
+    return new Promise((resolve, reject) => {
+      const timer = new Timer(() => {
+        this.stopListening(this, eventName);
+        reject(new DssTimeoutError({requestId, timeout, resource, params}));
+      }, timeout);
 
-    return new Promise((resolve) => {
       this.listenTo(this, eventName, (data) => {
-        const resultData = get(data, dataPath);
+        timer.reset();
+        const resultData = get(data, dataPath, []);
+        let found;
 
-        result[data.sequence] = resultData;
+        if (foundPath) {
+          found = get(data, foundPath, []);
+        }
+        result[data.sequence] = foundPath ? {resultData, found} : {resultData};
 
         if (data.finished) {
           expectedSeqNums = range(data.sequence + 1).map(String);
+          if (notFoundPath) {
+            notFoundArray = get(data, notFoundPath, []);
+          }
         }
 
         const done = isEqual(expectedSeqNums, Object.keys(result));
 
         if (done) {
-          const resultArray = [];
+          timer.cancel();
+
+          const resultArray: any[] = [];
+          const foundArray: any[] = [];
+
           expectedSeqNums.forEach((index) => {
             const seqResult = result[index];
+
             if (seqResult) {
-              resultArray.push(...seqResult);
+              resultArray.push(...seqResult.resultData);
+              if (foundPath) {
+                foundArray.push(...seqResult.found);
+              }
             }
-          })
-
-          resolve(resultArray);
+          });
+          const resolveValue: RequestResult = {
+            resultArray,
+          };
+
+          if (foundPath) {
+            resolveValue.foundArray = foundArray;
+          }
+          if (notFoundPath) {
+            resolveValue.notFoundArray = notFoundArray;
+          }
+          resolve(resolveValue);
           this.stopListening(this, eventName);
         }
       });
@@ -170,62 +238,130 @@ const DSS = WebexPlugin.extend({
         resource,
         method: 'POST',
         contentType: 'application/json',
-        body: {requestId, ...params}
+        body: {requestId, ...params},
       });
+      timer.start();
     });
   },
 
+  /**
+   * Uses a batcher to make the request to the directory service
+   * @param {Object} options
+   * @param {string} options.resource the URL to query
+   * @param {string} options.value the id or email to lookup
+   * @returns {Promise} Resolves with an array of entities found
+   * @throws {DssTimeoutError} when server does not respond in the specified timeframe
+   */
+  _batchedLookup(options: BatcherOptions) {
+    const {resource, lookupValue} = options;
+    const dataPath = LOOKUP_DATA_PATH;
+    const entitiesFoundPath = LOOKUP_FOUND_PATH;
+    const entitiesNotFoundPath = LOOKUP_NOT_FOUND_PATH;
+    const requestKey = LOOKUP_REQUEST_KEY;
+
+    this.batchers[resource] =
+      this.batchers[resource] ||
+      new DssBatcher({
+        resource,
+        dataPath,
+        entitiesFoundPath,
+        entitiesNotFoundPath,
+        requestKey,
+        parent: this,
+      });
+
+    return this.batchers[resource].request(lookupValue);
+  },
+
   /**
    * Retrieves detailed information about an entity
    * @param {Object} options
    * @param {UUID} options.id the id of the entity to lookup
-   * @returns {Promise} Resolves with an array of entities found
+   * @returns {Promise} Resolves with the entity found or null if not found
+   * @throws {DssTimeoutError} when server does not respond in the specified timeframe
    */
   lookupDetail(options: LookupDetailOptions) {
     const {id} = options;
 
+    const resource = `/lookup/orgid/${this.webex.internal.device.orgId}/identity/${id}/detail`;
+
     return this._request({
-      dataPath: 'lookupResult.entities',
-      resource: `/lookup/orgid/${this.webex.internal.device.orgId}/identity/${id}/detail`
+      dataPath: LOOKUP_DATA_PATH,
+      foundPath: LOOKUP_FOUND_PATH,
+      resource,
+    }).then(({resultArray, foundArray}) => {
+      // TODO: find out what is actually returned!
+      if (foundArray[0] === id) {
+        return resultArray[0];
+      }
+
+      return null;
     });
   },
 
   /**
-   * Retrieves basic information about a list entities within an organization
+   * Retrieves basic information about an entity within an organization
    * @param {Object} options
-   * @param {UUID} options.ids the id of the entity to lookup
-   * @param {UUID} options.entityProviderType the provider to query (optional)
-   * @returns {Promise} Resolves with an array of entities found
+   * @param {UUID} options.id the id of the entity to lookup
+   * @param {UUID} [options.entityProviderType] the provider to query
+   * @param {Boolean} options.shouldBatch whether to batch the query, set to false for single immediate result (defaults to true)
+   * @returns {Promise} Resolves with the entity found or null if not found
+   * @throws {DssTimeoutError} when server does not respond in the specified timeframe
    */
   lookup(options: LookupOptions) {
-    const {ids, entityProviderType} = options;
+    const {id, entityProviderType, shouldBatch = true} = options;
 
-    const resource = entityProviderType ? `/lookup/orgid/${this.webex.internal.device.orgId}/entityprovidertype/${entityProviderType}` : `/lookup/orgid/${this.webex.internal.device.orgId}/identities`;
+    const resource = entityProviderType
+      ? `/lookup/orgid/${this.webex.internal.device.orgId}/entityprovidertype/${entityProviderType}`
+      : `/lookup/orgid/${this.webex.internal.device.orgId}/identities`;
+
+    if (shouldBatch) {
+      return this._batchedLookup({
+        resource,
+        lookupValue: id,
+      });
+    }
 
     return this._request({
-      dataPath: 'lookupResult.entities',
+      dataPath: LOOKUP_DATA_PATH,
+      foundPath: LOOKUP_FOUND_PATH,
       resource,
       params: {
-        lookupValues: ids,
+        [LOOKUP_REQUEST_KEY]: [id],
+      },
+    }).then(({resultArray, foundArray}) => {
+      if (foundArray[0] === id) {
+        return resultArray[0];
       }
+
+      return null;
     });
   },
 
   /**
-   * Retrieves basic information about a list entities within an organization
+   * Retrieves basic information about an enitity within an organization
    * @param {Object} options
-   * @param {UUID} options.emails the emails of the entities to lookup
-   * @returns {Promise} Resolves with an array of entities found
+   * @param {UUID} options.email the email of the entity to lookup
+   * @returns {Promise} Resolves with the entity found or rejects if not found
+   * @throws {DssTimeoutError} when server does not respond in the specified timeframe
    */
   lookupByEmail(options: LookupByEmailOptions) {
-    const {emails} = options;
+    const {email} = options;
+    const resource = `/lookup/orgid/${this.webex.internal.device.orgId}/emails`;
 
     return this._request({
-      dataPath: 'lookupResult.entities',
-      resource: `/lookup/orgid/${this.webex.internal.device.orgId}/emails`,
+      dataPath: LOOKUP_DATA_PATH,
+      foundPath: LOOKUP_FOUND_PATH,
+      resource,
       params: {
-        lookupValues: emails,
+        [LOOKUP_REQUEST_KEY]: [email],
+      },
+    }).then(({resultArray, foundArray}) => {
+      if (foundArray[0] === email) {
+        return resultArray[0];
       }
+
+      return null;
     });
   },
 
@@ -236,23 +372,46 @@ const DSS = WebexPlugin.extend({
    * @param {string[]} options.queryString A query string that will be transformed into a Directory search filter query. It is used to search the following fields: username, givenName, familyName, displayName and email
    * @param {number} options.resultSize The maximum number of results returned from each provider
    * @returns {Promise} Resolves with an array of entities found
+   * @throws {DssTimeoutError} when server does not respond in the specified timeframe
    */
   search(options: SearchOptions) {
-    const {
-      requestedTypes, resultSize, queryString
-    } = options;
+    const {requestedTypes, resultSize, queryString} = options;
 
     return this._request({
-      dataPath: 'directoryEntities',
+      dataPath: SEARCH_DATA_PATH,
       resource: `/search/orgid/${this.webex.internal.device.orgId}/entities`,
       params: {
         queryString,
         resultSize,
-        requestedTypes
-      }
-    });
-  }
+        requestedTypes,
+      },
+    }).then(({resultArray}) => resultArray);
+  },
+
+  /**
+   * Search for information about places
+   * @param {Object} options
+   * @param {string} options.queryString A query string that will be transformed into a Directory search filter query. It is used to search the following fields: placeName, displayName.
+   * @param {number} options.resultSize The maximum number of results returned from each provider
+   * @returns {Promise} Resolves with an array of entities found
+   */
+  searchPlaces(options: SearchPlaceOptions) {
+    const {resultSize, queryString, isOnlySchedulableRooms} = options;
 
+    return this._request({
+      dataPath: 'directoryEntities',
+      resource: `/search/orgid/${this.webex.internal.device.orgId}/places`,
+      params: {
+        queryString,
+        resultSize,
+        isOnlySchedulableRooms,
+      },
+    }).catch((error) => {
+      this.logger.error(`DSS->search place#ERROR, search place failure, ${error.message}`);
+
+      return Promise.reject(error);
+    });
+  },
 });
 
 export default DSS;

package/src/index.ts

@@ -1,7 +1,8 @@
 import {registerInternalPlugin} from '@webex/webex-core';
 
 import DSS from './dss';
+import config from './config';
 
-registerInternalPlugin('dss', DSS);
+registerInternalPlugin('dss', DSS, {config});
 
 export {default} from './dss';