@soimy/dingtalk 3.2.0 → 3.3.0

package/src/connection-manager.ts

@@ -15,9 +15,21 @@ import type {
   ConnectionManagerConfig,
   ConnectionAttemptResult,
   Logger,
+  StreamClientFactory,
 } from "./types";
 import { ConnectionState as ConnectionStateEnum } from "./types";
 
+/**
+ * Thrown when a runtime reconnection cycle exceeds the configured deadline.
+ * Identified via instanceof in reconnect() to skip cycle counting.
+ */
+export class ReconnectDeadlineError extends Error {
+  constructor(options?: ErrorOptions) {
+    super("Reconnect deadline exceeded", options);
+    this.name = "ReconnectDeadlineError";
+  }
+}
+
 /**
  * ConnectionManager handles the robust connection lifecycle for DWClient
  */
@@ -34,14 +46,26 @@ export class ConnectionManager {
   private connectedAt?: number;
   private consecutiveUnhealthyChecks: number = 0;
 
-  private static readonly HEALTH_CHECK_INTERVAL_MS = 5000;
-  private static readonly HEALTH_CHECK_GRACE_MS = 3000;
+  private static readonly HEALTH_CHECK_INTERVAL_MS = 60000;
+  private static readonly HEALTH_CHECK_GRACE_MS = 30000;
   private static readonly HEALTH_CHECK_UNHEALTHY_THRESHOLD = 2;
   private static readonly DEFAULT_MAX_RECONNECT_CYCLES = 10;
+  private static readonly MAX_CYCLE_BACKOFF_MS = 5000;
+  private static readonly MAX_CONSECUTIVE_DEADLINE_TIMEOUTS = 5;
+  private static readonly HEARTBEAT_INTERVAL_MS = 20_000;
+  private static readonly HEARTBEAT_MISS_THRESHOLD = 2;
   private runtimeReconnectCycles: number = 0;
+  private reconnectDeadline?: number;
+  private consecutiveDeadlineTimeouts: number = 0;
+  private lastSocketActivityAt?: number;
+  private lastHeartbeatPingAt?: number;
+  private consecutiveHeartbeatMisses: number = 0;
   private runtimeCounters = {
     healthUnhealthyChecks: 0,
     healthTriggeredReconnects: 0,
+    heartbeatMisses: 0,
+    heartbeatTriggeredReconnects: 0,
+    serverDisconnectMessages: 0,
     socketCloseEvents: 0,
     runtimeDisconnects: 0,
     reconnectAttempts: 0,
@@ -51,9 +75,12 @@ export class ConnectionManager {
 
   // Runtime monitoring resources
   private healthCheckInterval?: NodeJS.Timeout;
+  private heartbeatInterval?: NodeJS.Timeout;
   private socketCloseHandler?: (code: number, reason: string) => void;
   private socketErrorHandler?: (error: Error) => void;
-  private monitoredSocket?: any; // Store the socket instance we attached listeners to
+  private socketMessageHandler?: (data: any) => void;
+  private socketPongHandler?: () => void;
+  private monitoredSocket?: any;
 
   // Sleep abort control
   private sleepTimeout?: NodeJS.Timeout;
@@ -65,11 +92,18 @@ export class ConnectionManager {
   // Client reference
   private client: DWClient;
 
-  constructor(client: DWClient, accountId: string, config: ConnectionManagerConfig, log?: Logger) {
+  // Warm-reconnect: factory to create fresh DWClient instances with listeners
+  // already registered so the new socket starts receiving immediately.
+  private clientFactory?: StreamClientFactory;
+  // Old client pending cleanup after a warm reconnect swap.
+  private pendingOldClient?: DWClient;
+
+  constructor(client: DWClient, accountId: string, config: ConnectionManagerConfig, log?: Logger, clientFactory?: StreamClientFactory) {
     this.client = client;
     this.accountId = accountId;
     this.config = config;
     this.log = log;
+    this.clientFactory = clientFactory;
   }
 
   private notifyStateChange(error?: string): void {
@@ -81,10 +115,114 @@ export class ConnectionManager {
   private logRuntimeCounters(reason: string): void {
     const c = this.runtimeCounters;
     this.log?.info?.(
-      `[${this.accountId}] Runtime counters (${reason}): healthUnhealthyChecks=${c.healthUnhealthyChecks}, healthTriggeredReconnects=${c.healthTriggeredReconnects}, socketCloseEvents=${c.socketCloseEvents}, runtimeDisconnects=${c.runtimeDisconnects}, reconnectAttempts=${c.reconnectAttempts}, reconnectSuccess=${c.reconnectSuccess}, reconnectFailures=${c.reconnectFailures}`,
+      `[${this.accountId}] Runtime counters (${reason}): healthUnhealthyChecks=${c.healthUnhealthyChecks}, healthTriggeredReconnects=${c.healthTriggeredReconnects}, heartbeatMisses=${c.heartbeatMisses}, heartbeatTriggeredReconnects=${c.heartbeatTriggeredReconnects}, serverDisconnectMessages=${c.serverDisconnectMessages}, socketCloseEvents=${c.socketCloseEvents}, runtimeDisconnects=${c.runtimeDisconnects}, reconnectAttempts=${c.reconnectAttempts}, reconnectSuccess=${c.reconnectSuccess}, reconnectFailures=${c.reconnectFailures}`,
     );
   }
 
+  private recordSocketActivity(now: number = Date.now()): void {
+    this.lastSocketActivityAt = now;
+    this.consecutiveHeartbeatMisses = 0;
+  }
+
+  private setupHeartbeat(socket: any): void {
+    this.cleanupHeartbeatInterval();
+    this.heartbeatInterval = setInterval(() => {
+      if (this.stopped || this.state !== ConnectionStateEnum.CONNECTED) {
+        return;
+      }
+
+      if (socket.readyState !== 1) {
+        return;
+      }
+
+      const now = Date.now();
+      const idleMs = this.lastSocketActivityAt !== undefined
+        ? now - this.lastSocketActivityAt
+        : ConnectionManager.HEARTBEAT_INTERVAL_MS;
+      if (idleMs >= ConnectionManager.HEARTBEAT_INTERVAL_MS) {
+        this.consecutiveHeartbeatMisses += 1;
+        this.runtimeCounters.heartbeatMisses += 1;
+
+        if (this.consecutiveHeartbeatMisses >= ConnectionManager.HEARTBEAT_MISS_THRESHOLD) {
+          const lastPingAgoMs = this.lastHeartbeatPingAt !== undefined
+            ? now - this.lastHeartbeatPingAt
+            : undefined;
+          this.log?.warn?.(
+            `[${this.accountId}] Connection heartbeat missed ${this.consecutiveHeartbeatMisses}/${ConnectionManager.HEARTBEAT_MISS_THRESHOLD} checks, triggering reconnection (lastPingAgoMs=${lastPingAgoMs ?? "n/a"})`,
+          );
+          this.runtimeCounters.heartbeatTriggeredReconnects += 1;
+          this.logRuntimeCounters("heartbeat-triggered-reconnect");
+          this.cleanupHeartbeatInterval();
+          this.handleRuntimeDisconnection();
+          return;
+        }
+
+        this.log?.debug?.(
+          `[${this.accountId}] Connection heartbeat missed (${this.consecutiveHeartbeatMisses}/${ConnectionManager.HEARTBEAT_MISS_THRESHOLD})`,
+        );
+      }
+
+      this.lastHeartbeatPingAt = now;
+      try {
+        socket.ping("", true);
+      } catch (err: any) {
+        this.log?.warn?.(
+          `[${this.accountId}] Failed to send heartbeat ping: ${err.message}`,
+        );
+      }
+    }, ConnectionManager.HEARTBEAT_INTERVAL_MS);
+  }
+
+  private cleanupHeartbeatInterval(): void {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = undefined;
+    }
+  }
+
+  private clearClientHeartbeatInterval(client: DWClient): void {
+    const clientAny = client as any;
+    if (clientAny.heartbeatIntervallId !== undefined) {
+      clearInterval(clientAny.heartbeatIntervallId);
+      clientAny.heartbeatIntervallId = undefined;
+    }
+  }
+
+  private async waitForSocketOpen(clientAny: any): Promise<void> {
+    const socket = clientAny.socket;
+    if (!socket) {
+      throw new Error("Socket unavailable after connect");
+    }
+
+    if (socket.readyState === 1 || clientAny.connected) {
+      return;
+    }
+
+    const defaultOpenTimeout = 10_000;
+    const openTimeout = this.reconnectDeadline !== undefined
+      ? Math.min(defaultOpenTimeout, Math.max(1000, this.reconnectDeadline - Date.now()))
+      : defaultOpenTimeout;
+
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error("Socket open timeout"));
+      }, openTimeout);
+      const cleanup = () => {
+        clearTimeout(timeout);
+        socket.removeListener("open", onOpen);
+        socket.removeListener("error", onError);
+        socket.removeListener("close", onClose);
+      };
+      const onOpen = () => { cleanup(); resolve(); };
+      const onError = (err: Error) => { cleanup(); reject(err); };
+      const onClose = () => { cleanup(); reject(new Error("Socket closed before open")); };
+      socket.once("open", onOpen);
+      socket.once("error", onError);
+      socket.once("close", onClose);
+    });
+  }
+
   /**
    * Calculate next reconnection delay with exponential backoff and jitter
    * Formula: delay = min(initialDelay * 2^attempt, maxDelay) * (1 ± jitter)
@@ -129,24 +267,52 @@ export class ConnectionManager {
     );
 
     try {
-      // Ensure previous connection resources (heartbeat timers, old sockets) are
-      // fully cleaned up before establishing a new connection.  The DWClient
-      // _connect() method does not clear its internal heartbeat interval, so a
-      // stale timer from a prior session can terminate the newly created socket
-      // before it finishes the handshake (manifests as code-1006 / "WebSocket was
-      // closed before the connection was established").
-      try {
-        this.client.disconnect();
-      } catch (disconnectErr: any) {
-        this.log?.debug?.(
-          `[${this.accountId}] pre-connect cleanup disconnect failed: ${disconnectErr.message}`,
-        );
+      // Warm-reconnect path: create a fresh DWClient so the new WebSocket
+      // can start receiving messages while the old zombie socket is cleaned
+      // up asynchronously. This minimizes the message-loss window during
+      // server-initiated disconnects (DingTalk robot msgs are fire-and-forget).
+      if (this.clientFactory) {
+        const oldClient = this.client;
+        this.pendingOldClient = oldClient;
+        try {
+          this.client = this.clientFactory();
+          this.log?.info?.(
+            `[${this.accountId}] Warm reconnect: created fresh DWClient, connecting new socket while old socket is cleaned up`,
+          );
+        } catch (factoryErr: any) {
+          this.log?.warn?.(
+            `[${this.accountId}] Client factory failed, falling back to same-client reconnect: ${factoryErr.message}`,
+          );
+          this.client = oldClient;
+          this.pendingOldClient = undefined;
+        }
       }
 
+      if (!this.pendingOldClient) {
+        // Legacy single-client reconnect: disconnect before reconnecting.
+        try {
+          this.client.disconnect();
+        } catch (disconnectErr: any) {
+          this.log?.debug?.(
+            `[${this.accountId}] pre-connect cleanup disconnect failed: ${disconnectErr.message}`,
+          );
+        }
+      }
+
+      // SDK _connect() resolves before socket "open" fires. If disconnect() runs
+      // before "open", heartbeatIntervallId is still undefined and clearInterval
+      // is a no-op. The deferred "open" handler then creates an interval that
+      // outlives the old socket and can terminate the next connection.
+      // For the race where interval is created AFTER this cleanup, the socket
+      // open timeout below serves as the final safety net.
+      // Field name "heartbeatIntervallId" (double-l typo) from dingtalk-stream
+      // SDK DWClient._connect() open handler (verified in SDK v1.x).
+      const clientAny = this.client as any;
+      this.clearClientHeartbeatInterval(this.client);
+
       await this.client.connect();
+      await this.waitForSocketOpen(clientAny);
 
-      // Re-check stopped flag after async connect() completes
-      // This prevents race condition where stop() is called during connection
       if (this.stopped) {
         this.log?.warn?.(
           `[${this.accountId}] Connection succeeded but manager was stopped during connect - disconnecting`,
@@ -165,21 +331,41 @@ export class ConnectionManager {
         };
       }
 
-      // Connection successful
       this.state = ConnectionStateEnum.CONNECTED;
       this.connectedAt = Date.now();
+      this.recordSocketActivity(this.connectedAt);
+      this.lastHeartbeatPingAt = undefined;
+      this.reconnectDeadline = undefined;
       this.consecutiveUnhealthyChecks = 0;
+      this.consecutiveHeartbeatMisses = 0;
       this.notifyStateChange();
       const successfulAttempt = this.attemptCount;
-      this.attemptCount = 0; // Reset counter on success
+      this.attemptCount = 0;
 
       this.log?.info?.(`[${this.accountId}] DingTalk Stream client connected successfully`);
 
-      // Reset runtime reconnect cycle counter on successful connection
       this.runtimeReconnectCycles = 0;
+      this.consecutiveDeadlineTimeouts = 0;
+      // Setup monitoring BEFORE cleaning up old client: setupRuntimeReconnection
+      // calls cleanupRuntimeMonitoring() which removes the old socket's event
+      // listeners, preventing the old socket's close event (triggered by
+      // disconnect below) from erroneously firing handleRuntimeDisconnection.
+      this.setupRuntimeReconnection();
+      this.cleanupPendingOldClient();
 
       return { success: true, attempt: successfulAttempt };
     } catch (err: any) {
+      // Warm-reconnect failed with new client: revert to old client so
+      // subsequent retry attempts don't keep creating throwaway instances.
+      if (this.pendingOldClient) {
+        try { this.client.disconnect(); } catch { /* best-effort cleanup of failed new client */ }
+        this.client = this.pendingOldClient;
+        this.pendingOldClient = undefined;
+        this.log?.debug?.(
+          `[${this.accountId}] Warm reconnect failed, reverted to previous client for next retry`,
+        );
+      }
+
       this.log?.error?.(
         `[${this.accountId}] Connection attempt ${this.attemptCount} failed: ${err.message}`,
       );
