The Complete Production SOP: How to Deploy and Run ws High-Performance Native WebSockets & Heartbeat Pings in Autonomous AI Agents

---
name: "ws-native-websockets-heartbeat"
description: "Deploy high-density WebSocket servers in Node.js with strict ping/pong connection healthchecks."
metadata:
  author: "WebSockets"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "setup ws websocket server"
  - "implement websocket heartbeat ping pong"
  - "handle dead websocket connections"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# ws High-Performance Native WebSockets & Heartbeat Pings

Configures ws package: creating WebSocketServer instances, managing client connection pools, implementing heartbeat ping/pong intervals to detect dead sockets, message compression (permessage-deflate), and rate limiting.

import { WebSocket } from 'ws';

export interface ExtWebSocket extends WebSocket {
  isAlive: boolean;
  sessionId?: string;
}

import { WebSocketServer, WebSocket } from 'ws';
import type { ExtWebSocket } from './types/websocket';

const PORT = Number(process.env.WS_PORT) || 8080;
const HEARTBEAT_INTERVAL_MS = 30000;

export const wss = new WebSocketServer({ port: PORT });

function heartbeat(this: ExtWebSocket): void {
  this.isAlive = true;
}

wss.on('connection', (socket: WebSocket) => {
  const ws = socket as ExtWebSocket;
  ws.isAlive = true;

  ws.on('pong', heartbeat);

  ws.on('message', (data) => {
    // Guard against unhandled buffers
    const message = data.toString();
    ws.send(`Echo: ${message}`);
  });

  ws.on('error', (err) => {
    console.error('Socket error encountered:', err.message);
  });
});

const interval = setInterval(() => {
  wss.clients.forEach((client) => {
    const ws = client as ExtWebSocket;
    if (!ws.isAlive) {
      // Hard socket teardown; skips TCP FIN handshake if connection is half-open
      return ws.terminate();
    }
    ws.isAlive = false;
    ws.ping();
  });
}, HEARTBEAT_INTERVAL_MS);

wss.on('close', () => {
  clearInterval(interval);
});

console.log(`Native ws server running on port ${PORT}`);

import { describe, it, expect, afterAll } from 'vitest';
import { WebSocket } from 'ws';
import { wss } from '../src/server';

describe('WebSocket Heartbeat Gate', () => {
  afterAll(() => {
    wss.close();
  });

  it('should initialize client connection and register pong listener', async () => {
    const client = new WebSocket(`ws://localhost:${wss.options.port}`);
    await new Promise<void>((resolve) => client.on('open', () => resolve()));
    
    expect(wss.clients.size).toBe(1);
    client.terminate();
  });
});