WebSocket Protocol Internals

import { WebSocketServer, WebSocket as WS } from 'ws';
import http from 'http';
import jwt from 'jsonwebtoken';

// npm install ws
// npm install -D @types/ws

const server = http.createServer();
const wss = new WebSocketServer({ server });

interface AuthenticatedSocket extends WS {
  userId?: string;
  isAlive?: boolean;
}

wss.on('connection', (ws: AuthenticatedSocket, req) => {
  // Authenticate on connect via token in query string
  const url = new URL(req.url!, 'ws://localhost');
  const token = url.searchParams.get('token');

  try {
    const payload = jwt.verify(token ?? '', process.env.JWT_SECRET!) as { userId: string };
    ws.userId = payload.userId;
    ws.isAlive = true;
  } catch {
    ws.close(4001, 'Unauthorized'); // custom close code
    return;
  }

  ws.on('message', (data: Buffer) => {
    const message = JSON.parse(data.toString());
    // Echo back to sender
    ws.send(JSON.stringify({ type: 'echo', data: message }));
  });

  ws.on('pong', () => { ws.isAlive = true; }); // heartbeat response

  ws.on('close', (code, reason) => {
    console.log(`Client ${ws.userId} disconnected: ${code} ${reason}`);
  });
});

// ━━ Heartbeat - detect dead connections ━━
// Clients that crash don't always send a close frame - detect with ping/pong
const heartbeat = setInterval(() => {
  wss.clients.forEach((ws) => {
    const socket = ws as AuthenticatedSocket;
    if (!socket.isAlive) { socket.terminate(); return; }
    socket.isAlive = false;
    socket.ping(); // client must respond with pong
  });
}, 30_000); // ping every 30s

wss.on('close', () => clearInterval(heartbeat));
server.listen(3000);