Heartbeats & Keep-Alive Mechanisms

Technical Deep Dive & Specifications

Why TCP Sockets Silently Die

1. Half-Open TCP Connections: If an intermediary router crashes or a mobile device loses radio signal, no FIN or RST packets are sent across the wire. The client and server both believe readyState === WebSocket.OPEN (1), but packets sent into the socket are silently discarded.
2. NAT Gateway & Firewall Idle Timeouts: Intermediate network hardware (residential routers, corporate firewalls, NAT tables, load balancers) maintain state tables mapping internal client IP/ports to external destinations. If no packets traverse the connection for 30–60 seconds, the NAT router purges the table entry. Future packets from either side are rejected or dropped.

Protocol Control Frames vs. Application-Level Heartbeats

RFC 6455 defines two dedicated 1-byte control frame opcodes:

• Opcode 0x9 (Ping): Can be sent by either endpoint with an optional payload.
• Opcode 0xA (Pong): Must be returned immediately by the receiving endpoint containing the exact identical payload as the ping.

+---------------------------------------------------------------------------------------+
|                 PROTOCOL-LEVEL (RFC 6455) vs APPLICATION-LEVEL HEARTBEATS             |
+---------------------------------------------------------------------------------------+

1. RFC 6455 Protocol Frames (Opcode 0x9 / 0xA):
   - Handled directly by the browser's underlying C++ networking engine.
   - Browsers automatically answer server pings with pongs.
   - ⚠️ CRITICAL: The browser JavaScript WebSocket API provides NO method to send 
     Opcode 0x9 or listen to Opcode 0xA!

2. Application-Level Heartbeats (JSON / Binary Frames):
   - Implemented in JavaScript userland using standard text/binary frames.
   - Example: { "type": "ping", "timestamp": 1720000000000 }
   - Universally supported across all web browsers, workers, and mobile runtimes.

The Dual-Timer Heartbeat Architecture

A production-grade heartbeat requires two coordinated timers:

1. Heartbeat Interval Timer: Periodically sends a ping frame (typically every 15–30 seconds).
2. Heartbeat Watchdog (Timeout) Timer: Armed the instant a ping is sent. If a corresponding pong is not received within a grace period (e.g., 5 seconds), the connection is presumed dead. The watchdog forces socket termination via socket.close(), triggering cleanup and auto-reconnect.

  CLIENT                                                SERVER
     |                                                     |
     |--- 1. Send { type: 'ping', t: 100 } -------------->|
     |    [Start 5-second Watchdog Timer]                  |
     |                                                     |
     |<-- 2. Receive { type: 'pong', t: 100 } -------------|
     |    [Clear Watchdog Timer; RTT = Now - 100]          |
     |                                                     |
     |--- (Wait 15s Heartbeat Interval)                    |
     |                                                     |
     |--- 3. Send { type: 'ping', t: 115 } -------------->|
     |    [Start 5-second Watchdog Timer]                  |
     |    ... [Network Fails - No Reply Received] ...      |
     |    [5-second Watchdog Expires!]                     |
     |    socket.close(4000, "Heartbeat Timeout")          |
     v                                                     v

Round-Trip Time (RTT) Calculation

By embedding a high-precision timestamp (Date.now() or performance.now()) inside the outbound ping payload and having the server echo it back inside the pong, the client calculates exact network latency:

$$\text{RTT} = \text{Date.now()} - \text{pongPayload.timestamp}$$

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 84–96 (mockServerReceive): Simulates a network transport layer with latency, capable of toggling into a "blackhole" mode to mimic a dead NAT table or dropped cellular connection.
• Lines 105–118 (sendPing): Dispatches a timestamped JSON ping frame and arms watchdogTimer = setTimeout(..., PONG_TIMEOUT).
• Lines 120–131 (handlePong): When the matching pong returns, it immediately executes clearTimeout(watchdogTimer), calculates RTT latency, and records server responsiveness.
• Lines 133–141 (handleDeadConnection): If the watchdog timer expires before a pong arrives, it terminates the dead socket and prepares for reconnection.

Expected Browser Render Output

Heartbeat Watchdog Engine [ACTIVE]
[RTT: 41 ms] [Pings Sent: 4] [Pongs Received: 4]

[Simulate Server Blackhole] [Restore Server]

Watchdog Diagnostics Log
[02:30:10.120] ➡️ Dispatched PING (Seq #1)
[02:30:10.161] ⬅️ Received PONG. RTT Latency: 41ms. Watchdog disarmed.
[02:30:13.120] ➡️ Dispatched PING (Seq #2)
[02:30:13.162] ⬅️ Received PONG. RTT Latency: 42ms. Watchdog disarmed.