Skip to main content

​
Overview

Ping and Pong messages are used to maintain and verify WebSocket connection health between workers and the iii framework. These messages implement a keepalive mechanism to detect disconnections and ensure the connection remains active.

​
Ping

​
Request

A Ping message is sent to verify that the connection is alive and the peer is responsive.

​
Example

{
  "type": "ping"
}

​
Pong

​
Response

A Pong message is sent in response to a Ping message to acknowledge the connection is healthy.
​
type
string
required
Message type. Must be "pong".

​
Example

{
  "type": "pong"
}

​
Usage Patterns

​
Client-Initiated Ping

The worker sends a Ping message and expects a Pong response: 
// Worker sends
{
  "type": "ping"
}

// Framework responds
{
  "type": "pong"
}

​
Server-Initiated Ping

The framework sends a Ping message and expects a Pong response from the worker: 
// Framework sends
{
  "type": "ping"
}

// Worker responds
{
  "type": "pong"
}

​
Heartbeat Implementation

Typical implementation with periodic pings: 
// Send ping every 30 seconds
setInterval(() => {
  ws.send(JSON.stringify({ type: "ping" }));
}, 30000);

// Respond to incoming pings
ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'ping') {
    ws.send(JSON.stringify({ type: "pong" }));
  }
});

​
Connection Timeout Detection

let lastPong = Date.now();
const TIMEOUT_MS = 60000; // 60 seconds

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'pong') {
    lastPong = Date.now();
  }
});

// Check for timeout
setInterval(() => {
  if (Date.now() - lastPong > TIMEOUT_MS) {
    console.error('Connection timeout - no pong received');
    ws.close();
  }
}, 10000);

​
Error Cases

​
No Pong Response

If a Pong is not received within the expected timeout period:
  • The connection may be broken or experiencing network issues
  • The peer may be unresponsive or overloaded
  • Consider closing and reconnecting the WebSocket

​
Delayed Pong

If Pong responses are consistently delayed:
  • May indicate network latency issues
  • The peer may be under heavy load
  • Consider adjusting timeout thresholds

​
Notes

  • Ping/Pong messages have no additional fields beyond the type
  • These are application-level keepalive messages (distinct from WebSocket protocol-level ping/pong frames)
  • Implementations should respond to Ping messages promptly
  • Typical ping intervals range from 15-60 seconds
  • Timeout thresholds are usually 2-3x the ping interval
  • Both client and server can initiate ping requests
  • Pong responses should be sent immediately upon receiving a Ping
  • Consider implementing exponential backoff for reconnection after timeout

​
Best Practices

  • Implement bidirectional pings: Both worker and framework should support sending and responding to pings
  • Set reasonable intervals: Don’t ping too frequently (wastes bandwidth) or too infrequently (slow to detect failures)
  • Use timeouts: Always implement timeout detection for missed pongs
  • Log ping/pong timing: Monitor latency and connection health
  • Handle reconnection: Automatically reconnect when connection health checks fail
  • Combine with other health checks: Use alongside application-level health monitoring

Build docs developers (and LLMs) love

Get started for freeTalk to us