@webex/internal-plugin-mercury 3.9.0 → 3.10.0

package/dist/mercury.js

@@ -11,11 +11,11 @@ _Object$defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
+var _now = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/date/now"));
 var _promise = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/promise"));
 var _keys = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/keys"));
 var _assign = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/assign"));
 var _deleteProperty = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/reflect/delete-property"));
-var _now = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/date/now"));
 var _getOwnPropertyDescriptor = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/get-own-property-descriptor"));
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/defineProperty"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/slicedToArray"));
@@ -79,6 +79,109 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
         _this.webex.internal.feature.updateFeature(envelope.data.featureToggle);
       }
     });
+    /*
+     * When Cluster Migrations, notify clients using ActiveClusterStatusEvent via mercury
+     * https://wwwin-github.cisco.com/pages/Webex/crr-docs/techdocs/rr-002.html#wip-notifying-clients-of-cluster-migrations
+     * */
+    this.on('event:ActiveClusterStatusEvent', function (envelope) {
+      var _this$webex$internal$;
+      if (typeof ((_this$webex$internal$ = _this.webex.internal.services) === null || _this$webex$internal$ === void 0 ? void 0 : _this$webex$internal$.switchActiveClusterIds) === 'function' && envelope && envelope.data) {
+        var _envelope$data;
+        _this.webex.internal.services.switchActiveClusterIds((_envelope$data = envelope.data) === null || _envelope$data === void 0 ? void 0 : _envelope$data.activeClusters);
+      }
+    });
+    /*
+     * Using cache-invalidation via mercury to instead the method of polling via the new /timestamp endpoint from u2c
+     * https://wwwin-github.cisco.com/pages/Webex/crr-docs/techdocs/rr-005.html#websocket-notifications
+     * */
+    this.on('event:u2c.cache-invalidation', function (envelope) {
+      var _this$webex$internal$2;
+      if (typeof ((_this$webex$internal$2 = _this.webex.internal.services) === null || _this$webex$internal$2 === void 0 ? void 0 : _this$webex$internal$2.invalidateCache) === 'function' && envelope && envelope.data) {
+        var _envelope$data2;
+        _this.webex.internal.services.invalidateCache((_envelope$data2 = envelope.data) === null || _envelope$data2 === void 0 ? void 0 : _envelope$data2.timestamp);
+      }
+    });
+  },
+  /**
+   * Attach event listeners to a socket.
+   * @param {Socket} socket - The socket to attach listeners to
+   * @returns {void}
+   */
+  _attachSocketEventListeners: function _attachSocketEventListeners(socket) {
+    var _this2 = this;
+    socket.on('close', function (event) {
+      return _this2._onclose(event, socket);
+    });
+    socket.on('message', function () {
+      return _this2._onmessage.apply(_this2, arguments);
+    });
+    socket.on('pong', function () {
+      return _this2._setTimeOffset.apply(_this2, arguments);
+    });
+    socket.on('sequence-mismatch', function () {
+      for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+        args[_key] = arguments[_key];
+      }
+      return _this2._emit.apply(_this2, ['sequence-mismatch'].concat(args));
+    });
+    socket.on('ping-pong-latency', function () {
+      for (var _len2 = arguments.length, args = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
+        args[_key2] = arguments[_key2];
+      }
+      return _this2._emit.apply(_this2, ['ping-pong-latency'].concat(args));
+    });
+  },
+  /**
+   * Handle imminent shutdown by establishing a new connection while keeping
+   * the current one alive (make-before-break).
+   * Idempotent: will no-op if already in progress.
+   * @returns {void}
+   */
+  _handleImminentShutdown: function _handleImminentShutdown() {
+    var _this3 = this;
+    try {
+      if (this._shutdownSwitchoverInProgress) {
+        this.logger.info("".concat(this.namespace, ": [shutdown] switchover already in progress"));
+        return;
+      }
+      this._shutdownSwitchoverInProgress = true;
+      this._shutdownSwitchoverId = "".concat((0, _now.default)());
+      this.logger.info("".concat(this.namespace, ": [shutdown] switchover start, id=").concat(this._shutdownSwitchoverId));
+      this._connectWithBackoff(undefined, {
+        isShutdownSwitchover: true,
+        attemptOptions: {
+          isShutdownSwitchover: true,
+          onSuccess: function onSuccess(newSocket, webSocketUrl) {
+            _this3.logger.info("".concat(_this3.namespace, ": [shutdown] switchover connected, url: ").concat(webSocketUrl));
+            var oldSocket = _this3.socket;
+            // Atomically switch active socket reference
+            _this3.socket = newSocket;
+            _this3.connected = true; // remain connected throughout
+
+            _this3._emit('event:mercury_shutdown_switchover_complete', {
+              url: webSocketUrl
+            });
+            if (oldSocket) {
+              _this3.logger.info("".concat(_this3.namespace, ": [shutdown] old socket retained; server will close with 4001"));
+            }
+          }
+        }
+      }).then(function () {
+        _this3.logger.info("".concat(_this3.namespace, ": [shutdown] switchover completed successfully"));
+      }).catch(function (err) {
+        _this3.logger.info("".concat(_this3.namespace, ": [shutdown] switchover exhausted retries; will fall back to normal reconnection"), err);
+        _this3._emit('event:mercury_shutdown_switchover_failed', {
+          reason: err
+        });
+        // Old socket will eventually close with 4001, triggering normal reconnection
+      });
+    } catch (e) {
+      this.logger.error("".concat(this.namespace, ": [shutdown] error during switchover"), e);
+      this._shutdownSwitchoverInProgress = false;
+      this._emit('event:mercury_shutdown_switchover_failed', {
+        reason: e
+      });
+    }
   },
   /**
    * Get the last error.
@@ -88,7 +191,7 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
     return this.lastError;
   },
   connect: function connect(webSocketUrl) {
-    var _this2 = this;
+    var _this4 = this;
     if (this.connected) {
       this.logger.info("".concat(this.namespace, ": already connected, will not connect again"));
       return _promise.default.resolve();
@@ -97,8 +200,8 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
     this.logger.info("".concat(this.namespace, ": starting connection attempt"));
     this.logger.info("".concat(this.namespace, ": debug_mercury_logging stack: "), new Error('debug_mercury_logging').stack);
     return _promise.default.resolve(this.webex.internal.device.registered || this.webex.internal.device.register()).then(function () {
-      _this2.logger.info("".concat(_this2.namespace, ": connecting"));
-      return _this2._connectWithBackoff(webSocketUrl);
+      _this4.logger.info("".concat(_this4.namespace, ": connecting"));
+      return _this4._connectWithBackoff(webSocketUrl);
     });
   },
   logout: function logout() {
@@ -110,16 +213,20 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
     } : undefined);
   },
   disconnect: function disconnect(options) {
-    var _this3 = this;
+    var _this5 = this;
     return new _promise.default(function (resolve) {
-      if (_this3.backoffCall) {
-        _this3.logger.info("".concat(_this3.namespace, ": aborting connection"));
-        _this3.backoffCall.abort();
+      if (_this5.backoffCall) {
+        _this5.logger.info("".concat(_this5.namespace, ": aborting connection"));
+        _this5.backoffCall.abort();
+      }
+      if (_this5._shutdownSwitchoverBackoffCall) {
+        _this5.logger.info("".concat(_this5.namespace, ": aborting shutdown switchover"));
+        _this5._shutdownSwitchoverBackoffCall.abort();
       }
-      if (_this3.socket) {
-        _this3.socket.removeAllListeners('message');
-        _this3.once('offline', resolve);
-        resolve(_this3.socket.close(options || undefined));
+      if (_this5.socket) {
+        _this5.socket.removeAllListeners('message');
+        _this5.once('offline', resolve);
+        resolve(_this5.socket.close(options || undefined));
       }
       resolve();
     });
@@ -145,19 +252,19 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
     });
   },
   _prepareUrl: function _prepareUrl(webSocketUrl) {
-    var _this4 = this;
+    var _this6 = this;
     if (!webSocketUrl) {
       webSocketUrl = this.webex.internal.device.webSocketUrl;
     }
     return this.webex.internal.feature.getFeature('developer', 'web-high-availability').then(function (haMessagingEnabled) {
       if (haMessagingEnabled) {
-        return _this4.webex.internal.services.convertUrlToPriorityHostUrl(webSocketUrl);
+        return _this6.webex.internal.services.convertUrlToPriorityHostUrl(webSocketUrl);
       }
       return webSocketUrl;
     }).then(function (wsUrl) {
       webSocketUrl = wsUrl;
     }).then(function () {
-      return _this4.webex.internal.feature.getFeature('developer', 'web-shared-mercury');
+      return _this6.webex.internal.feature.getFeature('developer', 'web-shared-mercury');
     }).then(function (webSharedMercury) {
       webSocketUrl = _url.default.parse(webSocketUrl, true);
       (0, _assign.default)(webSocketUrl.query, {
@@ -172,7 +279,7 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
         });
         (0, _deleteProperty.default)(webSocketUrl.query, 'bufferStates');
       }
-      if ((0, _lodash.get)(_this4, 'webex.config.device.ephemeral', false)) {
+      if ((0, _lodash.get)(_this6, 'webex.config.device.ephemeral', false)) {
         webSocketUrl.query.multipleConnections = true;
       }
       webSocketUrl.query.clientTimestamp = (0, _now.default)();
@@ -180,96 +287,94 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
     });
   },
   _attemptConnection: function _attemptConnection(socketUrl, callback) {
-    var _this5 = this;
+    var _this7 = this;
+    var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    var _options$isShutdownSw = options.isShutdownSwitchover,
+      isShutdownSwitchover = _options$isShutdownSw === void 0 ? false : _options$isShutdownSw,
+      _options$onSuccess = options.onSuccess,
+      onSuccess = _options$onSuccess === void 0 ? null : _options$onSuccess;
     var socket = new _socket.default();
-    var attemptWSUrl;
-    socket.on('close', function () {
-      return _this5._onclose.apply(_this5, arguments);
-    });
-    socket.on('message', function () {
-      return _this5._onmessage.apply(_this5, arguments);
-    });
-    socket.on('pong', function () {
-      return _this5._setTimeOffset.apply(_this5, arguments);
-    });
-    socket.on('sequence-mismatch', function () {
-      for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
-        args[_key] = arguments[_key];
-      }
-      return _this5._emit.apply(_this5, ['sequence-mismatch'].concat(args));
-    });
-    socket.on('ping-pong-latency', function () {
-      for (var _len2 = arguments.length, args = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
-        args[_key2] = arguments[_key2];
-      }
-      return _this5._emit.apply(_this5, ['ping-pong-latency'].concat(args));
-    });
-    _promise.default.all([this._prepareUrl(socketUrl), this.webex.credentials.getUserToken()]).then(function (_ref) {
-      var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
-        webSocketUrl = _ref2[0],
-        token = _ref2[1];
-      if (!_this5.backoffCall) {
-        var msg = "".concat(_this5.namespace, ": prevent socket open when backoffCall no longer defined");
-        _this5.logger.info(msg);
-        return _promise.default.reject(new Error(msg));
-      }
-      attemptWSUrl = webSocketUrl;
-      var options = {
-        forceCloseDelay: _this5.config.forceCloseDelay,
-        pingInterval: _this5.config.pingInterval,
-        pongTimeout: _this5.config.pongTimeout,
-        token: token.toString(),
-        trackingId: "".concat(_this5.webex.sessionId, "_").concat((0, _now.default)()),
-        logger: _this5.logger
-      };
+    var newWSUrl;
+    this._attachSocketEventListeners(socket);
+
+    // Check appropriate backoff call based on connection type
+    if (isShutdownSwitchover && !this._shutdownSwitchoverBackoffCall) {
+      var msg = "".concat(this.namespace, ": prevent socket open when switchover backoff call no longer defined");
+      var err = new Error(msg);
+      this.logger.info(msg);
+
+      // Call the callback with the error before rejecting
+      callback(err);
+      return _promise.default.reject(err);
+    }
+    if (!isShutdownSwitchover && !this.backoffCall) {
+      var _msg = "".concat(this.namespace, ": prevent socket open when backoffCall no longer defined");
+      var _err = new Error(_msg);
+      this.logger.info(_msg);
+
+      // Call the callback with the error before rejecting
+      callback(_err);
+      return _promise.default.reject(_err);
+    }
+
+    // For shutdown switchover, don't set socket yet (make-before-break)
+    // For normal connection, set socket before opening to allow disconnect() to close it
+    if (!isShutdownSwitchover) {
+      this.socket = socket;
+    }
+    return this._prepareAndOpenSocket(socket, socketUrl, isShutdownSwitchover).then(function (webSocketUrl) {
+      newWSUrl = webSocketUrl;
+      _this7.logger.info("".concat(_this7.namespace, ": ").concat(isShutdownSwitchover ? '[shutdown] switchover' : '', " connected to mercury, success, action: connected, url: ").concat(newWSUrl));
 
-      // if the consumer has supplied request options use them
-      if (_this5.webex.config.defaultMercuryOptions) {
-        _this5.logger.info("".concat(_this5.namespace, ": setting custom options"));
-        options = _objectSpread(_objectSpread({}, options), _this5.webex.config.defaultMercuryOptions);
+      // Custom success handler for shutdown switchover
+      if (onSuccess) {
+        onSuccess(socket, webSocketUrl);
+        callback();
+        return _promise.default.resolve();
       }
 
-      // Set the socket before opening it. This allows a disconnect() to close
-      // the socket if it is in the process of being opened.
-      _this5.socket = socket;
-      _this5.logger.info("".concat(_this5.namespace, " connection url: ").concat(webSocketUrl));
-      return socket.open(webSocketUrl, options);
-    }).then(function () {
-      _this5.logger.info("".concat(_this5.namespace, ": connected to mercury, success, action: connected, url: ").concat(attemptWSUrl));
+      // Default behavior for normal connection
       callback();
-      return _this5.webex.internal.feature.getFeature('developer', 'web-high-availability').then(function (haMessagingEnabled) {
+      return _this7.webex.internal.feature.getFeature('developer', 'web-high-availability').then(function (haMessagingEnabled) {
         if (haMessagingEnabled) {
-          return _this5.webex.internal.device.refresh();
+          return _this7.webex.internal.device.refresh();
         }
         return _promise.default.resolve();
       });
     }).catch(function (reason) {
-      var _this5$backoffCall, _this5$backoffCall3;
-      _this5.lastError = reason; // remember the last error
+      var _this7$backoffCall, _this7$backoffCall3;
+      // For shutdown, simpler error handling - just callback for retry
+      if (isShutdownSwitchover) {
+        _this7.logger.info("".concat(_this7.namespace, ": [shutdown] switchover attempt failed"), reason);
+        return callback(reason);
+      }
+
+      // Normal connection error handling (existing complex logic)
+      _this7.lastError = reason; // remember the last error
 
       // Suppress connection errors that appear to be network related. This
       // may end up suppressing metrics during outages, but we might not care
       // (especially since many of our outages happen in a way that client
       // metrics can't be trusted).
-      if (reason.code !== 1006 && _this5.backoffCall && ((_this5$backoffCall = _this5.backoffCall) === null || _this5$backoffCall === void 0 ? void 0 : _this5$backoffCall.getNumRetries()) > 0) {
-        var _this5$backoffCall2;
-        _this5._emit('connection_failed', reason, {
-          retries: (_this5$backoffCall2 = _this5.backoffCall) === null || _this5$backoffCall2 === void 0 ? void 0 : _this5$backoffCall2.getNumRetries()
+      if (reason.code !== 1006 && _this7.backoffCall && ((_this7$backoffCall = _this7.backoffCall) === null || _this7$backoffCall === void 0 ? void 0 : _this7$backoffCall.getNumRetries()) > 0) {
+        var _this7$backoffCall2;
+        _this7._emit('connection_failed', reason, {
+          retries: (_this7$backoffCall2 = _this7.backoffCall) === null || _this7$backoffCall2 === void 0 ? void 0 : _this7$backoffCall2.getNumRetries()
         });
       }
-      _this5.logger.info("".concat(_this5.namespace, ": connection attempt failed"), reason, ((_this5$backoffCall3 = _this5.backoffCall) === null || _this5$backoffCall3 === void 0 ? void 0 : _this5$backoffCall3.getNumRetries()) === 0 ? reason.stack : '');
+      _this7.logger.info("".concat(_this7.namespace, ": connection attempt failed"), reason, ((_this7$backoffCall3 = _this7.backoffCall) === null || _this7$backoffCall3 === void 0 ? void 0 : _this7$backoffCall3.getNumRetries()) === 0 ? reason.stack : '');
       // UnknownResponse is produced by IE for any 4XXX; treated it like a bad
       // web socket url and let WDM handle the token checking
       if (reason instanceof _errors.UnknownResponse) {
-        _this5.logger.info("".concat(_this5.namespace, ": received unknown response code, refreshing device registration"));
-        return _this5.webex.internal.device.refresh().then(function () {
+        _this7.logger.info("".concat(_this7.namespace, ": received unknown response code, refreshing device registration"));
+        return _this7.webex.internal.device.refresh().then(function () {
           return callback(reason);
         });
       }
       // NotAuthorized implies expired token
       if (reason instanceof _errors.NotAuthorized) {
-        _this5.logger.info("".concat(_this5.namespace, ": received authorization error, reauthorizing"));
-        return _this5.webex.credentials.refresh({
+        _this7.logger.info("".concat(_this7.namespace, ": received authorization error, reauthorizing"));
+        return _this7.webex.credentials.refresh({
           force: true
         }).then(function () {
           return callback(reason);
@@ -284,15 +389,15 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
       // BadRequest implies current credentials are for a Service Account
       // Forbidden implies current user is not entitle for Webex
       if (reason instanceof _errors.BadRequest || reason instanceof _errors.Forbidden) {
-        _this5.logger.warn("".concat(_this5.namespace, ": received unrecoverable response from mercury"));
-        _this5.backoffCall.abort();
+        _this7.logger.warn("".concat(_this7.namespace, ": received unrecoverable response from mercury"));
+        _this7.backoffCall.abort();
         return callback(reason);
       }
       if (reason instanceof _errors.ConnectionError) {
-        return _this5.webex.internal.feature.getFeature('developer', 'web-high-availability').then(function (haMessagingEnabled) {
+        return _this7.webex.internal.feature.getFeature('developer', 'web-high-availability').then(function (haMessagingEnabled) {
           if (haMessagingEnabled) {
-            _this5.logger.info("".concat(_this5.namespace, ": received a generic connection error, will try to connect to another datacenter. failed, action: 'failed', url: ").concat(attemptWSUrl, " error: ").concat(reason.message));
-            return _this5.webex.internal.services.markFailedUrl(attemptWSUrl);
+            _this7.logger.info("".concat(_this7.namespace, ": received a generic connection error, will try to connect to another datacenter. failed, action: 'failed', url: ").concat(newWSUrl, " error: ").concat(reason.message));
+            return _this7.webex.internal.services.markFailedUrl(newWSUrl);
           }
           return null;
         }).then(function () {
@@ -301,63 +406,116 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
       }
       return callback(reason);
     }).catch(function (reason) {
-      _this5.logger.error("".concat(_this5.namespace, ": failed to handle connection failure"), reason);
+      _this7.logger.error("".concat(_this7.namespace, ": failed to handle connection failure"), reason);
       callback(reason);
     });
   },
+  _prepareAndOpenSocket: function _prepareAndOpenSocket(socket, socketUrl) {
+    var _this8 = this;
+    var isShutdownSwitchover = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
+    var logPrefix = isShutdownSwitchover ? '[shutdown] switchover' : 'connection';
+    return _promise.default.all([this._prepareUrl(socketUrl), this.webex.credentials.getUserToken()]).then(function (_ref) {
+      var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
+        webSocketUrl = _ref2[0],
+        token = _ref2[1];
+      var options = {
+        forceCloseDelay: _this8.config.forceCloseDelay,
+        pingInterval: _this8.config.pingInterval,
+        pongTimeout: _this8.config.pongTimeout,
+        token: token.toString(),
+        trackingId: "".concat(_this8.webex.sessionId, "_").concat((0, _now.default)()),
+        logger: _this8.logger
+      };
+      if (_this8.webex.config.defaultMercuryOptions) {
+        var customOptionsMsg = isShutdownSwitchover ? 'setting custom options for switchover' : 'setting custom options';
+        _this8.logger.info("".concat(_this8.namespace, ": ").concat(customOptionsMsg));
+        options = _objectSpread(_objectSpread({}, options), _this8.webex.config.defaultMercuryOptions);
+      }
+      _this8.logger.info("".concat(_this8.namespace, ": ").concat(logPrefix, " url: ").concat(webSocketUrl));
+      return socket.open(webSocketUrl, options).then(function () {
+        return webSocketUrl;
+      });
+    });
+  },
   _connectWithBackoff: function _connectWithBackoff(webSocketUrl) {
-    var _this6 = this;
+    var _this9 = this;
+    var context = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    var _context$isShutdownSw = context.isShutdownSwitchover,
+      isShutdownSwitchover = _context$isShutdownSw === void 0 ? false : _context$isShutdownSw,
+      _context$attemptOptio = context.attemptOptions,
+      attemptOptions = _context$attemptOptio === void 0 ? {} : _context$attemptOptio;
     return new _promise.default(function (resolve, reject) {
       // eslint gets confused about whether or not call is actually used
       // eslint-disable-next-line prefer-const
       var call;
       var onComplete = function onComplete(err) {
-        _this6.connecting = false;
-        _this6.backoffCall = undefined;
+        // Clear state flags based on connection type
+        if (isShutdownSwitchover) {
+          _this9._shutdownSwitchoverInProgress = false;
+          _this9._shutdownSwitchoverBackoffCall = undefined;
+        } else {
+          _this9.connecting = false;
+          _this9.backoffCall = undefined;
+        }
         if (err) {
-          _this6.logger.info("".concat(_this6.namespace, ": failed to connect after ").concat(call.getNumRetries(), " retries; log statement about next retry was inaccurate; ").concat(err));
+          var msg = isShutdownSwitchover ? "[shutdown] switchover failed after ".concat(call.getNumRetries(), " retries") : "failed to connect after ".concat(call.getNumRetries(), " retries");
+          _this9.logger.info("".concat(_this9.namespace, ": ").concat(msg, "; log statement about next retry was inaccurate; ").concat(err));
           return reject(err);
         }
-        _this6.connected = true;
-        _this6.hasEverConnected = true;
-        _this6._emit('online');
-        _this6.webex.internal.newMetrics.callDiagnosticMetrics.setMercuryConnectedStatus(true);
+
+        // Default success handling for normal connections
+        if (!isShutdownSwitchover) {
+          _this9.connected = true;
+          _this9.hasEverConnected = true;
+          _this9._emit('online');
+          _this9.webex.internal.newMetrics.callDiagnosticMetrics.setMercuryConnectedStatus(true);
+        }
         return resolve();
       };
 
       // eslint-disable-next-line prefer-reflect
       call = _backoff.default.call(function (callback) {
-        _this6.logger.info("".concat(_this6.namespace, ": executing connection attempt ").concat(call.getNumRetries()));
-        _this6._attemptConnection(webSocketUrl, callback);
+        var attemptNum = call.getNumRetries();
+        var logPrefix = isShutdownSwitchover ? '[shutdown] switchover' : 'connection';
+        _this9.logger.info("".concat(_this9.namespace, ": executing ").concat(logPrefix, " attempt ").concat(attemptNum));
+        _this9._attemptConnection(webSocketUrl, callback, attemptOptions);
       }, onComplete);
       call.setStrategy(new _backoff.default.ExponentialStrategy({
-        initialDelay: _this6.config.backoffTimeReset,
-        maxDelay: _this6.config.backoffTimeMax
+        initialDelay: _this9.config.backoffTimeReset,
+        maxDelay: _this9.config.backoffTimeMax
       }));
-      if (_this6.config.initialConnectionMaxRetries && !_this6.hasEverConnected) {
-        call.failAfter(_this6.config.initialConnectionMaxRetries);
-      } else if (_this6.config.maxRetries) {
-        call.failAfter(_this6.config.maxRetries);
+      if (_this9.config.initialConnectionMaxRetries && !_this9.hasEverConnected && !isShutdownSwitchover) {
+        call.failAfter(_this9.config.initialConnectionMaxRetries);
+      } else if (_this9.config.maxRetries) {
+        call.failAfter(_this9.config.maxRetries);
       }
       call.on('abort', function () {
-        _this6.logger.info("".concat(_this6.namespace, ": connection aborted"));
-        reject(new Error('Mercury Connection Aborted'));
+        var msg = isShutdownSwitchover ? 'Shutdown Switchover' : 'Connection';
+        _this9.logger.info("".concat(_this9.namespace, ": ").concat(msg, " aborted"));
+        reject(new Error("Mercury ".concat(msg, " Aborted")));
       });
       call.on('callback', function (err) {
         if (err) {
           var number = call.getNumRetries();
-          var delay = Math.min(call.strategy_.nextBackoffDelay_, _this6.config.backoffTimeMax);
-          _this6.logger.info("".concat(_this6.namespace, ": failed to connect; attempting retry ").concat(number + 1, " in ").concat(delay, " ms"));
+          var delay = Math.min(call.strategy_.nextBackoffDelay_, _this9.config.backoffTimeMax);
+          var logPrefix = isShutdownSwitchover ? '[shutdown] switchover' : '';
+          _this9.logger.info("".concat(_this9.namespace, ": ").concat(logPrefix, " failed to connect; attempting retry ").concat(number + 1, " in ").concat(delay, " ms"));
           /* istanbul ignore if */
           if (process.env.NODE_ENV === 'development') {
-            _this6.logger.debug("".concat(_this6.namespace, ": "), err, err.stack);
+            _this9.logger.debug("".concat(_this9.namespace, ": "), err, err.stack);
           }
           return;
         }