@@ -221,17 +407,18 @@ export class ConnectionManager {
       `[${this.accountId}] Starting DingTalk Stream client with robust connection...`,
     );
 
-    // Keep trying until success or max attempts reached
     while (!this.stopped && this.state !== ConnectionStateEnum.CONNECTED) {
+      if (this.reconnectDeadline !== undefined && Date.now() >= this.reconnectDeadline) {
+        this.reconnectDeadline = undefined;
+        throw new ReconnectDeadlineError();
+      }
+
       const result = await this.attemptConnection();
 
       if (result.success) {
-        // Connection successful
-        this.setupRuntimeReconnection();
         return;
       }
 
-      // Check if connection was stopped during connect
       if (result.error?.message === "Connection manager stopped during connect") {
         this.log?.info?.(
           `[${this.accountId}] Connection cancelled: manager stopped during connect`,
@@ -240,12 +427,17 @@ export class ConnectionManager {
       }
 
       if (!result.nextDelay || this.attemptCount >= this.config.maxAttempts) {
-        // No more retries
         throw new Error(`Failed to connect after ${this.attemptCount} attempts`);
       }
 
-      // Wait before next attempt
-      await this.sleep(result.nextDelay);
+      // Truncate sleep to remaining deadline budget
+      let actualDelay = result.nextDelay;
+      if (this.reconnectDeadline !== undefined) {
+        const remaining = Math.max(0, this.reconnectDeadline - Date.now());
+        actualDelay = Math.min(actualDelay, remaining);
+      }
+
+      await this.sleep(actualDelay);
     }
   }
 
@@ -288,7 +480,15 @@ export class ConnectionManager {
 
       const socketReadyState = (client.socket as { readyState?: number } | undefined)?.readyState;
       const socketOpen = socketReadyState === 1;
-      const unhealthy = !client.connected && !socketOpen;
+      const registered = client.registered as boolean | undefined;
+
+      // Unhealthy if:
+      // 1. Not connected AND socket not open (full disconnect)
+      // 2. Socket is open, client.connected is false, AND not registered
+      //    (server sent logical "disconnect" and the socket is now a zombie)
+      const unhealthy =
+        (!client.connected && !socketOpen) ||
+        (socketOpen && !client.connected && registered === false);
 
       if (!unhealthy) {
         this.consecutiveUnhealthyChecks = 0;
@@ -302,7 +502,7 @@ export class ConnectionManager {
         ConnectionManager.HEALTH_CHECK_UNHEALTHY_THRESHOLD
       ) {
         this.log?.debug?.(
-          `[${this.accountId}] Connection health check unhealthy (${this.consecutiveUnhealthyChecks}/${ConnectionManager.HEALTH_CHECK_UNHEALTHY_THRESHOLD}) connected=${String(client.connected)} socketReadyState=${socketReadyState ?? "unknown"}`,
+          `[${this.accountId}] Connection health check unhealthy (${this.consecutiveUnhealthyChecks}/${ConnectionManager.HEALTH_CHECK_UNHEALTHY_THRESHOLD}) connected=${String(client.connected)} registered=${String(registered)} socketReadyState=${socketReadyState ?? "unknown"}`,
         );
         return;
       }
@@ -324,6 +524,7 @@ export class ConnectionManager {
       const socket = client.socket;
       // Store the socket instance we're attaching listeners to
       this.monitoredSocket = socket;
+      this.setupHeartbeat(socket);
 
       // Handler for socket close event
       this.socketCloseHandler = (code: number, reason: string) => {
@@ -349,11 +550,61 @@ export class ConnectionManager {
         );
       };
 
-      // Listen to socket events
-      // Use 'once' for close to avoid duplicate reconnection triggers
       socket.once("close", this.socketCloseHandler);
-      // Use 'once' for error as well to prevent accumulation across reconnects
       socket.once("error", this.socketErrorHandler);
+
+      // Monitor for server-side disconnect system messages and passive socket
+      // activity.
+      this.socketMessageHandler = (data: any) => {
+        this.recordSocketActivity();
+        try {
+          const msg = JSON.parse(typeof data === "string" ? data : data.toString());
+          if (msg?.type === "SYSTEM" && msg?.headers?.topic === "disconnect") {
+            this.runtimeCounters.serverDisconnectMessages += 1;
+            this.log?.warn?.(
+              `[${this.accountId}] Server disconnect system message received, triggering immediate reconnection`,
+            );
+            this.logRuntimeCounters("server-disconnect");
+            if (this.healthCheckInterval) {
+              clearInterval(this.healthCheckInterval);
+            }
+            this.handleRuntimeDisconnection();
+          }
+        } catch {
+          // Ignore parse errors — other handlers will process the message
+        }
+      };
+      socket.on("message", this.socketMessageHandler);
+
+      this.socketPongHandler = () => {
+        this.recordSocketActivity();
+      };
+      socket.on("pong", this.socketPongHandler);
+    }
+  }
+
+  /**
+   * Disconnect and release the old client left over from a warm-reconnect swap.
+   */
+  private cleanupPendingOldClient(): void {
+    if (!this.pendingOldClient) {
+      return;
+    }
+    const old = this.pendingOldClient;
+    this.pendingOldClient = undefined;
+    try {
+      // Clear stale heartbeat interval from old SDK instance.
+      const oldAny = old as any;
+      if (oldAny.heartbeatIntervallId !== undefined) {
+        clearInterval(oldAny.heartbeatIntervallId);
+        oldAny.heartbeatIntervallId = undefined;
+      }
+      old.disconnect();
+      this.log?.debug?.(`[${this.accountId}] Warm reconnect: old client disconnected`);
+    } catch (err: any) {
+      this.log?.debug?.(
+        `[${this.accountId}] Warm reconnect: old client cleanup failed: ${err.message}`,
+      );
     }
   }
 
@@ -367,6 +618,7 @@ export class ConnectionManager {
       this.healthCheckInterval = undefined;
       this.log?.debug?.(`[${this.accountId}] Health check interval cleared`);
     }
+    this.cleanupHeartbeatInterval();
 
     // Remove socket event listeners from the stored socket instance
     if (this.monitoredSocket) {
@@ -380,6 +632,14 @@ export class ConnectionManager {
         socket.removeListener("error", this.socketErrorHandler);
         this.socketErrorHandler = undefined;
       }
+      if (this.socketMessageHandler) {
+        socket.removeListener("message", this.socketMessageHandler);
+        this.socketMessageHandler = undefined;
+      }
+      if (this.socketPongHandler) {
+        socket.removeListener("pong", this.socketPongHandler);
+        this.socketPongHandler = undefined;
+      }
 
       this.log?.debug?.(`[${this.accountId}] Socket event listeners removed from monitored socket`);
       this.monitoredSocket = undefined;
@@ -390,35 +650,37 @@ export class ConnectionManager {
    * Handle runtime disconnection and trigger reconnection
    */
   private handleRuntimeDisconnection(): void {
-    if (this.stopped) {
+    if (this.stopped || this.state !== ConnectionStateEnum.CONNECTED) {
       return;
     }
 
+    this.state = ConnectionStateEnum.DISCONNECTED;
+
     this.log?.warn?.(
       `[${this.accountId}] Runtime disconnection detected, initiating reconnection...`,
     );
     this.runtimeCounters.runtimeDisconnects += 1;
 
-    this.state = ConnectionStateEnum.DISCONNECTED;
     this.notifyStateChange("Runtime disconnection detected");
-    this.attemptCount = 0; // Reset attempt counter for runtime reconnection
+    this.attemptCount = 0;
     this.connectedAt = undefined;
+    this.lastSocketActivityAt = undefined;
+    this.lastHeartbeatPingAt = undefined;
     this.consecutiveUnhealthyChecks = 0;
+    this.consecutiveHeartbeatMisses = 0;
+
+    const deadlineMs = this.config.reconnectDeadlineMs ?? 50000;
+    this.reconnectDeadline = Date.now() + deadlineMs;
 
-    // Clear any existing timer
     this.clearReconnectTimer();
 
-    // Start reconnection with initial delay
-    const delay = this.calculateNextDelay(0);
-    this.log?.info?.(
-      `[${this.accountId}] Scheduling reconnection in ${(delay / 1000).toFixed(2)}s`,
-    );
+    this.log?.info?.(`[${this.accountId}] Scheduling immediate reconnection`);
 
     this.reconnectTimer = setTimeout(() => {
       this.reconnect().catch((err) => {
         this.log?.error?.(`[${this.accountId}] Reconnection failed: ${err.message}`);
       });
-    }, delay);
+    }, 0);
   }
 
   /**
@@ -446,7 +708,40 @@ export class ConnectionManager {
       this.runtimeCounters.reconnectFailures += 1;
       this.logRuntimeCounters("reconnect-failed");
 
-      // Track runtime reconnect cycles to prevent infinite loops
+      if (err instanceof ReconnectDeadlineError) {
+        this.consecutiveDeadlineTimeouts += 1;
+
+        if (this.consecutiveDeadlineTimeouts >= ConnectionManager.MAX_CONSECUTIVE_DEADLINE_TIMEOUTS) {
+          this.log?.error?.(
+            `[${this.accountId}] Max consecutive deadline timeouts (${ConnectionManager.MAX_CONSECUTIVE_DEADLINE_TIMEOUTS}) reached. Giving up.`,
+          );
+          this.state = ConnectionStateEnum.FAILED;
+          this.connectedAt = undefined;
+          this.consecutiveUnhealthyChecks = 0;
+          this.reconnectDeadline = undefined;
+          this.notifyStateChange(
+            `Max consecutive deadline timeouts (${ConnectionManager.MAX_CONSECUTIVE_DEADLINE_TIMEOUTS}) reached`,
+          );
+          return;
+        }
+
+        const deadlineMs = this.config.reconnectDeadlineMs ?? 50000;
+        this.reconnectDeadline = Date.now() + deadlineMs;
+        const delay = Math.min(
+          this.calculateNextDelay(0),
+          ConnectionManager.MAX_CYCLE_BACKOFF_MS,
+        );
+        this.attemptCount = 0;
+        this.clearReconnectTimer();
+        this.log?.warn?.(
+          `[${this.accountId}] Reconnect deadline exceeded (${this.consecutiveDeadlineTimeouts}/${ConnectionManager.MAX_CONSECUTIVE_DEADLINE_TIMEOUTS}); scheduling next cycle in ${(delay / 1000).toFixed(2)}s`,
+        );
+        this.reconnectTimer = setTimeout(() => {
+          void this.reconnect();
+        }, delay);
+        return;
+      }
+
       this.runtimeReconnectCycles += 1;
       const maxCycles = this.config.maxReconnectCycles ?? ConnectionManager.DEFAULT_MAX_RECONNECT_CYCLES;
 
@@ -458,6 +753,7 @@ export class ConnectionManager {
         this.state = ConnectionStateEnum.FAILED;
         this.connectedAt = undefined;
         this.consecutiveUnhealthyChecks = 0;
+        this.reconnectDeadline = undefined;
         this.notifyStateChange(`Max runtime reconnect cycles (${maxCycles}) reached`);
         return;
       }
@@ -467,8 +763,11 @@ export class ConnectionManager {
       this.consecutiveUnhealthyChecks = 0;
       this.notifyStateChange(err.message);
 
-      // Continue runtime recovery with exponential backoff based on cycle count
-      const delay = this.calculateNextDelay(Math.min(this.runtimeReconnectCycles - 1, 6)); // Cap at ~64x initial delay
+      const rawDelay = this.calculateNextDelay(Math.min(this.runtimeReconnectCycles - 1, 6));
+      const delay = Math.min(rawDelay, ConnectionManager.MAX_CYCLE_BACKOFF_MS);
+      // Each cycle gets its own deadline so long-running retries don't block indefinitely
+      const deadlineMs = this.config.reconnectDeadlineMs ?? 50000;
+      this.reconnectDeadline = Date.now() + deadlineMs;
       this.attemptCount = 0;
       this.clearReconnectTimer();
       this.log?.warn?.(
@@ -493,7 +792,12 @@ export class ConnectionManager {
     this.stopped = true;
     this.state = ConnectionStateEnum.DISCONNECTING;
     this.connectedAt = undefined;
+    this.reconnectDeadline = undefined;
+    this.consecutiveDeadlineTimeouts = 0;
     this.consecutiveUnhealthyChecks = 0;
+    this.lastSocketActivityAt = undefined;
+    this.lastHeartbeatPingAt = undefined;
+    this.consecutiveHeartbeatMisses = 0;
 
     // Clear reconnect timer
     this.clearReconnectTimer();
@@ -504,6 +808,9 @@ export class ConnectionManager {
     // Clean up runtime monitoring resources
     this.cleanupRuntimeMonitoring();
 
+    // Clean up any pending old client from warm-reconnect swap.
+    this.cleanupPendingOldClient();
+
     // Disconnect client
     try {
       this.client.disconnect();

package/src/dedup.ts

@@ -1,6 +1,7 @@
 // ============ Message Deduplication ============
 // Prevent duplicate processing when DingTalk retries delivery.
 // In-memory TTL map + lazy cleanup keeps overhead small.
+export const DEDUP_NAMESPACE_POLICY = "memory-only" as const;
 
 const processedMessages = new Map<string, number>();
 const MESSAGE_DEDUP_TTL = 60000;