feat: add heartbeat to detect and clean up dead WS connections

[Paranoa-dev]

Add heartbeat ping/pong to detect dead WebSocket connections

Summary

Adds a periodic heartbeat mechanism to IntentsGateway that detects and cleans up dead WebSocket connections (e.g., network drops) that would otherwise remain in the subscribers set indefinitely, silently wasting broadcast() cycles.

Problem

IntentsGateway only removes a subscriber on an explicit error or close event. A connection that goes dead without a clean close (e.g., network drop, mobile sleep, load balancer timeout) stays in the subscribers set indefinitely, causing:

• Wasted broadcast() cycles sending to a socket that will never receive
• Memory leaks from accumulated dead connections
• Potential send errors that could disrupt other clients

Solution

Implemented the standard ws library heartbeat pattern:

How it works

1. On connection: Each client is marked as alive = true and a pong listener is registered
2. Every 30 seconds (HEARTBEAT_INTERVAL_MS):
   • For each subscriber, check if alive === false → if so, client.terminate() and remove from set
   • Otherwise, set alive = false and send ping
3. On pong response: Client is marked alive = true again
4. On module destroy: Heartbeat interval is cleared

Implementation details

• Uses a WeakMap<WebSocket, boolean> to track alive status (avoids monkey-patching the WebSocket instance)
• OnModuleDestroy interface ensures cleanup on application shutdown
• getAliveCount() exposed for observability/monitoring
• 30-second interval matches the ws library recommended pattern

Code changes

src/intents/intents.gateway.ts:

• Added WeakMap<WebSocket, boolean> for alive tracking
• Added setInterval-based heartbeat loop in constructor
• Added pong event handler in handleConnection
• Added heartbeat() private method with terminate logic
• Added onModuleDestroy() for cleanup
• Added getAliveCount() for observability

src/intents/intents.gateway.spec.ts (new):

• Tests connection alive marking
• Tests disconnect cleanup
• Tests dead client termination (no pong response)
• Tests alive client survival (pong received)
• Tests interval cleanup on module destroy
• Tests broadcast to all alive subscribers

Test Results

Unit tests:  24 passed (4 suites, including 6 new gateway heartbeat tests)
E2e tests:   23 passed (5 suites)
Total:       47 tests passing

Migration Notes

When scaling to multiple instances, the heartbeat pattern remains the same since each instance maintains its own WebSocket connections. No cross-instance coordination is needed.

Checklist

• Periodic ping sent to all connected clients
• Pong response marks client as alive
• Dead clients (no pong within interval) are terminated
• Terminated clients removed from subscriber set
• Heartbeat interval cleaned up on module destroy
• Unit tests for all heartbeat behaviors
• npm run lint passes
• npm run typecheck passes (pre-existing errors only)
• npm test passes
• npm run test:e2e passes

Closes #81

[drips-wave]

@Paranoa-dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits