Ping & Pong

Connection health check messages

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

Related Messages

• WorkerRegistered - Initial connection establishment