@webex/internal-plugin-llm 3.12.0-next.4 → 3.12.0-next.40

package/src/llm.ts

@@ -10,7 +10,7 @@ import {
   SUBSCRIPTION_AWARE_SUBCHANNELS_PARAM,
   LLM_DEFAULT_SESSION,
 } from './constants';
-import {ILLMChannel, DataChannelTokenType} from './llm.types';
+import {ILLMChannel, DataChannelTokenType, RegisterAndConnectTiming} from './llm.types';
 
 export const config = {
   llm: {
@@ -51,6 +51,7 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
   defaultSessionId = LLM_DEFAULT_SESSION;
   /**
    * Map to store connection-specific data for multiple LLM connections
+   * Key: sessionId
    * @private
    * @type {Map<string, {webSocketUrl?: string; binding?: string; locusUrl?: string; datachannelUrl?: string}>}
    */
@@ -61,19 +62,20 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
       binding?: string;
       locusUrl?: string;
       datachannelUrl?: string;
-      datachannelToken?: string;
+      ownerMeetingId?: string;
+      refreshHandler?: () => Promise<{
+        body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+      }>;
     }
   > = new Map();
 
-  private datachannelTokens: Record<DataChannelTokenType, string> = {
+  // Session-keyed token cache is intentionally decoupled from connection state.
+  // Disconnecting a socket session must not implicitly wipe token cache.
+  private datachannelTokens: Record<string, string | undefined> = {
     [DataChannelTokenType.Default]: undefined,
     [DataChannelTokenType.PracticeSession]: undefined,
   };
 
-  private refreshHandler?: () => Promise<{
-    body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
-  }>;
-
   /**
    * Register to the websocket
    * @param {string} llmSocketUrl
@@ -123,16 +125,36 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
     datachannelUrl: string,
     datachannelToken?: string,
     sessionId: string = LLM_DEFAULT_SESSION
-  ): Promise<void> =>
-    this.register(datachannelUrl, datachannelToken, sessionId).then(async () => {
-      if (!locusUrl || !datachannelUrl) return undefined;
+  ): Promise<RegisterAndConnectTiming | undefined> => {
+    const registerStart = performance.now();
 
-      // Get or create connection data
+    // Pre-populate locusUrl and datachannelUrl before register() fires the
+    // HTTP POST, so that any token refresh triggered during registration can
+    // be routed via connections without falling back to a locusInfo URL scan.
+    if (locusUrl && datachannelUrl) {
       const sessionData = this.connections.get(sessionId) || {};
       sessionData.locusUrl = locusUrl;
       sessionData.datachannelUrl = datachannelUrl;
-      sessionData.datachannelToken = datachannelToken;
       this.connections.set(sessionId, sessionData);
+    }
+
+    return this.register(datachannelUrl, datachannelToken, sessionId).then(async () => {
+      if (!locusUrl || !datachannelUrl) return undefined;
+
+      const clientLLMDatachannelResponseTime = Math.round(performance.now() - registerStart);
+
+      // locusUrl and datachannelUrl were pre-populated before register(); here
+      // we only need to read the existing session data to get webSocketUrl/binding
+      // that register() filled in.
+      const sessionData = this.connections.get(sessionId) || {};
+
+      if (!sessionData.webSocketUrl) {
+        // register() succeeded but the response carried no websocket URL. Attach the measured
+        // datachannel time so callers don't misreport a registration that completed as time 0.
+        const error: any = new Error(`LLM registration for ${sessionId} returned no websocket URL`);
+        error.timing = {clientLLMDatachannelResponseTime};
+        throw error;
+      }
 
       const isDataChannelTokenEnabled = await this.isDataChannelTokenEnabled();
 
@@ -140,8 +162,23 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
         ? LLMChannel.buildUrlWithAwareSubchannels(sessionData.webSocketUrl, AWARE_DATA_CHANNEL)
         : sessionData.webSocketUrl;
 
-      return this.connect(connectUrl, sessionId);
+      const connectStart = performance.now();
+
+      try {
+        await this.connect(connectUrl, sessionId);
+      } 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};
     });
+  };
 
   /**
    * Tells if LLM socket is connected
@@ -187,73 +224,234 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
     return sessionData?.datachannelUrl;
   };
 
+  /**
+   * Get WebSocket URL for the connection
+   * @param {string} sessionId - Connection identifier
+   * @returns {string | undefined} WebSocket URL
+   */
+  public getWebSocketUrl = (sessionId = LLM_DEFAULT_SESSION): string | undefined => {
+    const sessionData = this.connections.get(sessionId);
+
+    return sessionData?.webSocketUrl;
+  };
+
+  /**
+   * Set the owner meeting ID for a given LLM session. Used by the meetings
+   * plugin to tag which Meeting instance currently owns the (default) LLM
+   * connection so that other Meeting instances can avoid disconnecting or
+   * re-initializing a connection they do not own.
+   *
+   * Does NOT create a connections entry if one does not already exist — this
+   * method is a no-op when there is no active session data. Callers should
+   * invoke it after a successful `registerAndConnect` or during an explicit
+   * ownership handoff.
+   *
+   * @param {string | undefined} ownerMeetingId - Meeting ID (or undefined to clear)
+   * @param {string} sessionId - Connection identifier (defaults to default session)
+   * @returns {void}
+   */
+  public setOwnerMeetingId = (
+    ownerMeetingId: string | undefined,
+    sessionId: string = LLM_DEFAULT_SESSION
+  ): void => {
+    const sessionData = this.connections.get(sessionId);
+
+    if (!sessionData) {
+      return;
+    }
+
+    sessionData.ownerMeetingId = ownerMeetingId;
+    this.connections.set(sessionId, sessionData);
+  };
+
+  /**
+   * Get the owner meeting ID currently associated with an LLM session.
+   * Returns undefined when no owner has been assigned (e.g. before the
+   * first successful `registerAndConnect`, or after `disconnectLLM`).
+   *
+   * @param {string} sessionId - Connection identifier (defaults to default session)
+   * @returns {string | undefined} ownerMeetingId
+   */
+  public getOwnerMeetingId = (sessionId: string = LLM_DEFAULT_SESSION): string | undefined => {
+    const sessionData = this.connections.get(sessionId);
+
+    return sessionData?.ownerMeetingId;
+  };
+
+  /**
+   * Resolve ownership information for an LLM session.
+   *
+   * Rules:
+   * - no current owner => caller may proceed
+   * - caller has no identity to assert => treat as owner
+   * - otherwise caller must match current owner
+   *
+   * @param {string | undefined} ownerMeetingId - Candidate owner to evaluate
+   * @param {string} sessionId - Connection identifier (defaults to default session)
+   * @returns {{currentOwner: (string|undefined), isOwner: boolean}}
+   */
+  public resolveSessionOwnership = (
+    ownerMeetingId?: string,
+    sessionId: string = LLM_DEFAULT_SESSION
+  ): {
+    currentOwner: string | undefined;
+    isOwner: boolean;
+  } => {
+    const currentOwner = this.getOwnerMeetingId(sessionId);
+    const isOwner = !currentOwner || !ownerMeetingId || currentOwner === ownerMeetingId;
+
+    return {
+      currentOwner,
+      isOwner,
+    };
+  };
+
   /**
    * Get data channel token for the connection
-   * @param {DataChannelTokenType} dataChannelTokenType
-   * @returns {string} data channel token
+   * @param {DataChannelTokenType|string} tokenKey
+   * @param {string | undefined} ownerMeetingId - Meeting id asserting read ownership
+   * @returns {string | undefined} data channel token
    */
   public getDatachannelToken = (
-    dataChannelTokenType: DataChannelTokenType = DataChannelTokenType.Default
-  ): string => {
-    return this.datachannelTokens[dataChannelTokenType];
+    tokenKey?: DataChannelTokenType | string,
+    ownerMeetingId?: string
+  ): string | undefined => {
+    const resolvedTokenKey = tokenKey ?? DataChannelTokenType.Default;
+
+    const {currentOwner, isOwner} = this.resolveSessionOwnership(ownerMeetingId, resolvedTokenKey);
+
+    if (!isOwner) {
+      this.logger.info(
+        `llm#getDatachannelToken --> skip read for session ${resolvedTokenKey}; owned by ${currentOwner}, candidate ${ownerMeetingId}`
+      );
+
+      return undefined;
+    }
+
+    return this.datachannelTokens[resolvedTokenKey];
   };
 
   /**
    * Set data channel token for the connection
    * @param {string} datachannelToken - data channel token
-   * @param {DataChannelTokenType} dataChannelTokenType
+   * @param {DataChannelTokenType|string} [tokenKey]
+   * @param {string | undefined} ownerMeetingId - Meeting id asserting write ownership
    * @returns {void}
    */
   public setDatachannelToken = (
     datachannelToken: string,
-    dataChannelTokenType: DataChannelTokenType = DataChannelTokenType.Default
+    tokenKey?: DataChannelTokenType | string,
+    ownerMeetingId?: string
   ): void => {
-    this.datachannelTokens[dataChannelTokenType] = datachannelToken;
+    const resolvedTokenKey = tokenKey ?? DataChannelTokenType.Default;
+
+    const {currentOwner, isOwner} = this.resolveSessionOwnership(ownerMeetingId, resolvedTokenKey);
+
+    if (!isOwner) {
+      this.logger.info(
+        `llm#setDatachannelToken --> skip write for session ${resolvedTokenKey}; owned by ${currentOwner}, candidate ${ownerMeetingId}`
+      );
+
+      return;
+    }
+
+    this.datachannelTokens[resolvedTokenKey] = datachannelToken;
   };
 
   /**
-   * Resets all data‑channel tokens to their initial undefined values.
-   * Used when leaving or disconnecting from a meeting.
+   * Clears a single session's data channel token.
+   * @param {DataChannelTokenType|string} tokenKey
+   * @param {string} ownerMeetingId - Meeting id asserting delete ownership
    * @returns {void}
    */
-  public resetDatachannelTokens() {
-    this.datachannelTokens = {
-      [DataChannelTokenType.Default]: undefined,
-      [DataChannelTokenType.PracticeSession]: undefined,
-    };
-  }
+  public clearDatachannelToken = (
+    tokenKey: DataChannelTokenType | string,
+    ownerMeetingId: string
+  ): void => {
+    const resolvedTokenKey = tokenKey;
+
+    const {currentOwner, isOwner} = this.resolveSessionOwnership(ownerMeetingId, resolvedTokenKey);
+
+    if (!isOwner) {
+      this.logger.info(
+        `llm#clearDatachannelToken --> skip clear for session ${resolvedTokenKey}; owned by ${currentOwner}, candidate ${ownerMeetingId}`
+      );
+
+      return;
+    }
+
+    this.datachannelTokens[resolvedTokenKey] = undefined;
+    delete this.datachannelTokens[resolvedTokenKey];
+  };
 
   /**
    * Set the handler used to refresh the DataChannel token
    *
    * @param {function} handler - Function that returns a refreshed token
+   * @param {string} [sessionId] - Connection identifier
+   * @param {string | undefined} ownerMeetingId - Meeting id asserting refresh-handler ownership
    * @returns {void}
    */
   public setRefreshHandler(
     handler: () => Promise<{
       body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
-    }>
+    }>,
+    sessionId?: string,
+    ownerMeetingId?: string
   ) {
-    this.refreshHandler = handler;
+    const resolvedSessionId = sessionId ?? LLM_DEFAULT_SESSION;
+
+    const {currentOwner, isOwner} = this.resolveSessionOwnership(ownerMeetingId, resolvedSessionId);
+
+    if (!isOwner) {
+      this.logger.info(
+        `llm#setRefreshHandler --> skip write for session ${resolvedSessionId}; owned by ${currentOwner}, candidate ${ownerMeetingId}`
+      );
+
+      return;
+    }
+
+    const sessionData = this.connections.get(resolvedSessionId);
+
+    if (sessionData) {
+      sessionData.refreshHandler = handler;
+      if (ownerMeetingId) {
+        sessionData.ownerMeetingId = ownerMeetingId;
+      }
+
+      return;
+    }
+
+    // Intentionally allow a pre-connection session shape here.
+    // Some flows inject refreshHandler before register/connect so token refresh
+    // is already wired when the socket lifecycle starts. register()/
+    // registerAndConnect() will later fill webSocketUrl/binding/locusUrl/
+    // datachannelUrl into this same session entry.
+    this.connections.set(resolvedSessionId, {
+      refreshHandler: handler,
+      ownerMeetingId,
+    });
   }
 
   /**
    * Refresh the data channel token using the injected handler.
    * Logs a descriptive error if the handler is missing or fails.
-   *
+   * @param {string} sessionId - Connection identifier (defaults to default session)
    * @returns {Promise<string>} The refreshed token.
    */
-  public async refreshDataChannelToken() {
-    if (!this.refreshHandler) {
+  public async refreshDataChannelToken(sessionId: string = LLM_DEFAULT_SESSION) {
+    const refreshHandler = this.connections.get(sessionId)?.refreshHandler;
+
+    if (!refreshHandler) {
       this.logger.warn(
-        'llm#refreshDataChannelToken --> LLM refreshHandler is not set, skipping token refresh'
+        `llm#refreshDataChannelToken --> LLM refreshHandler is not set for session ${sessionId}, skipping token refresh`
       );
 
       return null;
     }
 
     try {
-      const res = await this.refreshHandler();
+      const res = await refreshHandler();
 
       return res;
     } catch (error: any) {
@@ -271,16 +469,51 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
    * Disconnects websocket connection
    * @param {{code: number, reason: string}} options - The disconnect option object with code and reason
    * @param {string} sessionId - Connection identifier
-   * @returns {Promise<void>}
+   * @param {string} ownerMeetingId - Meeting id asserting disconnect ownership
+   * @returns {Promise<boolean>} True when disconnect was performed, false when skipped
    */
   public disconnectLLM = (
     options: {code: number; reason: string},
-    sessionId: string = LLM_DEFAULT_SESSION
-  ): Promise<void> =>
-    this.disconnect(options, sessionId).then(() => {
+    sessionId?: string,
+    ownerMeetingId?: string
+  ): Promise<boolean> => {
+    const resolvedSessionId = sessionId ?? LLM_DEFAULT_SESSION;
+
+    // Backward-compat path: historically callers could omit ownerMeetingId
+    // (and sometimes sessionId). Reuse current owner when available so legacy
+    // calls remain best-effort without throwing at teardown time.
+    const resolvedOwnerMeetingId = ownerMeetingId || this.getOwnerMeetingId(resolvedSessionId);
+
+    if (!ownerMeetingId) {
+      this.logger.warn(
+        `llm#disconnectLLM --> ownerMeetingId is omitted for session ${resolvedSessionId}; using legacy compatibility path`
+      );
+    }
+
+    const {currentOwner, isOwner} = this.resolveSessionOwnership(
+      resolvedOwnerMeetingId,
+      resolvedSessionId
+    );
+
+    if (!isOwner) {
+      this.logger.info(
+        `llm#disconnectLLM --> skip disconnect for session ${resolvedSessionId}; owned by ${currentOwner}, candidate ${resolvedOwnerMeetingId}`
+      );
+
+      return Promise.resolve(false);
+    }
+
+    return this.disconnect(options, resolvedSessionId).then(() => {
+      // Clear owner tag before cleanup to ensure it's not lingering
+      // if another meeting claimed it during disconnect
+      this.setOwnerMeetingId(undefined, resolvedSessionId);
+
       // Clean up sessions data
-      this.connections.delete(sessionId);
+      this.connections.delete(resolvedSessionId);
+
+      return true;
     });
+  };
 
   /**
    * Disconnects all LLM websocket connections
@@ -304,10 +537,79 @@ export default class LLMChannel extends (Mercury as any) implements ILLMChannel
       binding?: string;
       locusUrl?: string;
       datachannelUrl?: string;
-      datachannelToken?: string;
+      ownerMeetingId?: string;
     }
   > => new Map(this.connections);
 
+  /**
+   * Look up the locusUrl associated with a datachannel request URL.
+   * Iterates all active LLM sessions and returns the locusUrl of the
+   * session whose stored datachannelUrl is a prefix of the given request URL.
+   *
+   * @param {string} requestUrl - The in-flight request URL to match
+   * @returns {string | undefined} The matching locusUrl, or undefined if not found
+   */
+  public getLocusUrlByDatachannelUrl(requestUrl: string): string | undefined {
+    for (const [, connection] of this.connections) {
+      if (
+        connection.datachannelUrl &&
+        LLMChannel.matchesDatachannelRequestUrl(requestUrl, connection.datachannelUrl)
+      ) {
+        return connection.locusUrl;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Look up the sessionId associated with a datachannel request URL.
+   * Iterates all active LLM sessions and returns the sessionId whose
+   * stored datachannelUrl is a prefix of the given request URL.
+   *
+   * @param {string} requestUrl - The in-flight request URL to match
+   * @returns {string | undefined} The matching sessionId, or undefined if not found
+   */
+  public getSessionIdByDatachannelUrl(requestUrl: string): string | undefined {
+    for (const [sessionId, connection] of this.connections) {
+      if (
+        connection.datachannelUrl &&
+        LLMChannel.matchesDatachannelRequestUrl(requestUrl, connection.datachannelUrl)
+      ) {
+        return sessionId;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * 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  data channel token is enabled, false otherwise
    * @returns {Promise<boolean>} resolves with true if data channel token  is enabled

package/src/llm.types.ts

@@ -1,16 +1,67 @@
+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;
+};
+
 interface ILLMChannel {
   registerAndConnect: (
     locusUrl: string,
     datachannelUrl: string,
     datachannelToken?: string,
     sessionId?: string
-  ) => Promise<void>;
+  ) => Promise<RegisterAndConnectTiming | undefined>;
   isConnected: (sessionId?: string) => boolean;
   getBinding: (sessionId?: string) => string;
   getLocusUrl: (sessionId?: string) => string;
   getDatachannelUrl: (sessionId?: string) => string;
-  disconnectLLM: (options: {code: number; reason: string}, sessionId?: string) => Promise<void>;
+  getWebSocketUrl: (sessionId?: string) => string | undefined;
+  disconnectLLM: (
+    options: {code: number; reason: string},
+    sessionId?: string,
+    ownerMeetingId?: string
+  ) => Promise<boolean>;
   disconnectAllLLM: (options?: {code: number; reason: string}) => Promise<void>;
+  setOwnerMeetingId: (ownerMeetingId: string | undefined, sessionId?: string) => void;
+  getOwnerMeetingId: (sessionId?: string) => string | undefined;
+  resolveSessionOwnership: (
+    ownerMeetingId?: string,
+    sessionId?: string
+  ) => {
+    currentOwner: string | undefined;
+    isOwner: boolean;
+  };
+  getDatachannelToken: (
+    tokenKey?: DataChannelTokenKey,
+    ownerMeetingId?: string
+  ) => string | undefined;
+  setDatachannelToken: (
+    datachannelToken: string,
+    tokenKey?: DataChannelTokenKey,
+    ownerMeetingId?: string
+  ) => void;
+  clearDatachannelToken: (tokenKey: DataChannelTokenKey, ownerMeetingId: string) => void;
+  setRefreshHandler: (
+    handler: () => Promise<{
+      body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+    }>,
+    sessionId?: string,
+    ownerMeetingId?: string
+  ) => void;
+  refreshDataChannelToken: (sessionId?: string) => Promise<{
+    body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+  } | null>;
+  getLocusUrlByDatachannelUrl: (requestUrl: string) => string | undefined;
+  getSessionIdByDatachannelUrl: (requestUrl: string) => string | undefined;
   getAllConnections: () => Map<
     string,
     {
@@ -18,15 +69,10 @@ interface ILLMChannel {
       binding?: string;
       locusUrl?: string;
       datachannelUrl?: string;
-      datachannelToken?: string;
+      ownerMeetingId?: string;
     }
   >;
 }
 
-export enum DataChannelTokenType {
-  Default = 'llm-default-session',
-  PracticeSession = 'llm-practice-session',
-}
-
 // eslint-disable-next-line import/prefer-default-export
-export type {ILLMChannel};
+export type {ILLMChannel, DataChannelTokenKey, RegisterAndConnectTiming};