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

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,20 @@ const Services = WebexPlugin.extend({
     initFailed: ['boolean', false, false],
   },
 
+  session: {
+    /**
+     * Becomes `true` once services initialization has completed.
+     * This blocks `webex.ready` until services are initialized.
+     * @instance
+     * @memberof Services
+     * @type {boolean}
+     */
+    ready: {
+      default: false,
+      type: 'boolean',
+    },
+  },
+
   _catalogs: new WeakMap(),
 
   _activeServices: {},
@@ -56,6 +80,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 +174,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 +218,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 +335,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 +1032,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 +1357,30 @@ 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;
+    this.trigger('services:initialized');
+  },
+
   /**
    * Initializer
    *
@@ -1091,13 +1397,32 @@ const Services = WebexPlugin.extend({
       this.initConfig();
     });
 
-    // wait for webex instance to be ready before attempting
-    // to update the service catalogs
-    this.listenToOnce(this.webex, 'ready', () => {
+    // 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.
+    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) {
-        this.initServiceCatalogs()
+        Promise.race([this.initServiceCatalogs(), timeout])
           .then(() => {
             catalog.isReady = true;
           })
@@ -1106,15 +1431,33 @@ const Services = WebexPlugin.extend({
             this.logger.error(
               `services: failed to init initial services when credentials available, ${error?.message}`
             );
-          });
+          })
+          .finally(() => this._finalizeReady());
       } 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}`
-          );
+        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());
+        // Listen for when credentials become available to fetch the full catalog.
+        // This handles fresh login where 'loaded' fires before OAuth completes.
+        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}`
+                );
+              });
+          }
         });
       }
     });

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,12 +404,26 @@ describe('webex-core', () => {
         assert.isTrue(catalog.isReady);
       });
 
-      it('should call services#initServiceCatalogs() on webex ready', () => {
+      it('should call services#initServiceCatalogs() on webex loaded', async () => {
         services.initServiceCatalogs = sinon.stub().resolves();
         services.initialize();
-        webex.trigger('ready');
+        webex.trigger('loaded');
+        // Wait for the async callback to execute
+        await new Promise((resolve) => setTimeout(resolve, 10));
         assert.called(services.initServiceCatalogs);
-        assert.isTrue(catalog.isReady);
+      });
+
+      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);
       });
 
       it('should collect different catalogs based on OrgId region', () =>
@@ -697,7 +711,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 +845,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 +929,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 +1275,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-v2/services-v2.js

@@ -23,7 +23,7 @@ import {
   formattedServiceHostmapEntryConv,
   formattedServiceHostmapEntryMercury,
   formattedServiceHostmapEntryTest,
-  serviceHostmapV2
+  serviceHostmapV2,
 } from '../../../fixtures/host-catalog-v2';
 
 // /* eslint-disable no-underscore-dangle */
@@ -316,12 +316,26 @@ describe('webex-core', () => {
         assert.isTrue(catalog.isReady);
       });
 
-      it('should call services#initServiceCatalogs() on webex ready', () => {
+      it('should call services#initServiceCatalogs() on webex loaded', async () => {
         services.initServiceCatalogs = sinon.stub().resolves();
         services.initialize();
-        webex.trigger('ready');
+        webex.trigger('loaded');
+        // Wait for the async callback to execute
+        await new Promise((resolve) => setTimeout(resolve, 10));
         assert.called(services.initServiceCatalogs);
-        assert.isTrue(catalog.isReady);
+      });
+
+      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);
       });
 
       it('should collect different catalogs based on OrgId region', () =>
@@ -413,7 +427,11 @@ describe('webex-core', () => {
             .initServiceCatalogs(true)
             // services#updateServices() gets called once by the limited catalog
             // retrieval and should get called again when authorized.
-            .then(() => assert.calledTwice(services.updateServices) && assert.calledWith(services.updateServices, sinon.match({forceRefresh: true})))
+            .then(
+              () =>
+                assert.calledTwice(services.updateServices) &&
+                assert.calledWith(services.updateServices, sinon.match({forceRefresh: true}))
+            )
         );
       });
     });
@@ -750,9 +768,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);
@@ -825,7 +846,7 @@ describe('webex-core', () => {
             assert.equal(r.user.verificationEmailTriggered, true);
           }));
 
-      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`,