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

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

@@ -15,6 +15,7 @@ import {
   ServiceHostmap,
   ServiceGroup,
   ServiceHost,
+  SelectionMeta,
 } from './types';
 
 const trailingSlashes = /(?:^\/)|(?:\/$)/;
@@ -28,6 +29,15 @@ const CLUSTER_SERVICE = process.env.WEBEX_CONVERSATION_CLUSTER_SERVICE || DEFAUL
 const DEFAULT_CLUSTER_IDENTIFIER =
   process.env.WEBEX_CONVERSATION_DEFAULT_CLUSTER || `${DEFAULT_CLUSTER}:${CLUSTER_SERVICE}`;
 
+const CATALOG_CACHE_KEY_V2 = 'services.v2.u2cHostMap';
+const CATALOG_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+// Maximum time we will wait for the initial catalog collection before letting
+// `services.ready` (and therefore `webex.ready`) fire anyway. A hung request
+// must never leave the app on a permanent spinner - past this point downstream
+// consumers must fall through to their normal error/login paths.
+const SERVICES_INIT_TIMEOUT_MS = 15_000;
+
 /* eslint-disable no-underscore-dangle */
 /**
  * @class
@@ -40,6 +50,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: {},
@@ -56,6 +82,46 @@ const Services = WebexPlugin.extend({
     return this._catalogs.get(this.webex);
   },
 
+  /**
+   * Safely access localStorage if available; returns the Storage or null.
+   * @returns {Storage | null}
+   */
+  _getLocalStorageSafe(): Storage | null {
+    if (typeof window !== 'undefined' && (window as any).localStorage) {
+      return (window as any).localStorage as Storage;
+    }
+
+    return null;
+  },
+
+  /**
+   * Determine the intended preauth selection based on the current context.
+   * @param {string} [currentOrgId]
+   * @returns {{selectionType: string, selectionValue: string}}
+   */
+  getIntendedPreauthSelection(currentOrgId?: string): {
+    selectionType: string;
+    selectionValue: string;
+  } {
+    if (this.webex.credentials?.canAuthorize) {
+      if (currentOrgId) {
+        return {selectionType: 'orgId', selectionValue: currentOrgId};
+      }
+    }
+
+    const emailConfig = this.webex.config && this.webex.config.email;
+
+    if (typeof emailConfig === 'string' && emailConfig.trim()) {
+      return {
+        selectionType: 'emailhash',
+        selectionValue: sha256(emailConfig.toLowerCase()).toString(),
+      };
+    }
+
+    // fall back to proximity mode when no orgId or email available
+    return {selectionType: 'mode', selectionValue: 'DEFAULT_BY_PROXIMITY'};
+  },
+
   /**
    * Get a service url from the current services list by name
    * from the associated instance catalog.
@@ -110,6 +176,7 @@ const Services = WebexPlugin.extend({
    * @returns {Array<ServiceHost>} - An array of `ServiceHost` objects.
    */
   getMobiusClusters(): Array<ServiceHost> {
+    this.logger.info('services: fetching mobius clusters');
     const clusters: Array<ServiceHost> = [];
     const services: Array<Service> = this._services || [];
 
@@ -153,6 +220,27 @@ const Services = WebexPlugin.extend({
       });
     });
   },
