feat(services): U2C cache logic

docs/samples/calling/app.js

@@ -223,6 +223,10 @@ async function initCalling(e) {
       logger: {
         level: 'debug', // set the desired log level
       },
+      calling: {
+        // Enable U2C catalog caching for calling sample app
+        cacheU2C: true,
+      },
       meetings: {
         reconnection: {
           enabled: true,

packages/@webex/internal-plugin-device/src/device.js

@@ -667,6 +667,8 @@ const Device = WebexPlugin.extend({
     const {services} = this.webex.internal;
 
     // Wait for the postauth catalog to populate.
+    console.log('pkesari_canRegister invoking waitForCatalog for postauth');
+
     return services.waitForCatalog('postauth', this.config.canRegisterWaitDuration).then(() =>
       // Validate that the service exists after waiting for the catalog.
       services.get('wdm')

packages/@webex/webex-core/src/config.js

@@ -83,6 +83,16 @@ export default {
   metrics: {
     type: ['behavioral', 'operational'],
   },
+  /**
+   * Calling-specific configuration.
+   */
+  calling: {
+    /**
+     * Controls whether U2C service catalogs should be cached and warmed from cache.
+     * When false, the services layer will skip reading and writing the U2C cache.
+     */
+    cacheU2C: false,
+  },
   payloadTransformer: {
     predicates: [],
     transforms: [],

packages/@webex/webex-core/src/lib/services-v2/services-v2.ts

@@ -28,6 +28,9 @@ 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
+
 /* eslint-disable no-underscore-dangle */
 /**
  * @class
@@ -110,6 +113,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 || [];
 
@@ -249,6 +253,22 @@ const Services = WebexPlugin.extend({
           serviceHostMap?.services,
           serviceHostMap?.timestamp
         );
+        // Build selection metadata for caching discrimination (preauth/signin)
+        let selectionMeta: {selectionType: string; selectionValue: string} | undefined;
+        if (serviceGroup === 'preauth' || serviceGroup === 'signin') {
+          try {
+            const key = formattedQuery && Object.keys(formattedQuery || {})[0];
+            if (key) {
+              selectionMeta = {
+                selectionType: key,
+                selectionValue: formattedQuery[key],
+              };
+            }
+          } catch {
+            this.logger.warn('services: error building selection meta');
+          }
+        }
+        this._cacheCatalog(serviceGroup, serviceHostMap, selectionMeta);
         this.updateCredentialsConfig();
         catalog.status[serviceGroup].collecting = false;
       })
@@ -934,6 +954,216 @@ 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?: {selectionType: string; selectionValue: string}
+  ): 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 && this.webex.config.calling.cacheU2C === false) {
+        return;
+      }
+
+      try {
+        const raw =
+          typeof window !== 'undefined' && (window as any).localStorage
+            ? (window as any).localStorage.getItem(CATALOG_CACHE_KEY_V2)
+            : null;
+        current = raw ? JSON.parse(raw) : {};
+      } 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: {fedramp?: boolean; u2cDiscoveryUrl?: string} | undefined;
+      try {
+        const fedramp = !!this.webex.config?.fedramp;
+        const u2cDiscoveryUrl = this.webex.config?.services?.discovery?.u2c;
+        env = {fedramp, u2cDiscoveryUrl};
+      } catch {
+        env = current.env;
+      }
+
+      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(),
+      };
+
+      if (typeof window !== 'undefined' && (window as any).localStorage) {
+        (window as any).localStorage.setItem(CATALOG_CACHE_KEY_V2, JSON.stringify(updated));
+      }
+    } catch {
+      this.logger.warn('services: error caching catalog');
+    }
+  },
+
+  /**
+   * @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 && this.webex.config.calling.cacheU2C === false) {
+        return false;
+      }
+
+      if (typeof window === 'undefined' || !(window as any).localStorage) {
+        return false;
+      }
+      const raw = (window as any).localStorage.getItem(CATALOG_CACHE_KEY_V2);
+      const cached = raw ? JSON.parse(raw) : undefined;
+      if (!cached) {
+        return false;
+      }
+
+      // TTL enforcement
+      const cachedAt = Number(cached.cachedAt) || 0;
+      if (!cachedAt || Date.now() - cachedAt > CATALOG_TTL_MS) {
+        try {
+          this.clearCatalogCache();
+        } catch {
+          this.logger.warn('services: error clearing catalog cache');
+        }
+
+        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 {
+        this.logger.warn('services: error checking orgId');
+      }
+
+      // Ensure cached environment matches current environment
+      try {
+        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;
+          }
+        }
+      } catch (e) {
+        this.logger.warn('services: error checking environment', e);
+      }
+
+      const catalog = this._getCatalog();
+      const groups: Array<ServiceGroup> = ['preauth', 'signin', 'postauth'];
+
+      // Helper: compute intended preauth selection based on current context
+      const getIntendedPreauthSelection = () => {
+        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'};
+      };
+
+      groups.forEach((g) => {
+        const cachedGroup = cached[g];
+        if (!cachedGroup) {
+          return;
+        }
+
+        // Support legacy (hostMap) and new ({hostMap, meta}) shapes
+        const hostMap: ServiceHostmap =
+          cachedGroup && cachedGroup.hostMap ? cachedGroup.hostMap : cachedGroup;
+        const meta: {selectionType: string; selectionValue: string} | undefined =
+          cachedGroup && cachedGroup.meta ? cachedGroup.meta : undefined;
+
+        if (g === 'preauth' && meta) {
+          // For proximity-based selection, always fetch fresh to respect IP/region changes
+          if (meta.selectionType === 'mode') {
+            return;
+          }
+
+          const intended = getIntendedPreauthSelection();
+          const matches =
+            intended &&
+            intended.selectionType === meta.selectionType &&
+            intended.selectionValue === meta.selectionValue;
+          if (!matches) {
+            return;
+          }
+        }
+
+        if (hostMap) {
+          catalog.updateServiceGroups(g, hostMap?.services, hostMap?.timestamp);
+        }
+      });
+
+      this.updateCredentialsConfig();
+
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Clear the catalog cache from the bounded storage (v2).
+   * @returns {Promise<void>}
+   */
+  clearCatalogCache(): Promise<void> {
+    try {
+      if (typeof window !== 'undefined' && (window as any).localStorage) {
+        (window as any).localStorage.removeItem(CATALOG_CACHE_KEY_V2);
+      }
+    } catch {
+      this.logger.warn('services: error clearing catalog cache');
+    }
+
+    return Promise.resolve();
+  },
+
   /**
    * @private
    * Simplified method wrapper for sending a request to get
@@ -1093,7 +1323,14 @@ const Services = WebexPlugin.extend({
 
     // 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) {