@webex/internal-plugin-dss 3.0.0-bnr.5 → 3.0.0

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,17 +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 {Timer} from '@webex/common-timers';
 import type {
   SearchOptions,
   LookupDetailOptions,
   LookupOptions,
   LookupByEmailOptions,
+  SearchPlaceOptions,
 } from './types';
-
 import {
   DSS_REGISTERED,
   DSS_UNREGISTERED,
@@ -21,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',
@@ -34,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}
@@ -113,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}
    */
@@ -121,6 +145,7 @@ const DSS = WebexPlugin.extend({
   },
 
   /**
+   * Takes incoming data and triggers correct events
    * @param {Object} data the event data
    * @returns {undefined}
    */
@@ -133,40 +158,78 @@ 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
+   * @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) {
-    const {resource, params, dataPath} = options;
+  _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);
         }
       });
@@ -177,62 +240,128 @@ const DSS = WebexPlugin.extend({
         contentType: 'application/json',
         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`;
 
+    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;
     });
   },
 
@@ -243,18 +372,44 @@ 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;
 
     return this._request({
-      dataPath: 'directoryEntities',
+      dataPath: SEARCH_DATA_PATH,
       resource: `/search/orgid/${this.webex.internal.device.orgId}/entities`,
       params: {
         queryString,
         resultSize,
         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);
     });
   },
 });

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';

package/src/types.ts

@@ -1,8 +1,21 @@
+export interface RequestOptions {
+  resource: string;
+  dataPath: string;
+  foundPath?: string;
+  notFoundPath?: string;
+  params?: Record<string, unknown>;
+}
+
+export interface RequestResult {
+  foundArray?: any[];
+  notFoundArray?: any[];
+  resultArray: any[];
+}
+
 export interface LookupDetailOptions {
   id: string;
 }
 
-// eslint-disable-next-line no-shadow
 export enum EntityProviderType {
   CI_USER = 'CI_USER',
   CI_MACHINE = 'CI_MACHINE',
@@ -11,12 +24,13 @@ export enum EntityProviderType {
 }
 
 export interface LookupOptions {
-  ids: string[];
+  id: string;
   entityProviderType?: EntityProviderType;
+  shouldBatch?: boolean;
 }
 
 export interface LookupByEmailOptions {
-  emails: string[];
+  email: string;
 }
 
 // eslint-disable-next-line no-shadow
@@ -33,3 +47,14 @@ export interface SearchOptions {
   resultSize: number;
   queryString: string;
 }
+
+export interface BatcherOptions {
+  resource: string;
+  lookupValue: string;
+}
+
+export interface SearchPlaceOptions {
+  resultSize: number;
+  queryString: string;
+  isOnlySchedulableRooms: boolean;
+}