@webex/webex-core 3.12.0-webex-services-ready.1 → 3.12.0-webex-services-ready.2

package/src/lib/services/services.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-console */
 import sha256 from 'crypto-js/sha256';
 
 import {union, forEach} from 'lodash';
@@ -66,8 +65,10 @@ const Services = WebexPlugin.extend({
 
   session: {
     /**
-     * Becomes `true` once service catalog initialization has completed.
-     * Blocks `webex.ready` until services are initialized.
+     * 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}
@@ -1414,7 +1415,6 @@ const Services = WebexPlugin.extend({
     }
 
     this.ready = true;
-    this.trigger('services:initialized');
   },
 
   /**
@@ -1433,14 +1433,90 @@ 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
+    // not be valid when services is initialized
+    this.listenToOnce(this.webex, 'ready', async () => {
+      const cachedCatalog = await this._loadCatalogFromCache();
+      if (cachedCatalog) {
+        catalog.isReady = true;
 
-    // Wait for storage to be loaded before attempting to update the service catalogs.
-    // We listen for 'loaded' instead of 'ready' because services.ready is a dependency
-    // of webex.ready - listening to 'ready' would cause a deadlock.
+        return; // skip initServiceCatalogs() on reload when cache exists
+      }
+      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}`
+            );
+          });
+      } else {
+        const {email} = this.webex.config;
+
+        this.collectPreauthCatalog(email ? {email} : undefined).catch((error) => {
+          this.initFailed = true;
+          this.logger.error(
+            `services: failed to init initial services when no credentials available, ${error?.message}`
+          );
+        });
+      }
+    });
+  },
+
+  /**
+   * 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) {
@@ -1485,19 +1561,16 @@ const Services = WebexPlugin.extend({
             );
           })
           .finally(() => this._finalizeReady());
-        // Listen for when credentials become available to fetch the full catalog.
-        // This handles fresh login where 'loaded' fires before OAuth completes.
+
+        // 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) {
-            this.initServiceCatalogs()
-              .then(() => {
-                catalog.isReady = true;
-              })
-              .catch((error) => {
-                this.logger.error(
-                  `services: failed to init service catalogs after auth, ${error?.message}`
-                );
-              });
+            this.initServiceCatalogs().catch((error) => {
+              this.logger.error(
+                `services: failed to init service catalogs after auth, ${error?.message}`
+              );
+            });
           }
         });
       }

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

@@ -52,8 +52,10 @@ const Services = WebexPlugin.extend({
 
   session: {
     /**
-     * Becomes `true` once services initialization has completed.
-     * This blocks `webex.ready` until services are initialized.
+     * 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}
@@ -1378,7 +1380,6 @@ const Services = WebexPlugin.extend({
     }
 
     this.ready = true;
-    this.trigger('services:initialized');
   },
 
   /**
@@ -1392,14 +1393,88 @@ 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 () => {
+      const warmed = await this._loadCatalogFromCache();
+      if (warmed) {
+        catalog.isReady = true;
 
-    // Wait for storage to be loaded before attempting to update the service catalogs.
-    // We listen for 'loaded' instead of 'ready' because services.ready is a dependency
-    // of webex.ready - listening to 'ready' would cause a deadlock.
+        return;
+      }
+      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}`
+            );
+          });
+      } else {
+        const {email} = this.webex.config;
+
+        this.collectPreauthCatalog(email ? {email} : undefined).catch((error) => {
+          this.initFailed = true;
+          this.logger.error(
+            `services: failed to init initial services when no credentials available, ${error?.message}`
+          );
+        });
+      }
+    });
+  },
+
+  /**
+   * 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) {
@@ -1444,19 +1519,16 @@ const Services = WebexPlugin.extend({
             );
           })
           .finally(() => this._finalizeReady());
-        // Listen for when credentials become available to fetch the full catalog.
-        // This handles fresh login where 'loaded' fires before OAuth completes.
+
+        // 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) {
-            this.initServiceCatalogs()
-              .then(() => {
-                catalog.isReady = true;
-              })
-              .catch((error) => {
-                this.logger.error(
-                  `services: failed to init service catalogs after auth, ${error?.message}`
-                );
-              });
+            this.initServiceCatalogs().catch((error) => {
+              this.logger.error(
+                `services: failed to init service catalogs after auth, ${error?.message}`
+              );
+            });
           }
         });
       }

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

@@ -404,26 +404,15 @@ describe('webex-core', () => {
         assert.isTrue(catalog.isReady);
       });
 
-      it('should call services#initServiceCatalogs() on webex loaded', async () => {
+      it('should call services#initServiceCatalogs() on webex ready', async () => {
+        services._loadCatalogFromCache = sinon.stub().resolves(false);
         services.initServiceCatalogs = sinon.stub().resolves();
         services.initialize();
-        webex.trigger('loaded');
-        // Wait for the async callback to execute
-        await new Promise((resolve) => setTimeout(resolve, 10));
+        webex.trigger('ready');
+        // Wait for the async 'ready' handler to complete
+        await new Promise((resolve) => setTimeout(resolve, 50));
         assert.called(services.initServiceCatalogs);
-      });
-
-      it('should set services.ready to true after initialization completes', async () => {
-        // services.ready starts as false
-        const newWebex = new WebexCore({credentials: {supertoken: webexUser.token}});
-        const newServices = newWebex.internal.services;
-
-        // Wait for initialization to complete
-        await new Promise((resolve) => {
-          newServices.on('services:initialized', resolve);
-        });
-
-        assert.isTrue(newServices.ready);
+        assert.isTrue(catalog.isReady);
       });
 
       it('should collect different catalogs based on OrgId region', () =>
@@ -441,6 +430,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()', () => {

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

@@ -316,26 +316,15 @@ describe('webex-core', () => {
         assert.isTrue(catalog.isReady);
       });
 
-      it('should call services#initServiceCatalogs() on webex loaded', async () => {
+      it('should call services#initServiceCatalogs() on webex ready', async () => {
+        services._loadCatalogFromCache = sinon.stub().resolves(false);
         services.initServiceCatalogs = sinon.stub().resolves();
         services.initialize();
-        webex.trigger('loaded');
-        // Wait for the async callback to execute
-        await new Promise((resolve) => setTimeout(resolve, 10));
+        webex.trigger('ready');
+        // Wait for the async 'ready' handler to complete
+        await new Promise((resolve) => setTimeout(resolve, 50));
         assert.called(services.initServiceCatalogs);
-      });
-
-      it('should set services.ready to true after initialization completes', async () => {
-        // services.ready starts as false
-        const newWebex = new WebexCore({credentials: {supertoken: webexUser.token}});
-        const newServices = newWebex.internal.services;
-
-        // Wait for initialization to complete
-        await new Promise((resolve) => {
-          newServices.on('services:initialized', resolve);
-        });
-
-        assert.isTrue(newServices.ready);
+        assert.isTrue(catalog.isReady);
       });
 
       it('should collect different catalogs based on OrgId region', () =>
@@ -352,6 +341,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()', () => {