Add WebSocket heartbeat with pong-timeout dead-connection detection

[partouf]

Problem

The WebSocket ping was fire-and-forget — it sent frames every 30s but never verified a response. A silently dead connection (half-open TCP, dropped network, a load balancer reaping an idle connection) went undetected until the OS TCP stack gave up, which can take minutes. During that window isConnected() and the healthcheck reported healthy while compilation subscriptions silently hung until their per-request timeout.

Change

• Active heartbeat with pong-timeout. Each interval sends a ping and arms a pong-timeout. If no pong or other inbound activity arrives before the deadline, the socket is treated as dead and terminate()d, which triggers the existing reconnect path. Dead connections are now caught in ~pingInterval + pongTimeout (≈40s) instead of minutes.
• Activity-based liveness. Any inbound message also counts as proof-of-life, so a busy connection is never killed for a single missed pong.
• PingMode setting (--ping-mode / WEBSOCKET_PING_MODE, default application):
  • application — sends a "ping" text message; the events server replies with a "pong" text message. This round-trips through the Lambda backend = true end-to-end liveness.
  • control — protocol-level ws.ping() / 'pong'. Behind API Gateway these are answered at the AWS edge, so they only prove the front door is up, not that the Lambda is reachable.
• Healthcheck now also reports lastActivityTime and secondsSinceLastActivity.

Why app-level is the default

API Gateway WebSocket APIs don't surface protocol ping/pong control frames to the Lambda backend. The matching server-side handler (events-lambda, message === 'ping' → 'pong') has been deployed to prod/staging/beta and verified: text "pong" round-trips on all three stages (prod ~267ms, staging ~177ms, beta ~894ms cold) — comfortably within the 10s pongTimeout.

Tests

New unit coverage for: ping cadence, termination on silence, staying alive under text "pong" replies, staying alive under application messages, reconnect-after-timeout, heartbeat stop on close, and control mode (protocol ping + protocol pong). 100 tests pass, typecheck and lint clean.

🤖 Generated with Claude Code