@webex/internal-plugin-llm 3.11.0 → 3.12.0-llmrefactor.1

package/src/llm-plugin.ts

@@ -0,0 +1,115 @@
+/* eslint-disable require-jsdoc */
+import {WebexPlugin} from '@webex/webex-core';
+import LLMChannel, {config} from './llm';
+import {DATA_CHANNEL_WITH_JWT_TOKEN} from './constants';
+
+/**
+ * LLMPlugin — registered as `webex.internal.llm`.
+ *
+ * Factory for creating LLMChannel instances. Each Meeting creates and owns
+ * its own LLMChannel(s), allowing multiple independent connections without
+ * the need for session IDs or ownership tracking.
+ *
+ * This is a breaking API change from the previous design where the plugin
+ * maintained a Map of sessions and exposed session-keyed methods.
+ *
+ * Old usage (no longer supported):
+ *   webex.internal.llm.isConnected()
+ *   webex.internal.llm.registerAndConnect(url, dcUrl, token, sessionId)
+ *
+ * New usage:
+ *   const llm = webex.internal.llm.createChannel();
+ *   await llm.registerAndConnect(url, dcUrl, token);
+ *   llm.isConnected();
+ *   // When done:
+ *   await llm.disconnect();
+ */
+export class LLMPlugin extends (WebexPlugin as any) {
+  namespace = 'llm';
+
+  /**
+   * Registry of active LLM channels for interceptor lookup.
+   * Channels are registered when created and unregistered on disconnect.
+   */
+  private channels = new Set<LLMChannel>();
+
+  /**
+   * Creates a new LLMChannel instance. The caller owns the channel and is
+   * responsible for connecting, disconnecting, and cleaning it up.
+   *
+   * @example
+   * const llm = webex.internal.llm.createChannel();
+   * llm.setRefreshHandler(() => meeting.refreshDataChannelToken());
+   * await llm.registerAndConnect(locusUrl, datachannelUrl, token);
+   *
+   * // Subscribe to events directly on the channel
+   * llm.on('event:relay.event', handler);
+   * llm.on('online', onlineHandler);
+   *
+   * // When done
+   * await llm.disconnect();
+   *
+   * @returns {LLMChannel} A new LLM channel instance
+   */
+  public createChannel(): LLMChannel {
+    // @ts-ignore — WebexPlugin children require {parent: this.webex}
+    const channel = new LLMChannel({parent: this.webex});
+
+    this.channels.add(channel);
+    channel.on('disconnected', () => this.channels.delete(channel));
+
+    return channel;
+  }
+
+  /**
+   * Returns true if the data channel token feature flag is enabled.
+   * This is a global check, not per-connection.
+   * @returns {Promise<boolean>}
+   */
+  public isDataChannelTokenEnabled(): Promise<boolean> {
+    // @ts-ignore
+    return this.webex.internal.feature.getFeature('developer', DATA_CHANNEL_WITH_JWT_TOKEN);
+  }
+
+  /**
+   * Find a channel by its datachannel URL. Used by the interceptor to
+   * route token refresh requests to the correct channel.
+   * @param {string} url - The request URL to match
+   * @returns {LLMChannel | undefined}
+   */
+  public getChannelByDatachannelUrl(url: string): LLMChannel | undefined {
+    for (const channel of this.channels) {
+      const datachannelUrl = channel.getDatachannelUrl();
+
+      if (datachannelUrl && LLMChannel.matchesDatachannelRequestUrl(url, datachannelUrl)) {
+        return channel;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get all active channels. Useful for diagnostics/debugging.
+   * @returns {Set<LLMChannel>}
+   */
+  public getAllChannels(): Set<LLMChannel> {
+    return new Set(this.channels);
+  }
+
+  /**
+   * Disconnect all active channels. Useful for cleanup on logout.
+   * @param {object} [options] - Disconnect options
+   * @param {number} [options.code] - WebSocket close code
+   * @param {string} [options.reason] - WebSocket close reason
+   * @returns {Promise<void>}
+   */
+  public async disconnectAllChannels(options?: {code: number; reason: string}): Promise<void> {
+    const promises = Array.from(this.channels).map((channel) => channel.disconnect(options));
+
+    await Promise.all(promises);
+  }
+}
+
+export {config};
+export default LLMPlugin;

package/src/llm.ts

@@ -1,10 +1,13 @@
 /* eslint-disable consistent-return */
-
 import Mercury from '@webex/internal-plugin-mercury';
 
-import {LLM} from './constants';
-// eslint-disable-next-line no-unused-vars
-import {ILLMChannel} from './llm.types';
+import {
+  LLM,
+  DATA_CHANNEL_WITH_JWT_TOKEN,
+  AWARE_DATA_CHANNEL,
+  SUBSCRIPTION_AWARE_SUBCHANNELS_PARAM,
+} from './constants';
+import {ILLMChannel, DataChannelTokenType, RegisterAndConnectTiming} from './llm.types';
 
 export const config = {
   llm: {
@@ -38,59 +41,128 @@ export const config = {
 };
 
 /**
- * LLMChannel to provide socket connections
+ * LLMChannel — a single WebSocket connection to the LLM data channel.
+ *
+ * Created via `webex.internal.llm.createChannel()`. The caller owns the
+ * channel and is responsible for its lifecycle (connect, disconnect, cleanup).
+ * Multiple LLMChannels can exist simultaneously for different meetings.
  */
 export default class LLMChannel extends (Mercury as any) implements ILLMChannel {
   namespace = LLM;
 
-  /**
-   * If the LLM plugin has been registered and listening
-   * @instance
-   * @type {Boolean}
-   * @public
-   */
-
   private webSocketUrl?: string;
-
   private binding?: string;
-
   private locusUrl?: string;
-
   private datachannelUrl?: string;
+  private datachannelToken?: string;
+  private refreshHandler?: () => Promise<{
+    body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+  }>;
+
+  /** In-flight connection promise for deduplication. */
+  private connectingPromise?: Promise<RegisterAndConnectTiming | void>;
+
+  /**
+   * Check if a connection is currently in progress.
+   * @returns {boolean} True if connecting
+   */
+  public isConnecting(): boolean {
+    return !!this.connectingPromise;
+  }
 
   /**
    * Register to the websocket
    * @param {string} llmSocketUrl
+   * @param {string} datachannelToken
    * @returns {Promise<void>}
    */
-  private register = (llmSocketUrl: string): Promise<void> =>
-    this.request({
+  private register = async (llmSocketUrl: string, datachannelToken?: string): Promise<void> => {
+    const isDataChannelTokenEnabled = await this.isDataChannelTokenEnabled();
+
+    return this.request({
       method: 'POST',
       url: llmSocketUrl,
       body: {deviceUrl: this.webex.internal.device.url},
+      headers:
+        isDataChannelTokenEnabled && datachannelToken
+          ? {'Data-Channel-Auth-Token': datachannelToken}
+          : {},
     })
       .then((res: {body: {webSocketUrl: string; binding: string}}) => {
         this.webSocketUrl = res.body.webSocketUrl;
         this.binding = res.body.binding;
       })
       .catch((error: any) => {
-        this.logger.error(`Error connecting to websocket: ${error}`);
+        this.logger.error(`Error connecting to websocket for : ${error}`);
         throw error;
       });
+  };
 
   /**
-   * Register and connect to the websocket
+   * Register and connect to the websocket.
+   * Handles deduplication: returns existing promise if connection in progress,
+   * or resolves immediately if already connected to the same URLs.
    * @param {string} locusUrl
    * @param {string} datachannelUrl
-   * @returns {Promise<void>}
+   * @param {string} datachannelToken
+   * @returns {Promise<RegisterAndConnectTiming | void>}
    */
-  public registerAndConnect = (locusUrl: string, datachannelUrl: string): Promise<void> =>
-    this.register(datachannelUrl).then(() => {
-      if (!locusUrl || !datachannelUrl) return undefined;
-      this.locusUrl = locusUrl;
-      this.datachannelUrl = datachannelUrl;
-      this.connect(this.webSocketUrl);
-    });
+  public registerAndConnect = (
+    locusUrl: string,
+    datachannelUrl: string,
+    datachannelToken?: string
+  ): Promise<RegisterAndConnectTiming | void> => {
+    // Deduplicate concurrent calls while a connection is in-flight
+    if (this.connectingPromise) {
+      return this.connectingPromise;
+    }
+
+    // If already connected to the exact same datachannel URL, avoid triggering
+    // a reconnect that would cause the server to replace with 4000 Replaced
+    if (
+      this.isConnected() &&
+      this.datachannelUrl === datachannelUrl &&
+      this.locusUrl === locusUrl
+    ) {
+      return Promise.resolve();
+    }
+
+    this.locusUrl = locusUrl;
+    this.datachannelUrl = datachannelUrl;
+    const registerStart = performance.now();
+
+    this.connectingPromise = this.register(datachannelUrl, datachannelToken)
+      .then(async () => {
+        const clientLLMDatachannelResponseTime = Math.round(performance.now() - registerStart);
+        const isDataChannelTokenEnabled = await this.isDataChannelTokenEnabled();
+
+        const connectUrl =
+          isDataChannelTokenEnabled && this.webSocketUrl
+            ? LLMChannel.buildUrlWithAwareSubchannels(this.webSocketUrl, AWARE_DATA_CHANNEL)
+            : this.webSocketUrl;
+
+        const connectStart = performance.now();
+
+        try {
+          await this.connect(connectUrl);
+        } catch (error) {
+          // register() succeeded; only connect() failed. Attach the measured datachannel time so
+          // callers don't misreport a websocket failure as a registration that never completed.
+          // @ts-ignore
+          error.timing = {clientLLMDatachannelResponseTime};
+          throw error;
+        }
+
+        const clientLLMWebSocketConnectTime = Math.round(performance.now() - connectStart);
+
+        return {clientLLMDatachannelResponseTime, clientLLMWebSocketConnectTime};
+      })
+      .finally(() => {
+        this.connectingPromise = undefined;
+      });
+
+    return this.connectingPromise;
+  };
 
   /**
    * Tells if LLM socket is connected
@@ -100,32 +172,147 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
 
   /**
    * Tells if LLM socket is binding
-   * @returns {string} binding
+   * @returns {string | undefined} binding
    */
-  public getBinding = (): string => this.binding;
+  public getBinding = (): string | undefined => this.binding;
 
   /**
    * Get Locus URL for the connection
-   * @returns {string} locus Url
+   * @returns {string | undefined} locus Url
    */
-  public getLocusUrl = (): string => this.locusUrl;
+  public getLocusUrl = (): string | undefined => this.locusUrl;
 
   /**
    * Get data channel URL for the connection
-   * @returns {string} data channel Url
+   * @returns {string | undefined} data channel Url
    */
-  public getDatachannelUrl = (): string => this.datachannelUrl;
+  public getDatachannelUrl = (): string | undefined => this.datachannelUrl;
 
   /**
-   * Disconnects websocket connection
-   * @param {{code: number, reason: string}} options - The disconnect option object with code and reason
+   * Get data channel token for this connection.
+   * @returns {string | undefined}
+   */
+  public getDatachannelToken = (): string | undefined => this.datachannelToken;
+
+  /**
+   * Store the data channel token for this connection.
+   * @param {string} token
+   * @returns {void}
+   */
+  public setDatachannelToken = (token: string): void => {
+    this.datachannelToken = token;
+  };
+
+  /**
+   * Clear the data channel token for this connection.
+   * @returns {void}
+   */
+  public clearDatachannelToken = (): void => {
+    this.datachannelToken = undefined;
+  };
+
+  /**
+   * Set the handler used to refresh the DataChannel token.
+   * @param {function} handler
+   * @returns {void}
+   */
+  public setRefreshHandler = (
+    handler: () => Promise<{
+      body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+    }>
+  ): void => {
+    this.refreshHandler = handler;
+  };
+
+  /**
+   * Refresh the data channel token using the injected handler.
+   * @returns {Promise<object | null>}
+   */
+  public async refreshDataChannelToken() {
+    if (!this.refreshHandler) {
+      this.logger.warn(
+        'llm#refreshDataChannelToken --> LLM refreshHandler is not set, skipping token refresh'
+      );
+
+      return null;
+    }
+
+    try {
+      return await this.refreshHandler();
+    } catch (error: any) {
+      this.logger.warn(
+        `llm#refreshDataChannelToken --> DataChannel token refresh failed: ${
+          error?.message || error
+        }`
+      );
+
+      return null;
+    }
+  }
+
+  /**
+   * Disconnects the WebSocket and clears all connection state.
+   * Overrides Mercury's disconnect to also clear LLM-specific state.
+   * @param {object} [options]
    * @returns {Promise<void>}
    */
-  public disconnectLLM = (options: object): Promise<void> =>
-    this.disconnect(options).then(() => {
-      this.locusUrl = undefined;
-      this.datachannelUrl = undefined;
-      this.binding = undefined;
-      this.webSocketUrl = undefined;
-    });
+  public async disconnect(options?: {code: number; reason: string}): Promise<void> {
+    await super.disconnect(options);
+    this.webSocketUrl = undefined;
+    this.binding = undefined;
+    this.locusUrl = undefined;
+    this.datachannelUrl = undefined;
+    this.datachannelToken = undefined;
+    this.refreshHandler = undefined;
+    this.emit('disconnected');
+  }
+
+  /**
+   * Matches a request URL to a stored datachannel registration URL.
+   * Host can differ (e.g. rewritten by hostmap interceptor), so we first
+   * try full URL prefix and then fall back to pathname prefix.
+   * @param {string} requestUrl
+   * @param {string} registrationUrl
+   * @returns {boolean}
+   */
+  public static matchesDatachannelRequestUrl(requestUrl: string, registrationUrl: string): boolean {
+    if (!requestUrl || !registrationUrl) {
+      return false;
+    }
+
+    if (requestUrl.startsWith(registrationUrl)) {
+      return true;
+    }
+
+    try {
+      const request = new URL(requestUrl);
+      const registration = new URL(registrationUrl);
+
+      return request.pathname.startsWith(registration.pathname);
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Returns true if the data channel token feature flag is enabled.
+   * @returns {Promise<boolean>}
+   */
+  public isDataChannelTokenEnabled(): Promise<boolean> {
+    // @ts-ignore
+    return this.webex.internal.feature.getFeature('developer', DATA_CHANNEL_WITH_JWT_TOKEN);
+  }
+
+  /**
+   * Builds a WebSocket URL with the `subscriptionAwareSubchannels` query parameter.
+   * @param {string} baseUrl
+   * @param {string[]} subchannels
+   * @returns {string}
+   */
+  public static buildUrlWithAwareSubchannels = (baseUrl: string, subchannels: string[]) => {
+    const urlObj = new URL(baseUrl);
+    urlObj.searchParams.set(SUBSCRIPTION_AWARE_SUBCHANNELS_PARAM, subchannels.join(','));
+
+    return urlObj.toString();
+  };
 }

package/src/llm.types.ts

@@ -1,9 +1,96 @@
+export enum DataChannelTokenType {
+  Default = 'llm-default-session',
+  PracticeSession = 'llm-practice-session',
+}
+
+type DataChannelTokenKey = DataChannelTokenType | string;
+
+/**
+ * Latencies (in milliseconds) captured during register + websocket connect.
+ */
+type RegisterAndConnectTiming = {
+  clientLLMDatachannelResponseTime?: number;
+  clientLLMWebSocketConnectTime?: number;
+};
+
+/**
+ * ILLMChannel — interface for a single LLM WebSocket connection.
+ * Created via `webex.internal.llm.createChannel()`.
+ */
 interface ILLMChannel {
-  registerAndConnect: (locusUrl: string, datachannelUrl: string) => Promise<void>;
+  /** Register with the server and connect the WebSocket. */
+  registerAndConnect: (
+    locusUrl: string,
+    datachannelUrl: string,
+    datachannelToken?: string
+  ) => Promise<void>;
+
+  /** Returns true if the WebSocket is connected. */
   isConnected: () => boolean;
-  getBinding: () => string;
-  getLocusUrl: () => string;
-  disconnectLLM: (options: {code: number; reason: string}) => Promise<void>;
+
+  /** Returns true if a connection is currently in progress. */
+  isConnecting: () => boolean;
+
+  /** Get the underlying WebSocket. */
+  getSocket: () => any;
+
+  /** Get the binding ID for this connection. */
+  getBinding: () => string | undefined;
+
+  /** Get the Locus URL associated with this connection. */
+  getLocusUrl: () => string | undefined;
+
+  /** Get the datachannel URL for this connection. */
+  getDatachannelUrl: () => string | undefined;
+
+  /** Get the stored datachannel token. */
+  getDatachannelToken: () => string | undefined;
+
+  /** Store a datachannel token for this connection. */
+  setDatachannelToken: (datachannelToken: string) => void;
+
+  /** Clear the stored datachannel token. */
+  clearDatachannelToken: () => void;
+
+  /** Set the handler used to refresh the datachannel token. */
+  setRefreshHandler: (
+    handler: () => Promise<{
+      body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+    }>
+  ) => void;
+
+  /** Refresh the datachannel token using the injected handler. */
+  refreshDataChannelToken: () => Promise<{
+    body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+  } | null>;
+
+  /** Disconnect the WebSocket and clean up state. */
+  disconnect: (options?: {code: number; reason: string}) => Promise<void>;
+
+  /** Check if the datachannel token feature flag is enabled. */
+  isDataChannelTokenEnabled: () => Promise<boolean>;
+}
+
+/**
+ * ILLMPlugin — interface for the LLM plugin factory.
+ * Accessed via `webex.internal.llm`.
+ */
+interface ILLMPlugin {
+  /** Create a new LLM channel instance. */
+  createChannel: () => ILLMChannel;
+
+  /** Check if the datachannel token feature flag is enabled globally. */
+  isDataChannelTokenEnabled: () => Promise<boolean>;
+
+  /** Find a channel by matching a request URL to its datachannel URL. */
+  getChannelByDatachannelUrl: (url: string) => ILLMChannel | undefined;
+
+  /** Get all active channels. */
+  getAllChannels: () => Set<ILLMChannel>;
+
+  /** Disconnect all active channels. */
+  disconnectAllChannels: (options?: {code: number; reason: string}) => Promise<void>;
 }
+
 // eslint-disable-next-line import/prefer-default-export
-export type {ILLMChannel};
+export type {ILLMChannel, ILLMPlugin, DataChannelTokenKey, RegisterAndConnectTiming};