@webex/internal-plugin-mercury 3.11.0 → 3.12.0-auth-prejoin-fetch.1

package/test/unit/spec/mercury.js

@@ -100,9 +100,32 @@ describe('plugin-mercury', () => {
       });
 
       mercury = webex.internal.mercury;
+      mercury.defaultSessionId = 'mercury-default-session';
     });
 
-    afterEach(() => {
+    afterEach(async () => {
+      // Clean up Mercury connections and internal state
+      if (mercury) {
+        try {
+          await mercury.disconnectAll();
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+        // Clear any remaining connection promises
+        if (mercury._connectPromises) {
+          mercury._connectPromises.clear();
+        }
+      }
+
+      // Ensure mock socket is properly closed
+      if (mockWebSocket && typeof mockWebSocket.close === 'function') {
+        try {
+          mockWebSocket.close();
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+      }
+
       if (socketOpenStub) {
         socketOpenStub.restore();
       }
@@ -110,6 +133,9 @@ describe('plugin-mercury', () => {
       if (Socket.getWebSocketConstructor.restore) {
         Socket.getWebSocketConstructor.restore();
       }
+
+      // Small delay to ensure all async operations complete
+      await new Promise((resolve) => setTimeout(resolve, 10));
     });
 
     describe('#listen()', () => {
@@ -268,18 +294,20 @@ describe('plugin-mercury', () => {
             .then(() => {
               assert.calledOnce(Socket.prototype.open);
 
-              return promiseTick(5);
+              // Wait for error handling from 1st failure to schedule 2nd timer
+              return promiseTick(10);
             })
             .then(() => {
               clock.tick(mercury.config.backoffTimeReset);
 
-              return promiseTick(5);
+              // Wait for 2nd socket.open call AND error handling to schedule 3rd timer
+              return promiseTick(10);
             })
             .then(() => {
               assert.calledTwice(Socket.prototype.open);
               clock.tick(2 * mercury.config.backoffTimeReset);
 
-              return promiseTick(5);
+              return promiseTick(10);
             })
             .then(() => {
               assert.calledThrice(Socket.prototype.open);
@@ -354,20 +382,20 @@ describe('plugin-mercury', () => {
             .then(() => {
               assert.calledOnce(Socket.prototype.open);
 
-              // I'm not sure why, but it's important the clock doesn't advance
-              // until a tick happens
-              return promiseTick(5);
+              // Wait for error handling from 1st failure to schedule 2nd timer
+              return promiseTick(10);
             })
             .then(() => {
               clock.tick(mercury.config.backoffTimeReset);
 
-              return promiseTick(5);
+              // Wait for 2nd socket.open call AND error handling to schedule 3rd timer
+              return promiseTick(10);
             })
             .then(() => {
               assert.calledTwice(Socket.prototype.open);
               clock.tick(2 * mercury.config.backoffTimeReset);
 
-              return promiseTick(5);
+              return promiseTick(10);
             })
             .then(() => {
               assert.calledThrice(Socket.prototype.open);
@@ -467,15 +495,49 @@ describe('plugin-mercury', () => {
         // });
 
         describe('when web-high-availability feature is enabled', () => {
-          it('marks current socket url as failed and get new one on Connection Error', () => {
+          it('marks the URL as failed when socket.open() fails with a ConnectionError', () => {
+            // When socket.open() fails, _prepareAndOpenSocket attaches webSocketUrl to the error.
+            // The error handler then uses wsUrl = newWSUrl || reason.webSocketUrl, so markFailedUrl
+            // is called with the URL obtained before the socket open attempt.
             webex.internal.feature.getFeature.returns(Promise.resolve(true));
             socketOpenStub.restore();
             socketOpenStub = sinon.stub(Socket.prototype, 'open').returns(Promise.resolve());
             socketOpenStub.onCall(0).returns(Promise.reject(new ConnectionError({code: 4001})));
             const promise = mercury.connect();
 
-            return promiseTick(7).then(() => {
+            return promiseTick(15).then(() => {
               assert.calledOnce(webex.internal.services.markFailedUrl);
+              assert.calledWith(
+                webex.internal.services.markFailedUrl,
+                sinon.match(/example-2\.com/)
+              );
+              clock.tick(1000);
+
+              return promise;
+            });
+          });
+
+          it('does not mark a URL as failed when no wsUrl is available in ConnectionError', () => {
+            // If the error has no webSocketUrl and newWSUrl is also undefined,
+            // markFailedUrl should not be called.
+            webex.internal.feature.getFeature.returns(Promise.resolve(true));
+
+            const errWithNoUrl = new ConnectionError({code: 4001});
+            // Explicitly ensure no webSocketUrl on the error
+            delete errWithNoUrl.webSocketUrl;
+
+            // Stub _prepareAndOpenSocket so it rejects without attaching webSocketUrl
+            // (simulating a failure before socket.open is reached, e.g. _prepareUrl failure)
+            const prepareAndOpenStub = sinon.stub(mercury, '_prepareAndOpenSocket');
+
+            prepareAndOpenStub.onCall(0).returns(Promise.reject(errWithNoUrl));
+            prepareAndOpenStub.returns(Promise.resolve('ws://example-2.com'));
+
+            const promise = mercury.connect();
+
+            return promiseTick(15).then(() => {
+              assert.notCalled(webex.internal.services.markFailedUrl);
+              prepareAndOpenStub.restore();
               clock.tick(1000);
 
               return promise;
@@ -499,17 +561,22 @@ describe('plugin-mercury', () => {
 
         // skipping due to apparent bug with lolex in all browsers but Chrome.
         skipInBrowser(it)('does not continue attempting to connect', () => {
-          mercury.connect();
+          const promise = mercury.connect();
 
-          return promiseTick(2)
-            .then(() => {
-              clock.tick(6 * webex.internal.mercury.config.backoffTimeReset);
+          // Wait for the connection to be established before proceeding
+          mockWebSocket.open();
 
-              return promiseTick(2);
-            })
-            .then(() => {
-              assert.calledOnce(Socket.prototype.open);
-            });
+          return promise.then(() =>
+            promiseTick(2)
+              .then(() => {
+                clock.tick(6 * webex.internal.mercury.config.backoffTimeReset);
+
+                return promiseTick(2);
+              })
+              .then(() => {
+                assert.calledOnce(Socket.prototype.open);
+              })
+          );
         });
       });
 
@@ -584,11 +651,11 @@ describe('plugin-mercury', () => {
     });
 
     describe('#logout()', () => {
-      it('calls disconnect and logs', () => {
+      it('calls disconnectAll and logs', () => {
         sinon.stub(mercury.logger, 'info');
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.logout();
-        assert.called(mercury.disconnect);
+        assert.called(mercury.disconnectAll);
         assert.calledTwice(mercury.logger.info);
 
         assert.calledWith(mercury.logger.info.getCall(0), 'Mercury: logout() called');
@@ -600,24 +667,24 @@ describe('plugin-mercury', () => {
       });
 
       it('uses the config.beforeLogoutOptionsCloseReason to disconnect and will send code 3050 for logout', () => {
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.config.beforeLogoutOptionsCloseReason = 'done (permanent)';
         mercury.logout();
-        assert.calledWith(mercury.disconnect, {code: 3050, reason: 'done (permanent)'});
+        assert.calledWith(mercury.disconnectAll, {code: 3050, reason: 'done (permanent)'});
       });
 
       it('uses the config.beforeLogoutOptionsCloseReason to disconnect and will send code 3050 for logout if the reason is different than standard', () => {
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.config.beforeLogoutOptionsCloseReason = 'test';
         mercury.logout();
-        assert.calledWith(mercury.disconnect, {code: 3050, reason: 'test'});
+        assert.calledWith(mercury.disconnectAll, {code: 3050, reason: 'test'});
       });
 
       it('uses the config.beforeLogoutOptionsCloseReason to disconnect and will send undefined for logout if the reason is same as standard', () => {
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.config.beforeLogoutOptionsCloseReason = 'done (forced)';
         mercury.logout();
-        assert.calledWith(mercury.disconnect, undefined);
+        assert.calledWith(mercury.disconnectAll, undefined);
       });
     });
 
@@ -723,12 +790,18 @@ describe('plugin-mercury', () => {
           return promiseTick(webex.internal.mercury.config.backoffTimeReset).then(() => {
             // By this time backoffCall and mercury socket should be defined by the
             // 'connect' call
-            assert.isDefined(mercury.backoffCall, 'Mercury backoffCall is not defined');
+            assert.isDefined(
+              mercury.backoffCalls.get('mercury-default-session'),
+              'Mercury backoffCall is not defined'
+            );
             assert.isDefined(mercury.socket, 'Mercury socket is not defined');
             // Calling disconnect will abort the backoffCall, close the socket, and
             // reject the connect
             mercury.disconnect();
-            assert.isUndefined(mercury.backoffCall, 'Mercury backoffCall is still defined');
+            assert.isUndefined(
+              mercury.backoffCalls.get('mercury-default-session'),
+              'Mercury backoffCall is still defined'
+            );
             // The socket will never be unset (which seems bad)
             assert.isDefined(mercury.socket, 'Mercury socket is not defined');
 
@@ -746,16 +819,24 @@ describe('plugin-mercury', () => {
 
           let reason;
 
-          mercury.backoffCall = undefined;
-          mercury._attemptConnection('ws://example.com', (_reason) => {
-            reason = _reason;
-          });
+          mercury.backoffCalls.clear();
+
+          const promise = mercury._attemptConnection(
+            'ws://example.com',
+            'mercury-default-session',
+            (_reason) => {
+              reason = _reason;
+            }
+          );
 
           return promiseTick(webex.internal.mercury.config.backoffTimeReset).then(() => {
             assert.equal(
               reason.message,
-              'Mercury: prevent socket open when backoffCall no longer defined'
+              `Mercury: prevent socket open when backoffCall no longer defined for ${mercury.defaultSessionId}`
             );
+
+            // Ensure the promise was actually rejected (short-circuited)
+            return assert.isRejected(promise);
           });
         });
 
@@ -776,7 +857,10 @@ describe('plugin-mercury', () => {
             return assert.isRejected(promise).then((error) => {
               const lastError = mercury.getLastError();
 
-              assert.equal(error.message, 'Mercury Connection Aborted');
+              assert.equal(
+                error.message,
+                `Mercury Connection Aborted for ${mercury.defaultSessionId}`
+              );
               assert.isDefined(lastError);
               assert.equal(lastError, realError);
             });
@@ -870,7 +954,7 @@ describe('plugin-mercury', () => {
           },
         };
         assert.isUndefined(mercury.mercuryTimeOffset);
-        mercury._setTimeOffset(event);
+        mercury._setTimeOffset('mercury-default-session', event);
         assert.isDefined(mercury.mercuryTimeOffset);
         assert.isTrue(mercury.mercuryTimeOffset > 0);
       });
@@ -880,7 +964,7 @@ describe('plugin-mercury', () => {
             wsWriteTimestamp: Date.now() + 60000,
           },
         };
-        mercury._setTimeOffset(event);
+        mercury._setTimeOffset('mercury-default-session', event);
         assert.isTrue(mercury.mercuryTimeOffset < 0);
       });
       it('handles invalid wsWriteTimestamp', () => {
@@ -891,7 +975,7 @@ describe('plugin-mercury', () => {
               wsWriteTimestamp: invalidTimestamp,
             },
           };
-          mercury._setTimeOffset(event);
+          mercury._setTimeOffset('mercury-default-session', event);
           assert.isUndefined(mercury.mercuryTimeOffset);
         });
       });
@@ -998,13 +1082,15 @@ describe('plugin-mercury', () => {
     describe('shutdown protocol', () => {
       describe('#_handleImminentShutdown()', () => {
         let connectWithBackoffStub;
+        const sessionId = 'mercury-default-session';
 
         beforeEach(() => {
           mercury.connected = true;
-          mercury.socket = {
+          mercury.sockets.set(sessionId, {
             url: 'ws://old-socket.com',
             removeAllListeners: sinon.stub(),
-          };
+          });
+          mercury.socket = mercury.sockets.get(sessionId);
           connectWithBackoffStub = sinon.stub(mercury, '_connectWithBackoff');
           connectWithBackoffStub.returns(Promise.resolve());
           sinon.stub(mercury, '_emit');
@@ -1013,32 +1099,47 @@ describe('plugin-mercury', () => {
         afterEach(() => {
           connectWithBackoffStub.restore();
           mercury._emit.restore();
+          mercury.sockets.clear();
         });
 
         it('should be idempotent - no-op if already in progress', () => {
-          mercury._shutdownSwitchoverInProgress = true;
+          // Simulate an existing switchover in progress by seeding the backoff map
+          mercury._shutdownSwitchoverBackoffCalls.set(sessionId, {placeholder: true});
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
           assert.notCalled(connectWithBackoffStub);
         });
 
         it('should set switchover flags when called', () => {
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
-          assert.isTrue(mercury._shutdownSwitchoverInProgress);
+          // With _connectWithBackoff stubbed, the backoff map entry may not be created here.
+          // Assert that switchover initiation state was set and a shutdown switchover connect was requested.
           assert.isDefined(mercury._shutdownSwitchoverId);
+
+          assert.calledOnce(connectWithBackoffStub);
+          const callArgs = connectWithBackoffStub.firstCall.args;
+          assert.isUndefined(callArgs[0]); // webSocketUrl
+          assert.equal(callArgs[1], sessionId); // sessionId
+          assert.isObject(callArgs[2]); // context
+          assert.isTrue(callArgs[2].isShutdownSwitchover);
+          assert.isObject(callArgs[2].attemptOptions);
+          assert.isTrue(callArgs[2].attemptOptions.isShutdownSwitchover);
         });
 
         it('should call _connectWithBackoff with correct parameters', (done) => {
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
           process.nextTick(() => {
             assert.calledOnce(connectWithBackoffStub);
             const callArgs = connectWithBackoffStub.firstCall.args;
             assert.isUndefined(callArgs[0]); // webSocketUrl
-            assert.isObject(callArgs[1]); // context
-            assert.isTrue(callArgs[1].isShutdownSwitchover);
+            assert.equal(callArgs[1], sessionId); // sessionId
+            assert.isObject(callArgs[2]); // context
+            assert.isTrue(callArgs[2].isShutdownSwitchover);
+            assert.isObject(callArgs[2].attemptOptions);
+            assert.isTrue(callArgs[2].attemptOptions.isShutdownSwitchover);
             done();
           });
         });
@@ -1047,9 +1148,13 @@ describe('plugin-mercury', () => {
           connectWithBackoffStub.restore();
           sinon.stub(mercury, '_connectWithBackoff').throws(new Error('Connection failed'));
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
-          assert.isFalse(mercury._shutdownSwitchoverInProgress);
+          // When an exception happens synchronously, the placeholder entry
+          // should be removed from the map.
+          const switchoverCall = mercury._shutdownSwitchoverBackoffCalls.get(sessionId);
+          assert.isUndefined(switchoverCall);
+          mercury._connectWithBackoff.restore();
         });
       });
 
@@ -1073,10 +1178,15 @@ describe('plugin-mercury', () => {
             },
           };
 
-          const result = mercury._onmessage(shutdownEvent);
+          const result = mercury._onmessage(mercury.defaultSessionId, shutdownEvent);
 
           assert.calledOnce(mercury._handleImminentShutdown);
-          assert.calledWith(mercury._emit, 'event:mercury_shutdown_imminent', shutdownEvent.data);
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'event:mercury_shutdown_imminent',
+            shutdownEvent.data
+          );
           assert.instanceOf(result, Promise);
         });
 
@@ -1087,7 +1197,7 @@ describe('plugin-mercury', () => {
             },
           };
 
-          mercury._onmessage(shutdownEvent);
+          mercury._onmessage(mercury.defaultSessionId, shutdownEvent);
 
           assert.calledOnce(mercury._handleImminentShutdown);
         });
@@ -1102,12 +1212,251 @@ describe('plugin-mercury', () => {
             },
           };
 
-          mercury._onmessage(regularEvent);
+          mercury._onmessage(mercury.defaultSessionId, regularEvent);
 
           assert.notCalled(mercury._handleImminentShutdown);
         });
       });
 
+      describe('#_onmessage() with missing data or eventType', () => {
+        beforeEach(() => {
+          sinon.stub(mercury, '_emit');
+          sinon.stub(mercury, '_setTimeOffset');
+          sinon.stub(mercury, '_applyOverrides');
+        });
+
+        afterEach(() => {
+          mercury._emit.restore();
+          mercury._setTimeOffset.restore();
+          mercury._applyOverrides.restore();
+        });
+
+        it('should not throw when envelope.data is undefined', () => {
+          const event = {
+            data: {
+              type: 'someType',
+              // no nested data property
+            },
+          };
+
+          const result = mercury._onmessage(mercury.defaultSessionId, event);
+
+          assert.instanceOf(result, Promise);
+          assert.calledWith(mercury._emit, mercury.defaultSessionId, 'event', event.data);
+        });
+
+        it('should not throw when data.eventType is undefined', () => {
+          const event = {
+            data: {
+              type: 'someType',
+              data: {
+                // no eventType property
+                someField: 'value',
+              },
+            },
+          };
+
+          const result = mercury._onmessage(mercury.defaultSessionId, event);
+
+          assert.instanceOf(result, Promise);
+          assert.calledWith(mercury._emit, mercury.defaultSessionId, 'event', event.data);
+        });
+
+        it('should emit generic event for messages without eventType (e.g. subscription responses)', () => {
+          const event = {
+            data: {
+              id: 'msg-123',
+              sequenceNumber: 5,
+              data: {
+                statusCode: 200,
+              },
+            },
+          };
+
+          const result = mercury._onmessage(mercury.defaultSessionId, event);
+
+          assert.instanceOf(result, Promise);
+          assert.calledOnce(mercury._emit);
+          assert.calledWith(mercury._emit, mercury.defaultSessionId, 'event', event.data);
+        });
+
+        it('should still process messages with a valid eventType', async () => {
+          const event = {
+            data: {
+              data: {
+                eventType: 'conversation.activity',
+              },
+            },
+          };
+
+          await mercury._onmessage(mercury.defaultSessionId, event);
+
+          // Normal flow emits namespace-specific events after processing handlers.
+          // The early-return guard only emits 'event', so asserting these proves the normal path was taken.
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'event:conversation',
+            event.data
+          );
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'event:conversation.activity',
+            event.data
+          );
+        });
+      });
+
+      describe('#_getEventHandlers()', () => {
+        it('should return an empty array when eventType is undefined', () => {
+          const result = mercury._getEventHandlers(undefined);
+
+          assert.deepEqual(result, []);
+        });
+
+        it('should return an empty array when eventType is null', () => {
+          const result = mercury._getEventHandlers(null);
+
+          assert.deepEqual(result, []);
+        });
+
+        it('should return an empty array when eventType is an empty string', () => {
+          const result = mercury._getEventHandlers('');
+
+          assert.deepEqual(result, []);
+        });
+
+        it('should return an empty array when namespace is not registered', () => {
+          const result = mercury._getEventHandlers('unknownNamespace.someEvent');
+
+          assert.deepEqual(result, []);
+        });
+      });
+
+      describe('#_onclose() with code 4000', () => {
+        let mockSocket, anotherSocket;
+
+        beforeEach(() => {
+          mockSocket = {
+            url: 'ws://active-socket.com',
+            removeAllListeners: sinon.stub(),
+          };
+          anotherSocket = {
+            url: 'ws://old-socket.com',
+            removeAllListeners: sinon.stub(),
+          };
+          mercury.socket = mockSocket;
+          mercury.sockets.set(mercury.defaultSessionId, mockSocket);
+          mercury.sessionWebSocketUrls.set(mercury.defaultSessionId, mockSocket.url);
+          mercury.connected = true;
+          sinon.stub(mercury, '_emit');
+          sinon.stub(mercury, '_reconnect');
+          sinon.stub(mercury, 'unset');
+        });
+
+        afterEach(() => {
+          mercury._emit.restore();
+          mercury._reconnect.restore();
+          mercury.unset.restore();
+        });
+
+        it('should not reconnect when active socket is replaced', () => {
+          const closeEvent = {
+            code: 4000,
+            reason: 'Replaced',
+          };
+
+          mercury._onclose(mercury.defaultSessionId, closeEvent, mockSocket);
+
+          assert.calledOnceWithExactly(
+            webex.internal.metrics.submitClientMetrics,
+            'JS_SDK_MERCURY_CLOSE_4000',
+            {
+              fields: {
+                action: 'no_action',
+                close_code: 4000,
+                close_reason: 'Replaced',
+                is_active_socket: true,
+                message_type: 'replaced',
+                session_id: mercury.defaultSessionId,
+              },
+              tags: {
+                action: 'no_action',
+                message_type: 'replaced',
+              },
+            }
+          );
+          assert.calledWith(mercury._emit, mercury.defaultSessionId, 'offline.replaced', closeEvent);
+          assert.notCalled(mercury._reconnect);
+        });
+
+        it('should reconnect active socket when 4000 has an unknown reason', () => {
+          const closeEvent = {
+            code: 4000,
+            reason: 'Unexpected close',
+          };
+
+          mercury._onclose(mercury.defaultSessionId, closeEvent, mockSocket);
+
+          assert.calledOnceWithExactly(
+            webex.internal.metrics.submitClientMetrics,
+            'JS_SDK_MERCURY_CLOSE_4000',
+            {
+              fields: {
+                action: 'reconnect',
+                close_code: 4000,
+                close_reason: 'Unexpected close',
+                is_active_socket: true,
+                message_type: 'other',
+                session_id: mercury.defaultSessionId,
+              },
+              tags: {
+                action: 'reconnect',
+                message_type: 'other',
+              },
+            }
+          );
+          assert.calledWith(mercury._emit, mercury.defaultSessionId, 'offline.transient', closeEvent);
+          assert.calledWith(
+            mercury._reconnect,
+            mockSocket.url,
+            mercury.defaultSessionId
+          );
+        });
+
+        it('should not reconnect a non-active socket with an unknown 4000 reason', () => {
+          const closeEvent = {
+            code: 4000,
+            reason: 'Unexpected close',
+          };
+
+          mercury._onclose(mercury.defaultSessionId, closeEvent, anotherSocket);
+
+          assert.calledOnceWithExactly(
+            webex.internal.metrics.submitClientMetrics,
+            'JS_SDK_MERCURY_CLOSE_4000',
+            {
+              fields: {
+                action: 'ignore_non_active',
+                close_code: 4000,
+                close_reason: 'Unexpected close',
+                is_active_socket: false,
+                message_type: 'other',
+                session_id: mercury.defaultSessionId,
+              },
+              tags: {
+                action: 'ignore_non_active',
+                message_type: 'other',
+              },
+            }
+          );
+          assert.notCalled(mercury._emit);
+          assert.notCalled(mercury._reconnect);
+          assert.isTrue(mercury.connected);
+        });
+      });
+
       describe('#_onclose() with code 4001 (shutdown replacement)', () => {
         let mockSocket, anotherSocket;
 
@@ -1121,6 +1470,7 @@ describe('plugin-mercury', () => {
             removeAllListeners: sinon.stub(),
           };
           mercury.socket = mockSocket;
+          mercury.sockets.set(mercury.defaultSessionId, mockSocket);
           mercury.connected = true;
           sinon.stub(mercury, '_emit');
           sinon.stub(mercury, '_reconnect');
@@ -1139,9 +1489,14 @@ describe('plugin-mercury', () => {
             reason: 'replaced during shutdown',
           };
 
-          mercury._onclose(closeEvent, mockSocket);
+          mercury._onclose(mercury.defaultSessionId, closeEvent, mockSocket);
 
-          assert.calledWith(mercury._emit, 'offline.permanent', closeEvent);
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'offline.permanent',
+            closeEvent
+          );
           assert.notCalled(mercury._reconnect); // No reconnect for 4001 on active socket
           assert.isFalse(mercury.connected);
         });
@@ -1152,9 +1507,14 @@ describe('plugin-mercury', () => {
             reason: 'replaced during shutdown',
           };
 
-          mercury._onclose(closeEvent, anotherSocket);
+          mercury._onclose(mercury.defaultSessionId, closeEvent, anotherSocket);
 
-          assert.calledWith(mercury._emit, 'offline.replaced', closeEvent);
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'offline.replaced',
+            closeEvent
+          );
           assert.notCalled(mercury._reconnect);
           assert.isTrue(mercury.connected); // Should remain connected
           assert.notCalled(mercury.unset);
@@ -1167,15 +1527,26 @@ describe('plugin-mercury', () => {
           };
 
           // Test non-active socket
-          mercury._onclose(closeEvent, anotherSocket);
-          assert.calledWith(mercury._emit, 'offline.replaced', closeEvent);
+          mercury._onclose(mercury.defaultSessionId, closeEvent, anotherSocket);
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'offline.replaced',
+            closeEvent
+          );
 
           // Reset the spy call history
           mercury._emit.resetHistory();
 
           // Test active socket
-          mercury._onclose(closeEvent, mockSocket);
-          assert.calledWith(mercury._emit, 'offline.permanent', closeEvent);
+          mercury.sockets.set(mercury.defaultSessionId, mockSocket);
+          mercury._onclose(mercury.defaultSessionId, closeEvent, mockSocket);
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'offline.permanent',
+            closeEvent
+          );
         });
 
         it('should handle missing sourceSocket parameter (treats as non-active)', () => {
@@ -1184,10 +1555,15 @@ describe('plugin-mercury', () => {
             reason: 'replaced during shutdown',
           };
 
-          mercury._onclose(closeEvent); // No sourceSocket parameter
+          mercury._onclose(mercury.defaultSessionId, closeEvent); // No sourceSocket parameter
 
           // With simplified logic, undefined !== this.socket, so isActiveSocket = false
-          assert.calledWith(mercury._emit, 'offline.replaced', closeEvent);
+          assert.calledWith(
+            mercury._emit,
+            mercury.defaultSessionId,
+            'offline.replaced',
+            closeEvent
+          );
           assert.notCalled(mercury._reconnect);
         });
 
@@ -1198,7 +1574,7 @@ describe('plugin-mercury', () => {
           };
 
           // Close non-active socket (not the active one)
-          mercury._onclose(closeEvent, anotherSocket);
+          mercury._onclose(mercury.defaultSessionId, closeEvent, anotherSocket);
 
           // Verify listeners were removed from the old socket
           // The _onclose method checks if sourceSocket !== this.socket (non-active)
@@ -1213,22 +1589,94 @@ describe('plugin-mercury', () => {
           };
 
           // Close active socket
-          mercury._onclose(closeEvent, mockSocket);
+          mercury._onclose(mercury.defaultSessionId, closeEvent, mockSocket);
 
           // Verify listeners were removed from active socket
           assert.calledOnce(mockSocket.removeAllListeners);
         });
       });
 
+      describe('#_onclose() reconnect URL derivation', () => {
+        const sessionId = 'mercury-default-session';
+        // The URL resolved and stored in _prepareAndOpenSocket (catalog-valid host).
+        const resolvedUrl = 'wss://mercury-connection.wbx2.com/v1/apps/wx2/registrations';
+        // The URL the native socket was actually opened with, after a lower
+        // layer (e.g. the same-site websocket proxy) rewrote it into a
+        // non-catalog host. Reusing this would fail host-catalog validation.
+        const proxiedUrl = 'wss://web.webex.com/webproxy/mercury-connection.wbx2.com/v1/apps/wx2';
+        let sourceSocket;
+
+        beforeEach(() => {
+          sourceSocket = {
+            url: proxiedUrl,
+            removeAllListeners: sinon.stub(),
+          };
+          mercury.socket = sourceSocket;
+          mercury.sockets.set(sessionId, sourceSocket);
+          mercury.sessionWebSocketUrls.set(sessionId, resolvedUrl);
+          mercury.connected = true;
+          sinon.stub(mercury, '_emit');
+          sinon.stub(mercury, '_reconnect');
+          sinon.stub(mercury, 'unset');
+        });
+
+        afterEach(() => {
+          mercury._emit.restore();
+          mercury._reconnect.restore();
+          mercury.unset.restore();
+          mercury.sockets.clear();
+          mercury.sessionWebSocketUrls.clear();
+        });
+
+        [1001, 1005, 1006, 1011].forEach((code) => {
+          it(`reconnects an active socket using the stored resolved URL (not the proxied socket.url) for code ${code}`, () => {
+            mercury._onclose(sessionId, {code, reason: 'transient'}, sourceSocket);
+
+            assert.calledOnceWithExactly(mercury._reconnect, resolvedUrl, sessionId);
+            assert.neverCalledWith(mercury._reconnect, proxiedUrl, sessionId);
+          });
+        });
+
+        it('reconnects using the stored resolved URL for a normal close (1000) with a reconnect reason', () => {
+          mercury._onclose(sessionId, {code: 1000, reason: 'done (forced)'}, sourceSocket);
+
+          assert.calledOnceWithExactly(mercury._reconnect, resolvedUrl, sessionId);
+        });
+
+        it('does not reconnect when a non-active (old) socket closes', () => {
+          const oldSocket = {
+            url: proxiedUrl,
+            removeAllListeners: sinon.stub(),
+          };
+
+          mercury._onclose(sessionId, {code: 1006, reason: 'transient'}, oldSocket);
+
+          assert.notCalled(mercury._reconnect);
+        });
+      });
+
+      describe('#disconnectAll()', () => {
+        it('clears sessionWebSocketUrls along with the other session state', async () => {
+          mercury.sessionWebSocketUrls.set('mercury-default-session', 'ws://example.com');
+          mercury.sessionWebSocketUrls.set('llm-session', 'ws://example-2.com');
+
+          await mercury.disconnectAll();
+
+          assert.equal(mercury.sessionWebSocketUrls.size, 0);
+        });
+      });
+
       describe('shutdown switchover with retry logic', () => {
         let connectWithBackoffStub;
+        const sessionId = 'mercury-default-session';
 
         beforeEach(() => {
           mercury.connected = true;
-          mercury.socket = {
+          mercury.sockets.set(sessionId, {
             url: 'ws://old-socket.com',
             removeAllListeners: sinon.stub(),
-          };
+          });
+          mercury.socket = mercury.sockets.get(sessionId);
           connectWithBackoffStub = sinon.stub(mercury, '_connectWithBackoff');
           sinon.stub(mercury, '_emit');
         });
@@ -1236,39 +1684,46 @@ describe('plugin-mercury', () => {
         afterEach(() => {
           connectWithBackoffStub.restore();
           mercury._emit.restore();
+          mercury.sockets.clear();
         });
 
         it('should call _connectWithBackoff with shutdown switchover context', (done) => {
           connectWithBackoffStub.returns(Promise.resolve());
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
-          // Give it a tick for the async call to happen
           process.nextTick(() => {
             assert.calledOnce(connectWithBackoffStub);
             const callArgs = connectWithBackoffStub.firstCall.args;
 
-            assert.isUndefined(callArgs[0]); // webSocketUrl is undefined
-            assert.isObject(callArgs[1]); // context object
-            assert.isTrue(callArgs[1].isShutdownSwitchover);
-            assert.isObject(callArgs[1].attemptOptions);
-            assert.isTrue(callArgs[1].attemptOptions.isShutdownSwitchover);
+            assert.isUndefined(callArgs[0]); // webSocketUrl
+            assert.equal(callArgs[1], sessionId);
+            assert.isObject(callArgs[2]);
+            assert.isTrue(callArgs[2].isShutdownSwitchover);
+            assert.isObject(callArgs[2].attemptOptions);
+            assert.isTrue(callArgs[2].attemptOptions.isShutdownSwitchover);
             done();
           });
         });
 
         it('should set _shutdownSwitchoverInProgress flag during switchover', () => {
-          connectWithBackoffStub.returns(new Promise(() => {})); // Never resolves
+          // With the new behavior, "in progress" is represented by the presence
+          // of an entry in _shutdownSwitchoverBackoffCalls.
+          // Since _connectWithBackoff is stubbed in this suite, simulate its side-effect
+          // of seeding the backoff-call map entry.
+          connectWithBackoffStub.callsFake(() => {
+            mercury._shutdownSwitchoverBackoffCalls.set(sessionId, {placeholder: true});
+            return new Promise(() => {}); // Never resolves
+          });
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
-          assert.isTrue(mercury._shutdownSwitchoverInProgress);
+          const switchoverBackoffCall = mercury._shutdownSwitchoverBackoffCalls.get(sessionId);
+          assert.isOk(switchoverBackoffCall);
         });
 
         it('should emit success event when switchover completes', async () => {
-          // We need to actually call the onSuccess callback to trigger the event
-          connectWithBackoffStub.callsFake((url, context) => {
-            // Simulate successful connection by calling onSuccess
+          connectWithBackoffStub.callsFake((url, sid, context) => {
             if (context && context.attemptOptions && context.attemptOptions.onSuccess) {
               const mockSocket = {url: 'ws://new-socket.com'};
               context.attemptOptions.onSuccess(mockSocket, 'ws://new-socket.com');
@@ -1276,14 +1731,15 @@ describe('plugin-mercury', () => {
             return Promise.resolve();
           });
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
-          // Wait for async operations
           await promiseTick(50);
 
           const emitCalls = mercury._emit.getCalls();
           const hasCompleteEvent = emitCalls.some(
-            (call) => call.args[0] === 'event:mercury_shutdown_switchover_complete'
+            (call) =>
+              call.args[0] === sessionId &&
+              call.args[1] === 'event:mercury_shutdown_switchover_complete'
           );
 
           assert.isTrue(hasCompleteEvent, 'Should emit switchover complete event');
@@ -1294,16 +1750,16 @@ describe('plugin-mercury', () => {
 
           connectWithBackoffStub.returns(Promise.reject(testError));
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
           await promiseTick(50);
 
-          // Check if failure event was emitted
           const emitCalls = mercury._emit.getCalls();
           const hasFailureEvent = emitCalls.some(
             (call) =>
-              call.args[0] === 'event:mercury_shutdown_switchover_failed' &&
-              call.args[1] &&
-              call.args[1].reason === testError
+              call.args[0] === sessionId &&
+              call.args[1] === 'event:mercury_shutdown_switchover_failed' &&
+              call.args[2] &&
+              call.args[2].reason === testError
           );
 
           assert.isTrue(hasFailureEvent, 'Should emit switchover failed event');
@@ -1312,10 +1768,9 @@ describe('plugin-mercury', () => {
         it('should allow old socket to be closed by server after switchover failure', async () => {
           connectWithBackoffStub.returns(Promise.reject(new Error('Failed')));
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
           await promiseTick(50);
 
-          // Old socket should not be closed immediately - server will close it
           assert.equal(mercury.socket.removeAllListeners.callCount, 0);
         });
       });
@@ -1399,6 +1854,16 @@ describe('plugin-mercury', () => {
           assert.equal(result, 'ws://example.com');
         });
 
+        it('stores the resolved (pre-proxy) URL under the sessionId in sessionWebSocketUrls', async () => {
+          const sessionId = 'llm-session';
+
+          await mercury._prepareAndOpenSocket(mockSocket, 'ws://original.com', sessionId);
+
+          // The stored value is the URL resolved by _prepareUrl, not the raw
+          // input, so _onclose can later reconnect from a catalog-valid host.
+          assert.equal(mercury.sessionWebSocketUrls.get(sessionId), 'ws://example.com');
+        });
+
         it('should handle errors during socket open', async () => {
           mockSocket.open.returns(Promise.reject(new Error('Open failed')));
 
@@ -1407,23 +1872,22 @@ describe('plugin-mercury', () => {
             assert.fail('Should have thrown an error');
           } catch (err) {
             assert.equal(err.message, 'Open failed');
+            assert.equal(err.webSocketUrl, 'ws://example.com');
           }
         });
       });
 
       describe('#_attemptConnection() with shutdown switchover', () => {
-        let mockSocket, prepareAndOpenSocketStub, callback;
+        let prepareAndOpenSocketStub, callback;
+        const sessionId = 'mercury-default-session';
 
         beforeEach(() => {
-          mockSocket = {
-            url: 'ws://test.com',
-          };
           prepareAndOpenSocketStub = sinon
             .stub(mercury, '_prepareAndOpenSocket')
             .returns(Promise.resolve('ws://new-socket.com'));
           callback = sinon.stub();
-          mercury._shutdownSwitchoverBackoffCall = {}; // Mock backoff call
-          mercury.socket = mockSocket;
+          mercury._shutdownSwitchoverBackoffCalls.set(sessionId, {abort: sinon.stub()});
+          mercury.socket = {url: 'ws://test.com'};
           mercury.connected = true;
           sinon.stub(mercury, '_emit');
           sinon.stub(mercury, '_attachSocketEventListeners');
@@ -1433,28 +1897,26 @@ describe('plugin-mercury', () => {
           prepareAndOpenSocketStub.restore();
           mercury._emit.restore();
           mercury._attachSocketEventListeners.restore();
+          mercury._shutdownSwitchoverBackoffCalls.clear();
         });
 
         it('should not set socket reference before opening for shutdown switchover', async () => {
           const originalSocket = mercury.socket;
 
-          await mercury._attemptConnection('ws://test.com', callback, {
+          await mercury._attemptConnection('ws://test.com', sessionId, callback, {
             isShutdownSwitchover: true,
             onSuccess: (newSocket, url) => {
-              // During onSuccess, verify original socket is still set
-              // (socket swap happens inside onSuccess callback in _handleImminentShutdown)
               assert.equal(mercury.socket, originalSocket);
             },
           });
 
-          // After onSuccess, socket should still be original since we only swap in _handleImminentShutdown
           assert.equal(mercury.socket, originalSocket);
         });
 
         it('should call onSuccess callback with new socket and URL for shutdown', async () => {
           const onSuccessStub = sinon.stub();
 
-          await mercury._attemptConnection('ws://test.com', callback, {
+          await mercury._attemptConnection('ws://test.com', sessionId, callback, {
             isShutdownSwitchover: true,
             onSuccess: onSuccessStub,
           });
@@ -1464,20 +1926,18 @@ describe('plugin-mercury', () => {
         });
 
         it('should emit shutdown switchover complete event', async () => {
-          const oldSocket = mercury.socket;
-
-          await mercury._attemptConnection('ws://test.com', callback, {
+          await mercury._attemptConnection('ws://test.com', sessionId, callback, {
             isShutdownSwitchover: true,
             onSuccess: (newSocket, url) => {
-              // Simulate the onSuccess callback behavior
               mercury.socket = newSocket;
               mercury.connected = true;
-              mercury._emit('event:mercury_shutdown_switchover_complete', {url});
+              mercury._emit(sessionId, 'event:mercury_shutdown_switchover_complete', {url});
             },
           });
 
           assert.calledWith(
             mercury._emit,
+            sessionId,
             'event:mercury_shutdown_switchover_complete',
             sinon.match.has('url', 'ws://new-socket.com')
           );
@@ -1486,23 +1946,20 @@ describe('plugin-mercury', () => {
         it('should use simpler error handling for shutdown switchover failures', async () => {
           prepareAndOpenSocketStub.returns(Promise.reject(new Error('Connection failed')));
 
-          try {
-            await mercury._attemptConnection('ws://test.com', callback, {
+          await mercury
+            ._attemptConnection('ws://test.com', sessionId, callback, {
               isShutdownSwitchover: true,
-            });
-          } catch (err) {
-            // Error should be caught and passed to callback
-          }
+            })
+            .catch(() => {});
 
-          // Should call callback with error for retry
           assert.calledOnce(callback);
           assert.instanceOf(callback.firstCall.args[0], Error);
         });
 
         it('should check _shutdownSwitchoverBackoffCall for shutdown connections', () => {
-          mercury._shutdownSwitchoverBackoffCall = undefined;
+          mercury._shutdownSwitchoverBackoffCalls.clear();
 
-          const result = mercury._attemptConnection('ws://test.com', callback, {
+          const result = mercury._attemptConnection('ws://test.com', sessionId, callback, {
             isShutdownSwitchover: true,
           });
 
@@ -1514,35 +1971,28 @@ describe('plugin-mercury', () => {
       });
 
       describe('#_connectWithBackoff() with shutdown switchover', () => {
-        // Note: These tests verify the parameterization logic without running real backoff timers
-        // to avoid test hangs. The backoff mechanism itself is tested in other test suites.
+        const sessionId = 'mercury-default-session';
 
         it('should use shutdown-specific parameters when called', () => {
-          // Stub _connectWithBackoff to prevent real execution
           const connectWithBackoffStub = sinon
             .stub(mercury, '_connectWithBackoff')
             .returns(Promise.resolve());
 
-          mercury._handleImminentShutdown();
+          mercury._handleImminentShutdown(sessionId);
 
-          // Verify it was called with shutdown context
           assert.calledOnce(connectWithBackoffStub);
           const callArgs = connectWithBackoffStub.firstCall.args;
-          assert.isObject(callArgs[1]); // context
-          assert.isTrue(callArgs[1].isShutdownSwitchover);
+          assert.equal(callArgs[1], sessionId);
+          assert.isObject(callArgs[2]);
+          assert.isTrue(callArgs[2].isShutdownSwitchover);
 
           connectWithBackoffStub.restore();
         });
 
         it('should pass shutdown switchover options to _attemptConnection', () => {
-          // Stub _attemptConnection to verify it receives correct options
           const attemptStub = sinon.stub(mercury, '_attemptConnection');
-          attemptStub.callsFake((url, callback) => {
-            // Immediately succeed
-            callback();
-          });
+          attemptStub.callsFake((url, sid, cb) => cb());
 
-          // Call _connectWithBackoff with shutdown context
           const context = {
             isShutdownSwitchover: true,
             attemptOptions: {
@@ -1551,34 +2001,30 @@ describe('plugin-mercury', () => {
             },
           };
 
-          // Start the backoff
-          const promise = mercury._connectWithBackoff(undefined, context);
+          const promise = mercury._connectWithBackoff(undefined, sessionId, context);
 
-          // Check that _attemptConnection was called with shutdown options
           return promise.then(() => {
             assert.calledOnce(attemptStub);
             const callArgs = attemptStub.firstCall.args;
-            assert.isObject(callArgs[2]); // options parameter
-            assert.isTrue(callArgs[2].isShutdownSwitchover);
-
+            assert.equal(callArgs[1], sessionId);
+            assert.isObject(callArgs[3]);
+            assert.isTrue(callArgs[3].isShutdownSwitchover);
             attemptStub.restore();
           });
         });
 
         it('should set and clear state flags appropriately', () => {
-          // Stub to prevent actual connection
-          sinon.stub(mercury, '_attemptConnection').callsFake((url, callback) => callback());
+          sinon.stub(mercury, '_attemptConnection').callsFake((url, sid, cb) => cb());
 
-          mercury._shutdownSwitchoverInProgress = true;
+          mercury._shutdownSwitchoverBackoffCalls.set(sessionId, {placeholder: true});
 
-          const promise = mercury._connectWithBackoff(undefined, {
+          const promise = mercury._connectWithBackoff(undefined, sessionId, {
             isShutdownSwitchover: true,
             attemptOptions: {isShutdownSwitchover: true, onSuccess: () => {}},
           });
 
           return promise.then(() => {
-            // Should be cleared after completion
-            assert.isFalse(mercury._shutdownSwitchoverInProgress);
+            assert.isUndefined(mercury._shutdownSwitchoverBackoffCalls.get(sessionId));
             mercury._attemptConnection.restore();
           });
         });
@@ -1586,32 +2032,30 @@ describe('plugin-mercury', () => {
 
       describe('#disconnect() with shutdown switchover in progress', () => {
         let abortStub;
+        const sessionId = 'mercury-default-session';
 
         beforeEach(() => {
-          mercury.socket = {
+          mercury.sockets.clear();
+          mercury.sockets.set(sessionId, {
             close: sinon.stub().returns(Promise.resolve()),
             removeAllListeners: sinon.stub(),
-          };
+          });
           abortStub = sinon.stub();
-          mercury._shutdownSwitchoverBackoffCall = {
-            abort: abortStub,
-          };
+          mercury._shutdownSwitchoverBackoffCalls.set(sessionId, {abort: abortStub});
         });
 
         it('should abort shutdown switchover backoff call on disconnect', async () => {
-          await mercury.disconnect();
+          await mercury.disconnect(undefined, sessionId);
 
           assert.calledOnce(abortStub);
         });
 
         it('should handle disconnect when no switchover is in progress', async () => {
-          mercury._shutdownSwitchoverBackoffCall = undefined;
+          mercury._shutdownSwitchoverBackoffCalls.clear();
 
-          // Should not throw
-          await mercury.disconnect();
+          await mercury.disconnect(undefined, sessionId);
 
-          // Should still close the socket
-          assert.calledOnce(mercury.socket.close);
+          assert.calledOnce(mercury.sockets.get(sessionId).close);
         });
       });
     });