@pnds/sdk 1.0.1 → 1.2.0

package/src/ws.ts

@@ -37,6 +37,10 @@ export class PondWs {
   private lastSeq = 0;
   private _state: WsConnectionState = 'disconnected';
   private intentionalClose = false;
+  private lastReceivedAt = 0;
+  private heartbeatIntervalMs = 0;
+  private probeTimer: ReturnType<typeof setTimeout> | null = null;
+  private browserListenersActive = false;
 
   constructor(options: PondWsOptions) {
     this.options = {
@@ -54,6 +58,7 @@ export class PondWs {
 
   async connect() {
     this.intentionalClose = false;
+    this.setupBrowserListeners();
     this.setState('connecting');
 
     let ticket: WsTicketResponse;
@@ -106,6 +111,7 @@ export class PondWs {
     this.ws.onopen = () => {
       clearTimeout(connectTimeout);
       this.reconnectAttempts = 0;
+      this.lastReceivedAt = Date.now();
       this.setState('connected');
     };
 
@@ -121,6 +127,7 @@ export class PondWs {
     this.ws.onclose = () => {
       clearTimeout(connectTimeout);
       this.stopHeartbeat();
+      this.clearProbe();
       if (this.intentionalClose) {
         this.setState('disconnected');
         return;
@@ -141,6 +148,8 @@ export class PondWs {
     this.intentionalClose = true;
     this.stopHeartbeat();
     this.clearReconnect();
+    this.clearProbe();
+    this.teardownBrowserListeners();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -216,6 +225,9 @@ export class PondWs {
   }
 
   private handleFrame(frame: WsFrame) {
+    this.lastReceivedAt = Date.now();
+    this.clearProbe();
+
     // Track seq for reconnection
     if (frame.seq !== undefined) {
       this.lastSeq = frame.seq;
@@ -238,7 +250,21 @@ export class PondWs {
 
   private startHeartbeat(intervalSec: number) {
     this.stopHeartbeat();
+    if (!Number.isFinite(intervalSec) || intervalSec <= 0) {
+      console.error('Invalid heartbeat interval from server:', intervalSec);
+      return;
+    }
+    this.heartbeatIntervalMs = intervalSec * 1000;
     this.heartbeatTimer = setInterval(() => {
+      // If no data received for >1.5× heartbeat interval, the connection may
+      // be stale — or the timer may have been delayed by browser throttling /
+      // event-loop stalls. Probe with a 5s timeout rather than force-
+      // reconnecting, so healthy connections that were merely timer-starved
+      // survive while genuinely dead sockets are caught quickly.
+      if (this.lastReceivedAt > 0 && Date.now() - this.lastReceivedAt > this.heartbeatIntervalMs * 1.5) {
+        this.probeConnection();
+        return;
+      }
       this.send({ type: WS_EVENTS.PING, data: { ts: Date.now() } });
     }, intervalSec * 1000);
   }
@@ -254,10 +280,12 @@ export class PondWs {
     this.setState('reconnecting');
     this.clearReconnect();
 
-    const delay = Math.min(
+    const base = Math.min(
       this.options.reconnectInterval * Math.pow(2, this.reconnectAttempts),
       this.options.maxReconnectInterval,
     );
+    // Jitter: 50-100% of base delay to prevent thundering herd
+    const delay = base * (0.5 + Math.random() * 0.5);
     this.reconnectAttempts++;
 
     this.reconnectTimer = setTimeout(() => {
@@ -272,6 +300,108 @@ export class PondWs {
     }
   }
 
+  /** Force-close a dead/stale connection and trigger reconnect. */
+  private forceReconnect() {
+    this.stopHeartbeat();
+    this.clearReconnect();
+    this.clearProbe();
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.onopen = null;
+      this.ws.onerror = null;
+      this.ws.onmessage = null;
+      try { this.ws.close(); } catch { /* ignore */ }
+      this.ws = null;
+    }
+    if (this.options.reconnect && !this.intentionalClose) {
+      this.scheduleReconnect();
+    } else {
+      this.setState('disconnected');
+    }
+  }
+
+  // ---- Browser event listeners for proactive reconnection ----
+
+  private setupBrowserListeners() {
+    if (this.browserListenersActive) return;
+    this.browserListenersActive = true;
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+    if (typeof window !== 'undefined') {
+      window.addEventListener('online', this.handleOnline);
+    }
+  }
+
+  private teardownBrowserListeners() {
+    if (!this.browserListenersActive) return;
+    this.browserListenersActive = false;
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('online', this.handleOnline);
+    }
+  }
+
+  /**
+   * Send a ping and arm a short timeout. If no frame arrives within 5s the
+   * connection is assumed dead and force-reconnected. Any received frame
+   * (including the pong) cancels the timer via clearProbe() in handleFrame.
+   */
+  private probeConnection() {
+    if (this.probeTimer) return; // don't re-arm an active probe
+    this.send({ type: WS_EVENTS.PING, data: { ts: Date.now() } });
+    this.probeTimer = setTimeout(() => {
+      this.forceReconnect();
+    }, 5_000);
+  }
+
+  private clearProbe() {
+    if (this.probeTimer) {
+      clearTimeout(this.probeTimer);
+      this.probeTimer = null;
+    }
+  }
+
+  /** Tab returned to foreground — verify connection or accelerate reconnect. */
+  private handleVisibilityChange = () => {
+    if (typeof document !== 'undefined' && document.hidden) return;
+
+    if (this._state === 'connected') {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        this.forceReconnect();
+      } else {
+        // Probe liveness — do NOT reset lastReceivedAt here; a zombie socket
+        // may still report OPEN. The 5s probe timeout will catch it quickly
+        // instead of deferring to the next heartbeat cycle (~60s).
+        this.probeConnection();
+      }
+    } else if (this._state === 'reconnecting') {
+      // Skip remaining backoff — try immediately
+      this.clearReconnect();
+      this.reconnectAttempts = 0;
+      this.connect();
+    }
+  };
+
+  /** Network restored — accelerate reconnection. */
+  private handleOnline = () => {
+    if (this.intentionalClose) return;
+
+    if (this._state === 'connected') {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        this.forceReconnect();
+      } else {
+        this.probeConnection();
+      }
+    } else if (this._state === 'reconnecting') {
+      this.clearReconnect();
+      this.reconnectAttempts = 0;
+      this.connect();
+    }
+  };
+
   private setState(state: WsConnectionState) {
     this._state = state;
     for (const listener of this.stateListeners) {