[STREAM-1180] Change media handling to only allow headsets to stop being used if there are no active conversations; also only disconnect idle connections

Author: hjon

src/client.ts

@@ -44,6 +44,7 @@ import { HeadsetProxyService } from './headsets/headset';
 import { Constants } from 'stanza';
 import { setupWebrtcForWindows11 } from './windows11-first-session-hack';
 import { ISdkHeadsetService } from './headsets/headset-types';
+import { SoftphoneSessionHandler } from '.';
 
 const ENVIRONMENTS = [
   'mypurecloud.com',
@@ -111,7 +112,7 @@ export class GenesysCloudWebrtcSdk extends (EventEmitter as { new(): StrictEvent
   _customerData: ICustomerData;
   _hasConnected: boolean;
   _config: ISdkFullConfig;
-  _mediaHandling = MediaHandling.media;
+  _mediaHandling = MediaHandling.standardMedia;
 
   get isInitialized (): boolean {
     return !!this._streamingConnection;
@@ -863,25 +864,41 @@ export class GenesysCloudWebrtcSdk extends (EventEmitter as { new(): StrictEvent
     this.media.setDefaultAudioStream(stream);
   }
 
+  /**
+   * **Genesys internal use only** - non-Genesys apps may experience unexpected behavior.
+   *
+   * Change the media handling for softphone sessions, which should be
+   * be chosen based on the alerting leader status of the consuming client.
+   *
+   * If media handling is reduced, idle persistent connections will be
+   * disconnected.
+   *
+   * @param mediaHandling how softphone media should be handled
+   */
   setMediaHandling (mediaHandling: MediaHandling): void {
-    this._mediaHandling = mediaHandling;
+    const activeConversations = this.sessionManager.getAllActiveConversations();
+    console.log('Hjon: mediaHandling:', mediaHandling);
+    const useHeadsets = !(mediaHandling === MediaHandling.reducedMediaNoHeadsets);
+    console.log('Hjon: useHeadsets:', useHeadsets);
 
-    // The intent behind this comes from requirements for alerting leader
-    // where a client shouldn't handle media (mostly) if it isn't the alerting
-    // leader. Ideally this would only handle outbound calls, but we can't
-    // distinguish between outbound calls and inbound autoanswer ACD calls when
-    // we receive the `propose`.
-    if (mediaHandling === MediaHandling.autoAnswerOnly) {
-      this.setUseHeadsets(false);
-
-      // Disconnect any persistent connections we might have
-      this.sessionManager.getAllActiveSessions()
-        .filter(session => session.sessionType === SessionTypes.softphone)
-        .forEach(softphoneSession => {
-          this.sessionManager.forceTerminateSession(softphoneSession.id);
-        });
-    } else {
-      this.setUseHeadsets(true);
+    if (activeConversations.length !== 0 && !useHeadsets) {
+      throw createAndEmitSdkError.call(this, SdkErrorTypes.not_supported, 'Cannot downgrade media handling to stop using headsets during an active call');
+    }
+
+    this._mediaHandling = mediaHandling;
+    this.setUseHeadsets(useHeadsets);
+
+    const reduceMediaHandling = mediaHandling === MediaHandling.reducedMediaHeadsets || mediaHandling === MediaHandling.reducedMediaNoHeadsets;
+    if (reduceMediaHandling) {
+      const conversationSessionIds = activeConversations.map(conversation => conversation.sessionId);
+      // Disconnect connections that aren't associated with an active conversation.
+      // When a client is no longer the alerting leader, it needs to give up any
+      // persistent connections. Active calls should be maintained.
+      this.sessionManager.getAllSessions().forEach(session => {
+        if (session.sessionType === SessionTypes.softphone && !conversationSessionIds.includes(session.id)) {
+          this.sessionManager.forceTerminateSession(session.id);
+        }
+      });
     }
   }
 

src/headsets/headset.ts

@@ -49,8 +49,8 @@ export class HeadsetProxyService implements ISdkHeadsetService {
     // TODO: PCM-2060 - remove this
     this.useHeadsetOrchestration = !this.sdk._config.disableHeadsetControlsOrchestration;
 
-    if (this.sdk._mediaHandling === MediaHandling.autoAnswerOnly) {
-      this.sdk.logger.warn('setUseHeadsets was called with `true` but headsets are not supported in this configuration - not handling media. Not activating headsets.');
+    if (this.sdk._mediaHandling === MediaHandling.reducedMediaNoHeadsets) {
+      this.sdk.logger.warn('setUseHeadsets was called with `true` but media handling is set to `reducedMediaNoHeadsets`; headsets are not supported in this configuration - not handling media. Not activating headsets.');
       useHeadsets = false;
     }
 

src/sessions/softphone-session-handler.ts

@@ -149,10 +149,12 @@ export class SoftphoneSessionHandler extends BaseSessionHandler {
   async handlePropose (pendingSession: IPendingSession): Promise<void> {
     const isPrivAnswerAuto = pendingSession.privAnswerMode === 'Auto';
     const eagerConnectionEstablishmentMode = this.sdk._config.eagerPersistentConnectionEstablishment;
-    const autoAnswerOnly = this.sdk._mediaHandling === MediaHandling.autoAnswerOnly;
     const logInfo = { sessionId: pendingSession?.id, conversationId: pendingSession.conversationId };
+    const reducedMediaHandling = this.sdk._mediaHandling === MediaHandling.reducedMediaHeadsets || this.sdk._mediaHandling === MediaHandling.reducedMediaNoHeadsets;
+
+    if (reducedMediaHandling) {
+      this.log('info', 'received a propose while the SDK is configured for reduced media handling', logInfo);
 
-    if (autoAnswerOnly) {
       if (pendingSession.autoAnswer) {
         // emit the pendingSession event
         await super.handlePropose(pendingSession);
@@ -164,7 +166,7 @@ export class SoftphoneSessionHandler extends BaseSessionHandler {
           await this.proceedWithSession(pendingSession);
         }
       } else {
-        this.log('info', 'media handling is set to "auto-answer-only", but this propose is not marked as autoAnswer and will be ignored', logInfo);
+        this.log('info', 'media handling is reduced, but this propose is not marked as autoAnswer and will be ignored', logInfo);
         return;
       }
     } else {

src/types/enums.ts

@@ -45,12 +45,26 @@ export enum JingleReasons {
   alternativeSession = 'alternative-session'
 }
 
+/** These currently only affect softphone media */
 export enum MediaHandling {
   /** Handle all media; headset controls use traditional orchestration */
-  media = 'media',
+  standardMedia = 'standard-media',
   /** Handle all media; headset controls follow alerting leader */
   alertingLeaderMedia = 'alerting-leader-media',
-  /** Only handle autoAnswer calls; headset controls are not used */
-  // Ideally we would only allow outbound calls, but currently we can't distinguish between an outbound call and an inbound autoanswer ACD call
-  autoAnswerOnly = 'auto-answer-only'
+  /**
+   * Handle some media (see below); headset controls use traditional orchestration
+   *
+   * - New eager persistent connections will be ignored.
+   * - Auto-answer calls will be handled, which could result in a
+   * persistent connection being established.
+   */
+  reducedMediaHeadsets = 'reduced-media-headsets',
+  /**
+   * Handle some media (see below); headset controls are not used
+   *
+   * - New eager persistent connections will be ignored.
+   * - Auto-answer calls will be handled, which could result in a
+   * persistent connection being established.
+   */
+  reducedMediaNoHeadsets = 'reduced-media-no-headsets',
 }

test/unit/client.test.ts

@@ -30,7 +30,8 @@ import {
   IPersonDetails,
   ISessionIdAndConversationId,
   VideoSessionHandler,
-  MediaHandling
+  MediaHandling,
+  IActiveConversationDescription
 } from '../../src';
 import * as utils from '../../src/utils';
 import { RetryPromise } from 'genesys-cloud-streaming-client/dist/es/utils';
@@ -1161,33 +1162,50 @@ describe('Client', () => {
   });
 
   describe('setMediaHandling()', () => {
-    it('should stop using headsets and disconnect any active sessions when set to "autoAnswerOnly"', () => {
+    it('should throw if media handling will not use headsets but there is an active conversation', () => {
       sdk = constructSdk();
-      const useHeadsetsSpy = jest.fn();
-      sdk.setUseHeadsets = useHeadsetsSpy;
+      const conversations = [{ conversationId: 'test-conversation-id' }] as IActiveConversationDescription[];
+      sessionManagerMock.getAllActiveConversations.mockReturnValue(conversations);
+
+      expect(() => {
+        sdk.setMediaHandling(MediaHandling.reducedMediaNoHeadsets);
+      }).toThrow();
+    });
+
+    it('should disconnect any sessions not connected to an active conversation when set to a reduced handling of media', () => {
+      sdk = constructSdk();
+      sdk.setUseHeadsets = jest.fn();
+
       const mockSession = new MockSession(SessionTypes.softphone);
-      const sessionId = mockSession.id;
-      const sessions = [mockSession] as unknown as IExtendedMediaSession[];
-      sessionManagerMock.getAllActiveSessions.mockReturnValue(sessions);
+      const conversations = [{ sessionId: mockSession.id }] as IActiveConversationDescription[];
+      sessionManagerMock.getAllActiveConversations.mockReturnValue(conversations);
+      const idleSession = new MockSession(SessionTypes.softphone);
+      const idleSessionId = idleSession.id;
+      const sessions = [mockSession, idleSession] as unknown as IExtendedMediaSession[];
+      sessionManagerMock.getAllSessions.mockReturnValue(sessions);
       const forceTerminateSpy = jest.fn();
       sessionManagerMock.forceTerminateSession = forceTerminateSpy;
 
-      sdk.setMediaHandling(MediaHandling.autoAnswerOnly);
+      sdk.setMediaHandling(MediaHandling.reducedMediaHeadsets);
 
-      expect(useHeadsetsSpy).toHaveBeenCalledWith(false);
-      expect(forceTerminateSpy).toHaveBeenCalledWith(sessionId);
+      expect(forceTerminateSpy).toHaveBeenCalledTimes(1);
+      expect(forceTerminateSpy).toHaveBeenCalledWith(idleSessionId);
     });
 
     it('should use headsets when handling any media', () => {
       sdk = constructSdk();
+      sessionManagerMock.getAllActiveConversations.mockReturnValue([]);
       const useHeadsetsSpy = jest.fn();
       sdk.setUseHeadsets = useHeadsetsSpy;
 
-      sdk.setMediaHandling(MediaHandling.media);
+      sdk.setMediaHandling(MediaHandling.standardMedia);
       expect(useHeadsetsSpy).toHaveBeenCalledWith(true);
 
       sdk.setMediaHandling(MediaHandling.alertingLeaderMedia);
       expect(useHeadsetsSpy).toHaveBeenCalledWith(true);
+
+      sdk.setMediaHandling(MediaHandling.reducedMediaHeadsets);
+      expect(useHeadsetsSpy).toHaveBeenCalledWith(true);
     });
   });
 

test/unit/headset/headset.test.ts

@@ -301,8 +301,8 @@ describe('HeadsetProxyService', () => {
       expect(proxyService['currentHeadsetService']).toBeInstanceOf(SdkHeadsetServiceFake);
     });
 
-    it('should use fake service if useHeadsets and only handling autoAnswer calls', () => {
-      proxyService['sdk']._mediaHandling = MediaHandling.autoAnswerOnly;
+    it('should use fake service if useHeadsets and media is set to reducedMediaNoHeadsets', () => {
+      proxyService['sdk']._mediaHandling = MediaHandling.reducedMediaNoHeadsets;
       const spy = jest.spyOn(proxyService, 'updateAudioInputDevice');
 
       proxyService.setUseHeadsets(true);

test/unit/sessions/softphone-session-handler.test.ts

@@ -70,31 +70,36 @@ describe('shouldHandleSessionByJid()', () => {
 });
 
 describe('handlePropose()', () => {
-  it('should ignore the propose if mediaHandling is "autoAnswerOnly" and autoAnswer is false', async () => {
+  it('should ignore the propose if mediaHandling is a reducedMedia variant and autoAnswer is false', async () => {
     const superSpyHandlePropose = jest.spyOn(BaseSessionHandler.prototype, 'handlePropose');
     const superSpyProceed = jest.spyOn(BaseSessionHandler.prototype, 'proceedWithSession').mockImplementation();
     const spy = jest.fn();
     mockSdk.on('pendingSession', spy);
     const pendingSession = createPendingSession(SessionTypes.softphone);
     pendingSession.autoAnswer = false;
-    mockSdk._mediaHandling = MediaHandling.autoAnswerOnly;
 
+    mockSdk._mediaHandling = MediaHandling.reducedMediaHeadsets;
     await handler.handlePropose(pendingSession);
+    expect(spy).not.toHaveBeenCalled();
+    expect(superSpyHandlePropose).not.toHaveBeenCalled();
+    expect(superSpyProceed).not.toHaveBeenCalled();
 
+    mockSdk._mediaHandling = MediaHandling.reducedMediaNoHeadsets;
+    await handler.handlePropose(pendingSession);
     expect(spy).not.toHaveBeenCalled();
     expect(superSpyHandlePropose).not.toHaveBeenCalled();
     expect(superSpyProceed).not.toHaveBeenCalled();
   });
 
-  it('should not autoAnswer if mediaHandling is "autoAnswerOnly", autoAnswer is true, but disableAutoAnswer is configured', async () => {
+  it('should not autoAnswer if mediaHandling is reducedMedia, autoAnswer is true, but disableAutoAnswer is configured', async () => {
     const superSpyHandlePropose = jest.spyOn(BaseSessionHandler.prototype, 'handlePropose');
     const superSpyProceed = jest.spyOn(BaseSessionHandler.prototype, 'proceedWithSession').mockImplementation();
     const spy = jest.fn();
     mockSdk.on('pendingSession', spy);
     mockSdk._config.disableAutoAnswer = true;
     const pendingSession = createPendingSession(SessionTypes.softphone);
     pendingSession.autoAnswer = true;
-    mockSdk._mediaHandling = MediaHandling.autoAnswerOnly;
+    mockSdk._mediaHandling = MediaHandling.reducedMediaHeadsets;
 
     await handler.handlePropose(pendingSession);
 
@@ -103,15 +108,15 @@ describe('handlePropose()', () => {
     expect(superSpyProceed).not.toHaveBeenCalled();
   });
 
-  it('should emit pending session and proceed immediately if mediaHandling is "autoAnswerOnly", autoAnswer is true, and disableAutoAnswer is not configured', async () => {
+  it('should emit pending session and proceed immediately if mediaHandling is reducedMedia, autoAnswer is true, and disableAutoAnswer is not configured', async () => {
     const superSpyHandlePropose = jest.spyOn(BaseSessionHandler.prototype, 'handlePropose');
     const superSpyProceed = jest.spyOn(BaseSessionHandler.prototype, 'proceedWithSession').mockImplementation();
     const spy = jest.fn();
     mockSdk.on('pendingSession', spy);
     mockSdk._config.disableAutoAnswer = false;
     const pendingSession = createPendingSession(SessionTypes.softphone);
     pendingSession.autoAnswer = true;
-    mockSdk._mediaHandling = MediaHandling.autoAnswerOnly;
+    mockSdk._mediaHandling = MediaHandling.reducedMediaNoHeadsets;
 
     await handler.handlePropose(pendingSession);