@webex/webex-core 3.12.0-next.32 → 3.12.0-next.34

package/src/lib/services/services.js

@@ -57,6 +57,22 @@ const Services = WebexPlugin.extend({
     initFailed: ['boolean', false, false],
   },
 
+  session: {
+    /**
+     * Becomes `true` once the initial catalog collection has completed
+     * (successfully or otherwise) and any in-flight credentials refresh has
+     * settled. Blocks `webex.ready` so consumers can rely on `webex.ready`
+     * implying "catalogs populated AND credential state stable".
+     * @instance
+     * @memberof Services
+     * @type {boolean}
+     */
+    ready: {
+      default: false,
+      type: 'boolean',
+    },
+  },
+
   _catalogs: new WeakMap(),
 
   _serviceUrls: null,
@@ -1346,6 +1362,7 @@ const Services = WebexPlugin.extend({
 
     // Destructure the credentials plugin.
     const {credentials} = this.webex;
+    const catalog = this._getCatalog();
 
     // Init a promise chain. Must be done as a Promise.resolve() to allow
     // credentials#getOrgId() to properly throw.
@@ -1358,12 +1375,18 @@ const Services = WebexPlugin.extend({
         .then(() => {
           // Validate if the token is authorized.
           if (credentials.canAuthorize) {
-            // Attempt to collect the postauth catalog.
-
-            return this.updateServices().catch(() => {
-              this.initFailed = true;
-              this.logger.warn('services: cannot retrieve postauth catalog');
-            });
+            // Attempt to collect the postauth catalog, then mark the catalog
+            // ready. Setting `isReady` here - rather than only in the init
+            // callers - means a slow postauth fetch that loses the gated-init
+            // timeout race still marks the catalog ready once it completes.
+            return this.updateServices()
+              .then(() => {
+                catalog.isReady = true;
+              })
+              .catch(() => {
+                this.initFailed = true;
+                this.logger.warn('services: cannot retrieve postauth catalog');
+              });
           }
 
           // Return a resolved promise for consistent return value.
@@ -1372,6 +1395,29 @@ const Services = WebexPlugin.extend({
     );
   },
 
+  /**
+   * Await any in-flight credentials refresh, then flip `services.ready` so
+   * `webex.ready` can fire. Closes the parallel-refresh window: if a credential
+   * refresh is in flight when initial catalog collection settles, we must not
+   * signal ready until the refresh has resolved - otherwise downstream
+   * consumers may observe `canAuthorize`/token state that is about to change
+   * under them.
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  async _finalizeReady() {
+    const {credentials} = this.webex;
+
+    if (credentials && credentials.isRefreshing) {
+      await new Promise((resolve) => {
+        credentials.once('change:isRefreshing', resolve);
+      });
+    }
+
+    this.ready = true;
+  },
+
   /**
    * Initializer
    *
@@ -1388,11 +1434,39 @@ const Services = WebexPlugin.extend({
     this.registries.set(this.webex, registry);
     this.states.set(this.webex, state);
 
-    // Listen for configuration changes once.
+    // Listen for configuration changes once. The config is not populated on the
+    // webex instance until the `change:config` event fires, so any decision that
+    // depends on config values (such as the gated-vs-ungated init below) must be
+    // made from within this handler rather than synchronously in `initialize()`.
     this.listenToOnce(this.webex, 'change:config', () => {
       this.initConfig();
+
+      // Feature flag: when enabled, `webex.ready` is blocked until the initial
+      // catalog collection has settled AND any in-flight credentials refresh has
+      // completed. When disabled (the default), preserves the pre-existing
+      // behavior where `webex.ready` fires as soon as `webex.loaded` does and
+      // the catalog is collected out-of-band.
+      const waitForCatalogInit = this.webex.config?.services?.waitForCatalogInit === true;
+
+      if (waitForCatalogInit) {
+        this._initializeCatalogsGated(catalog);
+      } else {
+        // Not gating - immediately mark ready so we do not block webex.ready.
+        this.ready = true;
+        this._initializeCatalogsUngated(catalog);
+      }
     });
+  },
 
+  /**
+   * Original (pre-verified-ready) initialization path. Runs on `webex.ready`
+   * and collects catalogs opportunistically without blocking anything.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsUngated(catalog) {
     // wait for webex instance to be ready before attempting
     // to update the service catalogs
     // this can cause a race condition because credentials may
@@ -1407,16 +1481,14 @@ const Services = WebexPlugin.extend({
       const {supertoken} = this.webex.credentials;
       // Validate if the supertoken exists.
       if (supertoken && supertoken.access_token) {
-        this.initServiceCatalogs()
-          .then(() => {
-            catalog.isReady = true;
-          })
-          .catch((error) => {
-            this.initFailed = true;
-            this.logger.error(
-              `services: failed to init initial services when credentials available, ${error?.message}`
-            );
-          });
+        // `initServiceCatalogs` marks the catalog ready internally once the
+        // postauth catalog is collected.
+        this.initServiceCatalogs().catch((error) => {
+          this.initFailed = true;
+          this.logger.error(
+            `services: failed to init initial services when credentials available, ${error?.message}`
+          );
+        });
       } else {
         const {email} = this.webex.config;
 
@@ -1429,6 +1501,87 @@ const Services = WebexPlugin.extend({
       }
     });
   },
+
+  /**
+   * Verified-ready initialization path. Blocks `webex.ready` until the initial
+   * catalog fetch has settled (or timed out) AND any in-flight credentials
+   * refresh has completed. Also handles the fresh-login case where OAuth
+   * completes after `loaded` fires.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsGated(catalog) {
+    // Wait for storage to be loaded before attempting to update the service
+    // catalogs. We listen for 'loaded' instead of 'ready' because `services.ready`
+    // now blocks `webex.ready` - listening to 'ready' would deadlock.
+    this.listenToOnce(this.webex, 'loaded', async () => {
+      const cachedCatalog = await this._loadCatalogFromCache();
+      if (cachedCatalog) {
+        catalog.isReady = true;
+        await this._finalizeReady();
+
+        return; // skip initServiceCatalogs() on reload when cache exists
+      }
+      const {supertoken} = this.webex.credentials;
+
+      // Race init against a hard timeout so a hung request never leaves
+      // `services.ready` false forever - that would stall `webex.ready` and
+      // leave consumers waiting on it indefinitely. Timeout is configurable via
+      // `config.services.catalogInitTimeout` (defaults to 15s in config).
+      const initTimeoutMs = this.webex.config?.services?.catalogInitTimeout;
+
+      const initServiceCatalogsTimeout = new Promise((_, reject) => {
+        setTimeout(
+          () => reject(new Error(`services: init timed out after ${initTimeoutMs}ms`)),
+          initTimeoutMs
+        );
+      });
+
+      // Validate if the supertoken exists.
+      if (supertoken && supertoken.access_token) {
+        // `initServiceCatalogs` marks the catalog ready internally once the
+        // postauth catalog is collected - even if it loses the timeout race
+        // above, so a slow fetch still eventually flips `catalog.isReady`.
+        Promise.race([this.initServiceCatalogs(), initServiceCatalogsTimeout])
+          .catch((error) => {
+            this.initFailed = true;
+            this.logger.error(
+              `services: failed to init initial services when credentials available, ${error?.message}`
+            );
+          })
+          .finally(() => this._finalizeReady());
+      } else {
+        const {email} = this.webex.config;
+
+        Promise.race([
+          this.collectPreauthCatalog(email ? {email} : undefined),
+          initServiceCatalogsTimeout,
+        ])
+          .catch((error) => {
+            this.initFailed = true;
+            this.logger.error(
+              `services: failed to init initial services when no credentials available, ${error?.message}`
+            );
+          })
+          .finally(() => this._finalizeReady());
+
+        // Handle fresh login: 'loaded' fires before OAuth completes, so listen
+        // for `canAuthorize` flipping true and then collect the postauth catalog.
+        this.listenToOnce(this.webex, 'change:canAuthorize', () => {
+          if (this.webex.canAuthorize && !catalog.status.postauth.ready) {
+            // `initServiceCatalogs` marks the catalog ready internally.
+            this.initServiceCatalogs().catch((error) => {
+              this.logger.error(
+                `services: failed to init service catalogs after auth, ${error?.message}`
+              );
+            });
+          }
+        });
+      }
+    });
+  },
 });
 /* eslint-enable no-underscore-dangle */
 

package/src/lib/services-v2/services-v2.ts

@@ -44,6 +44,22 @@ const Services = WebexPlugin.extend({
     initFailed: ['boolean', false, false],
   },
 
+  session: {
+    /**
+     * Becomes `true` once the initial catalog collection has completed
+     * (successfully or otherwise) and any in-flight credentials refresh has
+     * settled. Blocks `webex.ready` so consumers can rely on `webex.ready`
+     * implying "catalogs populated AND credential state stable".
+     * @instance
+     * @memberof Services
+     * @type {boolean}
+     */
+    ready: {
+      default: false,
+      type: 'boolean',
+    },
+  },
+
   _catalogs: new WeakMap(),
 
   _activeServices: {},
@@ -1312,6 +1328,7 @@ const Services = WebexPlugin.extend({
 
     // Destructure the credentials plugin.
     const {credentials} = this.webex;
+    const catalog = this._getCatalog();
 
     // Init a promise chain. Must be done as a Promise.resolve() to allow
     // credentials#getOrgId() to properly throw.
@@ -1324,11 +1341,18 @@ const Services = WebexPlugin.extend({
         .then(() => {
           // Validate if the token is authorized.
           if (credentials.canAuthorize) {
-            // Attempt to collect the postauth catalog.
-            return this.updateServices({forceRefresh: refresh}).catch(() => {
-              this.initFailed = true;
-              this.logger.warn('services: cannot retrieve postauth catalog');
-            });
+            // Attempt to collect the postauth catalog, then mark the catalog
+            // ready. Setting `isReady` here - rather than only in the init
+            // callers - means a slow postauth fetch that loses the gated-init
+            // timeout race still marks the catalog ready once it completes.
+            return this.updateServices({forceRefresh: refresh})
+              .then(() => {
+                catalog.isReady = true;
+              })
+              .catch(() => {
+                this.initFailed = true;
+                this.logger.warn('services: cannot retrieve postauth catalog');
+              });
           }
 
           // Return a resolved promise for consistent return value.
@@ -1337,6 +1361,29 @@ const Services = WebexPlugin.extend({
     );
   },
 
+  /**
+   * Await any in-flight credentials refresh, then flip `services.ready` so
+   * `webex.ready` can fire. Closes the parallel-refresh window: if a credential
+   * refresh is in flight when initial catalog collection settles, we must not
+   * signal ready until the refresh has resolved - otherwise downstream
+   * consumers may observe `canAuthorize`/token state that is about to change
+   * under them.
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  async _finalizeReady(): Promise<void> {
+    const {credentials} = this.webex;
+
+    if (credentials && credentials.isRefreshing) {
+      await new Promise<void>((resolve) => {
+        credentials.once('change:isRefreshing', resolve);
+      });
+    }
+
+    this.ready = true;
+  },
+
   /**
    * Initializer
    *
@@ -1348,11 +1395,39 @@ const Services = WebexPlugin.extend({
     const catalog = new ServiceCatalog();
     this._catalogs.set(this.webex, catalog);
 
-    // Listen for configuration changes once.
+    // Listen for configuration changes once. The config is not populated on the
+    // webex instance until the `change:config` event fires, so any decision that
+    // depends on config values (such as the gated-vs-ungated init below) must be
+    // made from within this handler rather than synchronously in `initialize()`.
     this.listenToOnce(this.webex, 'change:config', () => {
       this.initConfig();
+
+      // Feature flag: when enabled, `webex.ready` is blocked until the initial
+      // catalog collection has settled AND any in-flight credentials refresh has
+      // completed. When disabled (the default), preserves the pre-existing
+      // behavior where `webex.ready` fires as soon as `webex.loaded` does and
+      // the catalog is collected out-of-band.
+      const waitForCatalogInit = this.webex.config?.services?.waitForCatalogInit === true;
+
+      if (waitForCatalogInit) {
+        this._initializeCatalogsGated(catalog);
+      } else {
+        // Not gating - immediately mark ready so we do not block webex.ready.
+        this.ready = true;
+        this._initializeCatalogsUngated(catalog);
+      }
     });
+  },
 
+  /**
+   * Original (pre-verified-ready) initialization path. Runs on `webex.ready`
+   * and collects catalogs opportunistically without blocking anything.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsUngated(catalog: ServiceCatalog): void {
     // wait for webex instance to be ready before attempting
     // to update the service catalogs
     this.listenToOnce(this.webex, 'ready', async () => {
@@ -1365,16 +1440,14 @@ const Services = WebexPlugin.extend({
       const {supertoken} = this.webex.credentials;
       // Validate if the supertoken exists.
       if (supertoken && supertoken.access_token) {
-        this.initServiceCatalogs()
-          .then(() => {
-            catalog.isReady = true;
-          })
-          .catch((error) => {
-            this.initFailed = true;
-            this.logger.error(
-              `services: failed to init initial services when credentials available, ${error?.message}`
-            );
-          });
+        // `initServiceCatalogs` marks the catalog ready internally once the
+        // postauth catalog is collected.
+        this.initServiceCatalogs().catch((error) => {
+          this.initFailed = true;
+          this.logger.error(
+            `services: failed to init initial services when credentials available, ${error?.message}`
+          );
+        });
       } else {
         const {email} = this.webex.config;
 
@@ -1387,6 +1460,86 @@ const Services = WebexPlugin.extend({
       }
     });
   },
+
+  /**
+   * Verified-ready initialization path. Blocks `webex.ready` until the initial
+   * catalog fetch has settled (or timed out) AND any in-flight credentials
+   * refresh has completed. Also handles the fresh-login case where OAuth
+   * completes after `loaded` fires.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsGated(catalog: ServiceCatalog): void {
+    // Wait for storage to be loaded before attempting to update the service
+    // catalogs. We listen for 'loaded' instead of 'ready' because `services.ready`
+    // now blocks `webex.ready` - listening to 'ready' would deadlock.
+    this.listenToOnce(this.webex, 'loaded', async () => {
+      const warmed = await this._loadCatalogFromCache();
+      if (warmed) {
+        catalog.isReady = true;
+        await this._finalizeReady();
+
+        return;
+      }
+      const {supertoken} = this.webex.credentials;
+
+      // Race init against a hard timeout so a hung request never leaves
+      // `services.ready` false forever - that would stall `webex.ready` and
+      // leave consumers waiting on it indefinitely. Timeout is configurable via
+      // `config.services.catalogInitTimeout` (defaults to 15s in config).
+      const initTimeoutMs = this.webex.config?.services?.catalogInitTimeout;
+      const initServiceCatalogsTimeout = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new Error(`services: init timed out after ${initTimeoutMs}ms`)),
+          initTimeoutMs
+        );
+      });
+
+      // Validate if the supertoken exists.
+      if (supertoken && supertoken.access_token) {
+        // `initServiceCatalogs` marks the catalog ready internally once the
+        // postauth catalog is collected - even if it loses the timeout race
+        // above, so a slow fetch still eventually flips `catalog.isReady`.
+        Promise.race([this.initServiceCatalogs(), initServiceCatalogsTimeout])
+          .catch((error) => {
+            this.initFailed = true;
+            this.logger.error(
+              `services: failed to init initial services when credentials available, ${error?.message}`
+            );
+          })
+          .finally(() => this._finalizeReady());
+      } else {
+        const {email} = this.webex.config;
+
+        Promise.race([
+          this.collectPreauthCatalog(email ? {email} : undefined),
+          initServiceCatalogsTimeout,
+        ])
+          .catch((error) => {
+            this.initFailed = true;
+            this.logger.error(
+              `services: failed to init initial services when no credentials available, ${error?.message}`
+            );
+          })
+          .finally(() => this._finalizeReady());
+
+        // Handle fresh login: 'loaded' fires before OAuth completes, so listen
+        // for `canAuthorize` flipping true and then collect the postauth catalog.
+        this.listenToOnce(this.webex, 'change:canAuthorize', () => {
+          if (this.webex.canAuthorize && !catalog.status.postauth.ready) {
+            // `initServiceCatalogs` marks the catalog ready internally.
+            this.initServiceCatalogs().catch((error) => {
+              this.logger.error(
+                `services: failed to init service catalogs after auth, ${error?.message}`
+              );
+            });
+          }
+        });
+      }
+    });
+  },
 });
 /* eslint-enable no-underscore-dangle */
 

package/test/fixtures/activation-email.ts

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) 2015-2020 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import uuid from 'uuid';
+
+/**
+ * Generates a unique test email for user-activation/validation specs.
+ *
+ * The local part is kept short on purpose: for a brand-new self-signup user the
+ * backend derives the "given name" from the email local part, and self-signup
+ * orgs cap the given name at 50 characters. A full UUID would push the local
+ * part to 59 chars and fail with errorCode 100018, so we use 20 hex characters
+ * of entropy (local part = 43 chars).
+ *
+ * @returns {string} e.g. `Collabctg+webex-js-sdk-1a2b3c4d5e6f7a8b9c0d@gmail.com`
+ */
+export function createActivationEmail(): string {
+  return `Collabctg+webex-js-sdk-${uuid.v4().replace(/-/g, '').slice(0, 20)}@gmail.com`;
+}
+
+export default createActivationEmail;

package/test/integration/spec/services/services.js

@@ -20,6 +20,7 @@ import WebexCore, {
 import testUsers from '@webex/test-helper-test-users';
 import uuid from 'uuid';
 import sinon from 'sinon';
+import {createActivationEmail} from '../../../fixtures/activation-email';
 
 /* eslint-disable no-underscore-dangle */
 describe('webex-core', () => {
@@ -408,11 +409,13 @@ describe('webex-core', () => {
         services._loadCatalogFromCache = sinon.stub().resolves(false);
         services.initServiceCatalogs = sinon.stub().resolves();
         services.initialize();
+        // The mode-specific ('ready'/'loaded') listener is registered inside the
+        // change:config handler, so fire change:config first, then 'ready'.
+        webex.trigger('change:config');
         webex.trigger('ready');
         // Wait for the async 'ready' handler to complete
         await new Promise((resolve) => setTimeout(resolve, 50));
         assert.called(services.initServiceCatalogs);
-        assert.isTrue(catalog.isReady);
       });
 
       it('should collect different catalogs based on OrgId region', () =>
@@ -430,6 +433,39 @@ describe('webex-core', () => {
           done();
         }, 2000);
       });
+
+      it('blocks webex.ready until services.ready flips when waitForCatalogInit is enabled', async () => {
+        const gatedWebex = new WebexCore({
+          credentials: {supertoken: webexUser.token},
+          config: {services: {waitForCatalogInit: true}},
+        });
+
+        // Before init settles, webex.ready must be false because services.ready
+        // is a dependency and starts false in the gated path.
+        assert.isFalse(gatedWebex.internal.services.ready, 'services.ready should start false');
+        assert.isFalse(gatedWebex.ready, 'webex.ready should not fire while services.ready is false');
+
+        // Wait up to 30s for services init to complete and flip ready.
+        await new Promise((resolve, reject) => {
+          if (gatedWebex.internal.services.ready) {
+            resolve();
+
+            return;
+          }
+          const timer = setTimeout(
+            () => reject(new Error('timed out waiting for services.ready')),
+            30_000
+          );
+
+          gatedWebex.internal.services.once('change:ready', () => {
+            clearTimeout(timer);
+            resolve();
+          });
+        });
+
+        assert.isTrue(gatedWebex.internal.services.ready, 'services.ready should flip true after init settles');
+        assert.isTrue(gatedWebex.ready, 'webex.ready should fire once services.ready flips');
+      });
     });
 
     describe('#initServiceCatalogs()', () => {
@@ -892,7 +928,7 @@ describe('webex-core', () => {
 
       it('validates a non-existing user', () =>
         unauthServices
-          .validateUser({email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`})
+          .validateUser({email: createActivationEmail()})
           .then((r) => {
             assert.hasAllKeys(r, ['activated', 'exists', 'user', 'details']);
             assert.equal(r.activated, false);
@@ -905,7 +941,7 @@ describe('webex-core', () => {
       it('validates new user with activationOptions suppressEmail false', () =>
         unauthServices
           .validateUser({
-            email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`,
+            email: createActivationEmail(),
             activationOptions: {suppressEmail: false},
           })
           .then((r) => {
@@ -921,7 +957,7 @@ describe('webex-core', () => {
       it('validates new user with activationOptions suppressEmail true', () =>
         unauthServices
           .validateUser({
-            email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`,
+            email: createActivationEmail(),
             activationOptions: {suppressEmail: true},
           })
           .then((r) => {
@@ -977,7 +1013,7 @@ describe('webex-core', () => {
 
         return unauthServices
           .validateUser({
-            email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`,
+            email: createActivationEmail(),
             activationOptions: {suppressEmail: true},
           })
           .then(() => {
@@ -991,7 +1027,7 @@ describe('webex-core', () => {
 
         return unauthServices
           .validateUser({
-            email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`,
+            email: createActivationEmail(),
             activationOptions: {suppressEmail: true},
             preloginUserId,
           })
@@ -1008,7 +1044,7 @@ describe('webex-core', () => {
 
         return unauthServices
           .validateUser({
-            email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`,
+            email: createActivationEmail(),
             activationOptions: {suppressEmail: true},
           })
           .then(() => {
@@ -1031,7 +1067,7 @@ describe('webex-core', () => {
 
         return userOnboardingServices
           .validateUser({
-            email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`,
+            email: createActivationEmail(),
             activationOptions: {suppressEmail: true},
           })
           .then(() => {