-        _this6.logger.info("".concat(_this6.namespace, ": connected"));
+        _this9.logger.info("".concat(_this9.namespace, ": connected"));
       });
+
+      // Store backoff call reference BEFORE starting (so it's available in _attemptConnection)
+      if (isShutdownSwitchover) {
+        _this9._shutdownSwitchoverBackoffCall = call;
+      } else {
+        _this9.backoffCall = call;
+      }
       call.start();
-      _this6.backoffCall = call;
     });
   },
   _emit: function _emit() {
@@ -388,36 +546,74 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
     }
     return handlers;
   },
-  _onclose: function _onclose(event) {
+  _onclose: function _onclose(event, sourceSocket) {
     // I don't see any way to avoid the complexity or statement count in here.
     /* eslint complexity: [0] */
 
     try {
+      var isActiveSocket = sourceSocket === this.socket;
       var reason = event.reason && event.reason.toLowerCase();
-      var socketUrl = this.socket.url;
-      this.socket.removeAllListeners();
-      this.unset('socket');
-      this.connected = false;
-      this._emit('offline', event);
-      this.webex.internal.newMetrics.callDiagnosticMetrics.setMercuryConnectedStatus(false);
+      var socketUrl;
+      if (isActiveSocket && this.socket) {
+        // Active socket closed - get URL from current socket reference
+        socketUrl = this.socket.url;
+      } else if (sourceSocket) {
+        // Old socket closed - get URL from the closed socket
+        socketUrl = sourceSocket.url;
+      }
+      if (isActiveSocket) {
+        // Only tear down state if the currently active socket closed
+        if (this.socket) {
+          this.socket.removeAllListeners();
+        }
+        this.unset('socket');
+        this.connected = false;
+        this._emit('offline', event);
+        this.webex.internal.newMetrics.callDiagnosticMetrics.setMercuryConnectedStatus(false);
+      } else {
+        // Old socket closed; do not flip connection state
+        this.logger.info("".concat(this.namespace, ": [shutdown] non-active socket closed, code=").concat(event.code));
+        // Clean up listeners from old socket now that it's closed
+        if (sourceSocket) {
+          sourceSocket.removeAllListeners();
+        }
+      }
       switch (event.code) {
         case 1003:
           // metric: disconnect
           this.logger.info("".concat(this.namespace, ": Mercury service rejected last message; will not reconnect: ").concat(event.reason));
-          this._emit('offline.permanent', event);
+          if (isActiveSocket) this._emit('offline.permanent', event);
           break;
         case 4000:
           // metric: disconnect
           this.logger.info("".concat(this.namespace, ": socket replaced; will not reconnect"));
-          this._emit('offline.replaced', event);
+          if (isActiveSocket) this._emit('offline.replaced', event);
+          // If not active, nothing to do
+          break;
+        case 4001:
+          // replaced during shutdown
+          if (isActiveSocket) {
+            // Server closed active socket with 4001, meaning it expected this connection
+            // to be replaced, but the switchover in _handleImminentShutdown failed.
+            // This is a permanent failure - do not reconnect.
+            this.logger.warn("".concat(this.namespace, ": active socket closed with 4001; shutdown switchover failed"));
+            this._emit('offline.permanent', event);
+          } else {
+            // Expected: old socket closed after successful switchover
+            this.logger.info("".concat(this.namespace, ": old socket closed with 4001 (replaced during shutdown); no reconnect needed"));
+            this._emit('offline.replaced', event);
+          }
           break;
         case 1001:
         case 1005:
         case 1006:
         case 1011:
           this.logger.info("".concat(this.namespace, ": socket disconnected; reconnecting"));
-          this._emit('offline.transient', event);
-          this._reconnect(socketUrl);
+          if (isActiveSocket) {
+            this._emit('offline.transient', event);
+            this.logger.info("".concat(this.namespace, ": [shutdown] reconnecting active socket to recover"));
+            this._reconnect(socketUrl);
+          }
           // metric: disconnect
           // if (code == 1011 && reason !== ping error) metric: unexpected disconnect
           break;
@@ -426,31 +622,42 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
           // 3050 indicates logout form of closure, default to old behavior, use config reason defined by consumer to proceed with the permanent block
           if (normalReconnectReasons.includes(reason)) {
             this.logger.info("".concat(this.namespace, ": socket disconnected; reconnecting"));
-            this._emit('offline.transient', event);
-            this._reconnect(socketUrl);
+            if (isActiveSocket) {
+              this._emit('offline.transient', event);
+              this.logger.info("".concat(this.namespace, ": [shutdown] reconnecting due to normal close"));
+              this._reconnect(socketUrl);
+            }
             // metric: disconnect
             // if (reason === done forced) metric: force closure
           } else {
             this.logger.info("".concat(this.namespace, ": socket disconnected; will not reconnect: ").concat(event.reason));
-            this._emit('offline.permanent', event);
+            if (isActiveSocket) this._emit('offline.permanent', event);
           }
           break;
         default:
           this.logger.info("".concat(this.namespace, ": socket disconnected unexpectedly; will not reconnect"));
           // unexpected disconnect
-          this._emit('offline.permanent', event);
+          if (isActiveSocket) this._emit('offline.permanent', event);
       }
     } catch (error) {
       this.logger.error("".concat(this.namespace, ": error occurred in close handler"), error);
     }
   },
   _onmessage: function _onmessage(event) {
-    var _this7 = this;
+    var _this10 = this;
     this._setTimeOffset(event);
     var envelope = event.data;
     if (process.env.ENABLE_MERCURY_LOGGING) {
       this.logger.debug("".concat(this.namespace, ": message envelope: "), envelope);
     }
+
+    // Handle shutdown message shape: { type: 'shutdown' }
+    if (envelope && envelope.type === 'shutdown') {
+      this.logger.info("".concat(this.namespace, ": [shutdown] imminent shutdown message received"));
+      this._emit('event:mercury_shutdown_imminent', envelope);
+      this._handleImminentShutdown();
+      return _promise.default.resolve();
+    }
     var data = envelope.data;
     this._applyOverrides(data);
     return this._getEventHandlers(data.eventType).reduce(function (promise, handler) {
@@ -458,24 +665,24 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
         var namespace = handler.namespace,
           name = handler.name;
         return new _promise.default(function (resolve) {
-          return resolve((_this7.webex[namespace] || _this7.webex.internal[namespace])[name](data));
+          return resolve((_this10.webex[namespace] || _this10.webex.internal[namespace])[name](data));
         }).catch(function (reason) {
-          return _this7.logger.error("".concat(_this7.namespace, ": error occurred in autowired event handler for ").concat(data.eventType), reason);
+          return _this10.logger.error("".concat(_this10.namespace, ": error occurred in autowired event handler for ").concat(data.eventType), reason);
         });
       });
     }, _promise.default.resolve()).then(function () {
-      _this7._emit('event', event.data);
+      _this10._emit('event', event.data);
       var _data$eventType$split = data.eventType.split('.'),
         _data$eventType$split2 = (0, _slicedToArray2.default)(_data$eventType$split, 1),
         namespace = _data$eventType$split2[0];
       if (namespace === data.eventType) {
-        _this7._emit("event:".concat(namespace), envelope);
+        _this10._emit("event:".concat(namespace), envelope);
       } else {
-        _this7._emit("event:".concat(namespace), envelope);
-        _this7._emit("event:".concat(data.eventType), envelope);
+        _this10._emit("event:".concat(namespace), envelope);
+        _this10._emit("event:".concat(data.eventType), envelope);
       }
     }).catch(function (reason) {
-      _this7.logger.error("".concat(_this7.namespace, ": error occurred processing socket message"), reason);
+      _this10.logger.error("".concat(_this10.namespace, ": error occurred processing socket message"), reason);
     });
   },
   _setTimeOffset: function _setTimeOffset(event) {
@@ -488,7 +695,7 @@ var Mercury = _webexCore.WebexPlugin.extend((_dec = (0, _common.deprecated)('Mer
     this.logger.info("".concat(this.namespace, ": reconnecting"));
     return this.connect(webSocketUrl);
   },
-  version: "3.9.0"
+  version: "3.10.0"
 }, ((0, _applyDecoratedDescriptor2.default)(_obj, "connect", [_common.oneFlight], (0, _getOwnPropertyDescriptor.default)(_obj, "connect"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "disconnect", [_common.oneFlight], (0, _getOwnPropertyDescriptor.default)(_obj, "disconnect"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "listen", [_dec], (0, _getOwnPropertyDescriptor.default)(_obj, "listen"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "stopListening", [_dec2], (0, _getOwnPropertyDescriptor.default)(_obj, "stopListening"), _obj)), _obj)));
 var _default = exports.default = Mercury;
 //# sourceMappingURL=mercury.js.map