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

package/src/lib/services/services.js

@@ -20,6 +20,14 @@ export const DEFAULT_CLUSTER_SERVICE = 'identityLookup';
 const CLUSTER_SERVICE = process.env.WEBEX_CONVERSATION_CLUSTER_SERVICE || DEFAULT_CLUSTER_SERVICE;
 const DEFAULT_CLUSTER_IDENTIFIER =
   process.env.WEBEX_CONVERSATION_DEFAULT_CLUSTER || `${DEFAULT_CLUSTER}:${CLUSTER_SERVICE}`;
+const CATALOG_CACHE_KEY_V1 = 'services.v1.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 */
 /**
@@ -55,6 +63,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,
@@ -96,6 +120,49 @@ const Services = WebexPlugin.extend({
     return this._catalogs.get(this.webex);
   },
 
+  /**
+   * Safely access localStorage if available; returns the Storage or null.
+   * @returns {Storage|null}
+   */
+  _getLocalStorageSafe() {
+    if (typeof window !== 'undefined' && window.localStorage) {
+      return window.localStorage;
+    }
+
+    return null;
+  },
+
+  /**
+   * Determine the intended preauth selection based on the current context.
+   * @param {string|undefined} currentOrgId
+   * @returns {{selectionType: string, selectionValue: string}}
+   */
+  getIntendedPreauthSelection(currentOrgId) {
+    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.
@@ -165,9 +232,10 @@ const Services = WebexPlugin.extend({
 
   /**
    * Get all Mobius cluster host entries from the legacy host catalog.
-   * @returns {Array<Object>}
+   * @returns {Array<{host: string, id: string, ttl: number, priority: number}>}
    */
   getMobiusClusters() {
+    this.logger.info('services: fetching mobius clusters');
     const clusters = [];
     const hostCatalog = this._hostCatalog || {};
 
@@ -197,6 +265,28 @@ const Services = WebexPlugin.extend({
 
     return !!hostCatalog[host]?.length;
   },
+
+  /**
+   * 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() {
+    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;
+    }
+  },
+
   /**
    * Merge provided active cluster mappings into current state.
    * @param {Record<string,string>} activeServices
@@ -237,7 +327,7 @@ const Services = WebexPlugin.extend({
    * @param {string} [param.token] - used for signin catalog
    * @returns {Promise<object>}
    */
-  updateServices({from, query, token, forceRefresh} = {}) {
+  async updateServices({from, query, token, forceRefresh} = {}) {
     const catalog = this._getCatalog();
     let formattedQuery;
     let serviceGroup;
@@ -291,7 +381,20 @@ const Services = WebexPlugin.extend({
       forceRefresh,
     })
       .then((serviceHostMap) => {
-        catalog.updateServiceUrls(serviceGroup, serviceHostMap);
+        const formattedServiceHostMap = this._formatReceivedHostmap(serviceHostMap);
+        // Build selection metadata for caching discrimination
+        let selectionMeta;
+        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);
+        catalog.updateServiceUrls(serviceGroup, formattedServiceHostMap);
         this.updateCredentialsConfig();
         catalog.status[serviceGroup].collecting = false;
       })
@@ -1008,7 +1111,197 @@ const Services = WebexPlugin.extend({
 
     return this.webex.internal.newMetrics.callDiagnosticLatencies
       .measureLatency(() => this.request(requestObject), 'internal.get.u2c.time')
-      .then(({body}) => this._formatReceivedHostmap(body));
+      .then(({body}) => body);
+  },
+
+  /**
+   * Cache the catalog in the bounded storage.
+   * @param {string} serviceGroup - preauth, signin, postauth
+   * @param {object} hostMap - The hostmap to cache
+   * @param {object} [meta] - Optional selection metadata used to validate cache reuse
+   * @returns {Promise<void>}
+   *
+   */
+  async _cacheCatalog(serviceGroup, hostMap, meta) {
+    let current = {};
+    let orgId;
+    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;
+      }
+
+      // Persist to localStorage to survive browser refresh
+      try {
+        const ls = this._getLocalStorageSafe();
+        const cachedJson = ls ? ls.getItem(CATALOG_CACHE_KEY_V1) : null;
+        current = cachedJson ? JSON.parse(cachedJson) : {};
+      } catch (e) {
+        current = {};
+      }
+
+      try {
+        const {credentials} = this.webex;
+        orgId = credentials.getOrgId();
+      } catch (e) {
+        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_V1, JSON.stringify(updated));
+      }
+    } catch (error) {
+      this.logger.warn('services: error caching catalog', error);
+    }
+  },
+
+  /**
+   * Load the catalog from cache and hydrate the in-memory ServiceCatalog.
+   * @returns {Promise<boolean>} true if cache was loaded, false otherwise
+   */
+  async _loadCatalogFromCache() {
+    let currentOrgId;
+    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_V1);
+      const cached = cachedJson ? JSON.parse(cachedJson) : undefined;
+      if (!cached) {
+        return false;
+      }
+      // TTL enforcement: clear if older than 24 hours
+      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) {
+          this.logger.info('services: skipping cache warm due to environment mismatch');
+
+          return false;
+        }
+      }
+
+      const catalog = this._getCatalog();
+
+      // Apply any cached groups (with preauth selection validation if available)
+      const groups = ['preauth', 'signin', 'postauth'];
+      groups.forEach((serviceGroup) => {
+        const cachedGroup = cached[serviceGroup];
+        if (!cachedGroup) {
+          return;
+        }
+
+        // Support legacy (hostMap) and new ({hostMap, meta}) shapes
+        const hostMap = cachedGroup && cachedGroup.hostMap ? cachedGroup.hostMap : cachedGroup;
+        const meta = cachedGroup?.meta;
+
+        if (serviceGroup === 'preauth' && meta) {
+          // For proximity-based selection, always fetch fresh to respect IP/region changes
+          if (meta.selectionType === 'mode') {
+            this.logger.info('services: skipping preauth cache warm for proximity mode');
+
+            return;
+          }
+
+          const intended = this.getIntendedPreauthSelection(currentOrgId);
+          const matches =
+            intended &&
+            intended.selectionType === meta.selectionType &&
+            intended.selectionValue === meta.selectionValue;
+
+          if (!matches) {
+            this.logger.info('services: skipping preauth cache warm due to selection mismatch');
+
+            return;
+          }
+        }
+
+        if (hostMap) {
+          const formatted = this._formatReceivedHostmap(hostMap);
+          catalog.updateServiceUrls(serviceGroup, formatted);
+        }
+      });
+
+      // Align credentials against warmed catalog
+      this.updateCredentialsConfig();
+
+      return true;
+    } catch (e) {
+      this.logger.warn('services: error loading catalog from cache', e);
+
+      return false;
+    }
+  },
+
+  /**
+   * Clear the catalog cache from the bounded storage.
+   * @returns {Promise<void>}
+   */
+  clearCatalogCache() {
+    try {
+      const ls = this._getLocalStorageSafe();
+      if (ls) {
+        ls.removeItem(CATALOG_CACHE_KEY_V1);
+      }
+    } catch (e) {
+      this.logger.warn('services: error clearing catalog cache', e);
+    }
+
+    return Promise.resolve();
   },
 
   /**
@@ -1088,6 +1381,7 @@ const Services = WebexPlugin.extend({
           // 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');
@@ -1100,6 +1394,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
    *
@@ -1116,14 +1433,50 @@ 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.listenToOnce(this.webex, 'ready', () => {
+    // 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;
+
+        return; // skip initServiceCatalogs() on reload when cache exists
+      }
       const {supertoken} = this.webex.credentials;
       // Validate if the supertoken exists.
       if (supertoken && supertoken.access_token) {
@@ -1149,6 +1502,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) {
+    // 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 the app on a permanent spinner.
+      const timeout = new Promise((_, 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 */