+
+  /**
+   * Checks if the current environment is an integration (INT) environment
+   * by examining the u2c discovery URL from webex config.
+   * INT environments use discovery URLs containing 'intb' (e.g., u2c-intb.ciscospark.com).
+   * @returns {boolean} True if INT environment, false otherwise
+   */
+  isIntegrationEnvironment(): boolean {
+    try {
+      const u2cUrl = this.webex?.config?.services?.discovery?.u2c || '';
+      const isInt = u2cUrl.includes('intb');
+
+      this.logger.info(`services: isIntegrationEnvironment: ${isInt}`);
+
+      return isInt;
+    } catch (error) {
+      this.logger.error('services: failed to determine integration environment', error);
+
+      return false;
+    }
+  },
   /**
    * saves all the services from the pre and post catalog service
    * @param {ActiveServices} activeServices
@@ -249,6 +337,18 @@ const Services = WebexPlugin.extend({
           serviceHostMap?.services,
           serviceHostMap?.timestamp
         );
+        // Build selection metadata for caching discrimination (preauth/signin)
+        let selectionMeta: SelectionMeta | undefined;
+        if (serviceGroup === 'preauth' || serviceGroup === 'signin') {
+          const key = formattedQuery && Object.keys(formattedQuery || {})[0];
+          if (key) {
+            selectionMeta = {
+              selectionType: key,
+              selectionValue: formattedQuery[key],
+            };
+          }
+        }
+        this._cacheCatalog(serviceGroup, serviceHostMap, selectionMeta);
         this.updateCredentialsConfig();
         catalog.status[serviceGroup].collecting = false;
       })
@@ -934,6 +1034,190 @@ const Services = WebexPlugin.extend({
     return url.replace(data.defaultUrl, data.priorityUrl);
   },
 
+  /**
+   * @private
+   * Cache the catalog in the bounded storage.
+   * @param {ServiceGroup} serviceGroup - preauth, signin, postauth
+   * @param {ServiceHostmap} hostMap - The hostmap to cache
+   * @param {object} [meta] - Optional selection metadata for cache discrimination
+   * @returns {Promise<void>}
+   */
+  async _cacheCatalog(
+    serviceGroup: ServiceGroup,
+    hostMap: ServiceHostmap,
+    meta?: SelectionMeta
+  ): Promise<void> {
+    let current: {orgId?: string; env?: {fedramp?: boolean; u2cDiscoveryUrl?: string}} = {};
+    let orgId: string | undefined;
+    try {
+      // Respect calling.cacheU2C toggle; if disabled, skip writing cache
+      if (!this.webex.config?.calling?.cacheU2C) {
+        this.logger.info(`services: skipping cache write for ${serviceGroup} as per the config`);
+
+        return;
+      }
+
+      try {
+        const ls = this._getLocalStorageSafe();
+        const cachedJson = ls ? ls.getItem(CATALOG_CACHE_KEY_V2) : null;
+        current = cachedJson ? JSON.parse(cachedJson) : {};
+      } catch {
+        current = {};
+      }
+
+      try {
+        const {credentials} = this.webex;
+        orgId = credentials.getOrgId();
+      } catch {
+        orgId = current.orgId;
+      }
+
+      // Capture environment fingerprint to invalidate cache across env changes
+      let {env} = current;
+      const fedramp = !!this.webex?.config?.fedramp;
+      const u2cDiscoveryUrl = this.webex?.config?.services?.discovery?.u2c;
+      env = {fedramp, u2cDiscoveryUrl};
+
+      const updated = {
+        ...current,
+        orgId: orgId || current.orgId,
+        env: env || current.env,
+        // When selection meta is provided, store as an object; otherwise keep legacy shape
+        [serviceGroup]: meta ? {hostMap, meta} : hostMap,
+        cachedAt: Date.now(),
+      };
+
+      const ls = this._getLocalStorageSafe();
+      if (ls) {
+        ls.setItem(CATALOG_CACHE_KEY_V2, JSON.stringify(updated));
+      }
+    } catch (e) {
+      this.logger.warn('services: error caching catalog', e);
+    }
+  },
+
+  /**
+   * @private
+   * Load the catalog from cache and hydrate the in-memory ServiceCatalog.
+   * @returns {Promise<boolean>} true if cache was loaded, false otherwise
+   */
+  async _loadCatalogFromCache(): Promise<boolean> {
+    let currentOrgId: string | undefined;
+    try {
+      // Respect calling.cacheU2C toggle; if disabled, skip using cache
+      if (!this.webex.config?.calling?.cacheU2C) {
+        this.logger.info('services: skipping cache warm-up as per the cache config');
+
+        return false;
+      }
+
+      const ls = this._getLocalStorageSafe();
+      if (!ls) {
+        this.logger.info('services: skipping cache warm-up as no localStorage is available');
+
+        return false;
+      }
+      const cachedJson = ls.getItem(CATALOG_CACHE_KEY_V2);
+      const cached = cachedJson ? JSON.parse(cachedJson) : undefined;
+      if (!cached) {
+        return false;
+      }
+
+      // TTL enforcement
+      const cachedAt = Number(cached.cachedAt) || 0;
+      if (!cachedAt || Date.now() - cachedAt > CATALOG_TTL_MS) {
+        this.clearCatalogCache();
+
+        return false;
+      }
+
+      // If authorized, ensure cached org matches
+      try {
+        if (this.webex.credentials?.canAuthorize) {
+          const {credentials} = this.webex;
+          currentOrgId = credentials.getOrgId();
+          if (cached.orgId && cached.orgId !== currentOrgId) {
+            return false;
+          }
+        }
+      } catch (e) {
+        this.logger.warn('services: error checking orgId', e);
+      }
+
+      // Ensure cached environment matches current environment
+
+      const fedramp = !!this.webex.config?.fedramp;
+      const u2cDiscoveryUrl = this.webex.config?.services?.discovery?.u2c;
+      const currentEnv = {fedramp, u2cDiscoveryUrl};
+      if (cached.env) {
+        const sameEnv =
+          cached.env.fedramp === currentEnv.fedramp &&
+          cached.env.u2cDiscoveryUrl === currentEnv.u2cDiscoveryUrl;
+        if (!sameEnv) {
+          return false;
+        }
+      }
+
+      const catalog = this._getCatalog();
+      const groups: Array<ServiceGroup> = ['preauth', 'signin', 'postauth'];
+
+      groups.forEach((serviceGroup) => {
+        const cachedGroup = cached[serviceGroup];
+        if (!cachedGroup) {
+          return;
+        }
+
+        // Support legacy (hostMap) and new ({hostMap, meta}) shapes
+        const hostMap: ServiceHostmap =
+          cachedGroup && cachedGroup.hostMap ? cachedGroup.hostMap : cachedGroup;
+        const meta: SelectionMeta | undefined = cachedGroup?.meta;
+
+        if (serviceGroup === 'preauth' && meta) {
+          // For proximity-based selection, always fetch fresh to respect IP/region changes
+          if (meta.selectionType === 'mode') {
+            return;
+          }
+
+          const intended = this.getIntendedPreauthSelection(currentOrgId);
+          const matches =
+            intended &&
+            intended.selectionType === meta.selectionType &&
+            intended.selectionValue === meta.selectionValue;
+          if (!matches) {
+            return;
+          }
+        }
+
+        if (hostMap) {
+          catalog.updateServiceGroups(serviceGroup, hostMap?.services, hostMap?.timestamp);
+        }
+      });
+
+      this.updateCredentialsConfig();
+
+      return true;
+    } catch (e) {
+      return false;
+    }
+  },
+
+  /**
+   * Clear the catalog cache from the bounded storage (v2).
+   * @returns {Promise<void>}
+   */
+  clearCatalogCache(): Promise<void> {
+    try {
+      const ls = this._getLocalStorageSafe();
+      if (ls) {
+        ls.removeItem(CATALOG_CACHE_KEY_V2);
+      }
+    } catch (e) {
+      this.logger.warn('services: error clearing catalog cache', e);
+    }
+
+    return Promise.resolve();
+  },
+
   /**
    * @private
    * Simplified method wrapper for sending a request to get
@@ -1075,6 +1359,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
    *
@@ -1086,14 +1393,48 @@ 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', () => {
+    this.listenToOnce(this.webex, 'ready', async () => {
+      const warmed = await this._loadCatalogFromCache();
+      if (warmed) {
+        catalog.isReady = true;
+
+        return;
+      }
       const {supertoken} = this.webex.credentials;
       // Validate if the supertoken exists.
       if (supertoken && supertoken.access_token) {
@@ -1119,6 +1460,80 @@ 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 the app on a permanent spinner.
+      const timeout = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new Error(`services: init timed out after ${SERVICES_INIT_TIMEOUT_MS}ms`)),
+          SERVICES_INIT_TIMEOUT_MS
+        );
+      });
+
+      // Validate if the supertoken exists.
+      if (supertoken && supertoken.access_token) {
+        Promise.race([this.initServiceCatalogs(), timeout])
+          .then(() => {
+            catalog.isReady = true;
+          })
+          .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), timeout])
+          .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) {
+            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/types.ts

@@ -2,6 +2,11 @@ type ServiceName = string;
 type ClusterId = string;
 export type ServiceGroup = 'discovery' | 'override' | 'preauth' | 'postauth' | 'signin';
 
+export type SelectionMeta = {
+  selectionType: string;
+  selectionValue: string;
+};
+
 export type ServiceHost = {
   host: string;
   ttl: number;

package/test/integration/spec/services/service-catalog.js

@@ -23,13 +23,12 @@ describe('webex-core', () => {
         .then(
           ([user]) =>
             new Promise((resolve) => {
-              setTimeout(() => {
-                webexUser = user;
-                webex = new WebexCore({credentials: user.token});
-                services = webex.internal.services;
-                catalog = services._getCatalog();
-                resolve();
-              }, 1000);
+              webexUser = user;
+              webex = new WebexCore({credentials: user.token});
+              services = webex.internal.services;
+              catalog = services._getCatalog();
+              // Wait for webex ready event before registering device to ensure newMetrics.callDiagnosticMetrics is initialized
+              webex.once('ready', resolve);
             })
         )
         .then(() => webex.internal.device.register())
@@ -510,13 +509,19 @@ describe('webex-core', () => {
       );
 
       it('resolves to an authed u2c hostmap when no params specified', () => {
-        assert.typeOf(fullRemoteHM, 'array');
-        assert.isAbove(fullRemoteHM.length, 0);
+        assert.typeOf(fullRemoteHM, 'object');
+        assert.property(fullRemoteHM, 'serviceLinks');
+        assert.property(fullRemoteHM, 'hostCatalog');
+        assert.equal(fullRemoteHM.format, 'hostmap');
+        assert.isAbove(Object.keys(fullRemoteHM.serviceLinks).length, 0);
       });
 
       it('resolves to a limited u2c hostmap when params specified', () => {
-        assert.typeOf(limitedRemoteHM, 'array');
-        assert.isAbove(limitedRemoteHM.length, 0);
+        assert.typeOf(limitedRemoteHM, 'object');
+        assert.property(limitedRemoteHM, 'serviceLinks');
+        assert.property(limitedRemoteHM, 'hostCatalog');
+        assert.equal(limitedRemoteHM.format, 'hostmap');
+        assert.isAbove(Object.keys(limitedRemoteHM.serviceLinks).length, 0);
       });
 
       it('rejects if the params provided are invalid', () =>

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

@@ -404,10 +404,13 @@ describe('webex-core', () => {
         assert.isTrue(catalog.isReady);
       });
 
-      it('should call services#initServiceCatalogs() on webex ready', () => {
+      it('should call services#initServiceCatalogs() on webex ready', async () => {
+        services._loadCatalogFromCache = sinon.stub().resolves(false);
         services.initServiceCatalogs = sinon.stub().resolves();
         services.initialize();
         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);
       });
@@ -427,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()', () => {
@@ -697,7 +733,11 @@ describe('webex-core', () => {
 
       it('updates query.email to be emailhash-ed using SHA256', (done) => {
         catalog.updateServiceUrls = sinon.stub().returns({}); // returns `this`
-        services._fetchNewServiceHostmap = sinon.stub().resolves();
+        services._fetchNewServiceHostmap = sinon.stub().resolves({
+          serviceLinks: {},
+          hostCatalog: {},
+          format: 'hostmap',
+        });
 
         services
           .updateServices({
@@ -827,9 +867,12 @@ describe('webex-core', () => {
 
       const getActivationRequest = (requestStub, useUserOnboarding = false) => {
         const expectedService = useUserOnboarding ? 'user-onboarding' : 'license';
-        const expectedResource = useUserOnboarding ? 'api/v1/users/activations' : 'users/activations';
+        const expectedResource = useUserOnboarding
+          ? 'api/v1/users/activations'
+          : 'users/activations';
         const requests = requestStub.args.filter(
-          ([request]) => request.service === expectedService && request.resource === expectedResource
+          ([request]) =>
+            request.service === expectedService && request.resource === expectedResource
         );
 
         assert.strictEqual(requests.length, 1);
@@ -908,7 +951,7 @@ describe('webex-core', () => {
             assert.equal(Object.keys(unauthServices.list(false, 'postauth')).length, 0);
           }));
 
-      it.skip('validates new user with activationOptions suppressEmail true', () =>
+      it('validates new user with activationOptions suppressEmail true', () =>
         unauthServices
           .validateUser({
             email: `Collabctg+webex-js-sdk-${uuid.v4()}@gmail.com`,
@@ -1254,13 +1297,19 @@ describe('webex-core', () => {
       );
 
       it('resolves to an authed u2c hostmap when no params specified', () => {
-        assert.typeOf(fullRemoteHM, 'array');
-        assert.isAbove(fullRemoteHM.length, 0);
+        assert.typeOf(fullRemoteHM, 'object');
+        assert.property(fullRemoteHM, 'serviceLinks');
+        assert.property(fullRemoteHM, 'hostCatalog');
+        assert.equal(fullRemoteHM.format, 'hostmap');
+        assert.isAbove(Object.keys(fullRemoteHM.serviceLinks).length, 0);
       });
 
       it('resolves to a limited u2c hostmap when params specified', () => {
-        assert.typeOf(limitedRemoteHM, 'array');
-        assert.isAbove(limitedRemoteHM.length, 0);
+        assert.typeOf(limitedRemoteHM, 'object');
+        assert.property(limitedRemoteHM, 'serviceLinks');
+        assert.property(limitedRemoteHM, 'hostCatalog');
+        assert.equal(limitedRemoteHM.format, 'hostmap');
+        assert.isAbove(Object.keys(limitedRemoteHM.serviceLinks).length, 0);
       });
 
       it('rejects if the params provided are invalid', () =>