Gateway Liveness

Reap half-open gateway connections with ping/pong heartbeats

Liveness is on out-of-box: the gateway pings peers on an interval, refreshes activity on every inbound frame, and reaps any session — or any stalled handshake — that misses too many beats.

Quick Start

1. On by default

   from praisonaiagents import Agent
   from praisonai_bot.gateway import WebSocketGateway
   
   # Liveness runs at the config defaults — no LivenessConfig needed.
   gateway = WebSocketGateway()
   gateway.register_agent(Agent(name="Support", instructions="Reply to users"))

2. Tune the cadence

   from praisonaiagents.gateway import GatewayConfig, LivenessConfig
   from praisonai_bot.gateway import WebSocketGateway
   
   gateway = WebSocketGateway(
       config=GatewayConfig(
           liveness=LivenessConfig(interval_ms=15_000, missed_beats_before_reap=3)
       )
   )

3. Opt out with interval_ms=0

   from praisonaiagents.gateway import GatewayConfig, LivenessConfig
   from praisonai_bot.gateway import WebSocketGateway
   
   # The only supported way to fully disable liveness at the runtime.
   gateway = WebSocketGateway(
       config=GatewayConfig(liveness=LivenessConfig(enabled=False, interval_ms=0))
   )

How It Works

The gateway emits a PING on each interval; any inbound frame (a PONG, a peer PING, or a normal message) refreshes activity. A silent peer misses beats until the reaper closes it.

A connection is reaped once now > last_activity + interval_seconds × missed_beats_before_reap. Half-open peers with no bound session yet (a stalled pre-hello/join handshake) are evaluated against a per-connection _client_last_seen clock, so silent handshake sockets age out instead of leaking forever.

The runtime is on by default: the config’s enabled=False no longer disables it. Only interval_ms=0 yields a disabled policy, after which the loop stays inert and nothing is reaped.

Health Output

WebSocketGateway.health() surfaces the reaper’s state when the task is running:

"liveness": {
  "enabled": true,
  "interval_ms": 30000,
  "missed_beats_before_reap": 2,
  "reaped_connections": 4
}

LIVENESS_TIMEOUT close code

The reaped peer sees a WebSocket close with:

• Code: 4002 (application-defined, private-use 4000–4999 range)
• Reason: "liveness_timeout" (equal to GatewayCloseCode.LIVENESS_TIMEOUT.value)

Custom clients should treat this as expected and reconnect. The reference client’s heartbeat loop usually force-reconnects first — after 2 × heartbeat_ms of silence it closes its own socket so the backoff/resume path re-establishes the connection before the server reaps it.

Configuration Options

LivenessConfig is the user-facing config; to_policy() bridges it to the pure LivenessPolicy the reaper consumes.

Common Patterns

Liveness runs at the defaults; pick a cadence from the peer’s network profile, or opt out entirely with interval_ms=0.

Out-of-box defaults

from praisonai_bot.gateway import WebSocketGateway

gateway = WebSocketGateway()  # liveness on: 30s × 2 beats

Aggressive reaping for high-turnover realtime

from praisonaiagents.gateway import GatewayConfig, LivenessConfig
from praisonai_bot.gateway import WebSocketGateway

gateway = WebSocketGateway(
    config=GatewayConfig(
        liveness=LivenessConfig(interval_ms=5_000, missed_beats_before_reap=2)
    )
)

Fully disabled

from praisonaiagents.gateway import GatewayConfig, LivenessConfig
from praisonai_bot.gateway import WebSocketGateway

gateway = WebSocketGateway(
    config=GatewayConfig(liveness=LivenessConfig(enabled=False, interval_ms=0))
)
# PING/reap is off, but the housekeeping tick still runs so pressure eviction stays active.

Best Practices

Related