Introduction to
WebSockets

Client Request

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Extensions: permessage-deflate
Origin: http://example.com

Server Response

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat

// Create connection
const ws = new WebSocket('wss://api.example.com/chat');

// Connection opened
ws.addEventListener('open', (event) => {
  console.log('Connected!');
  ws.send(JSON.stringify({ type: 'join', room: 'general' }));
});

// Listen for messages
ws.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
});

// Handle errors
ws.addEventListener('error', (event) => {
  console.error('WebSocket error:', event);
});

// Connection closed
ws.addEventListener('close', (event) => {
  console.log(`Closed: ${event.code} ${event.reason}`);
  if (!event.wasClean) {
    console.log('Connection lost, reconnecting...');
  }
});

// Send data
ws.send('Hello, server!');
ws.send(new Blob(['binary data']));

// Close gracefully
ws.close(1000, 'Done');

Sending Binary Data

// ArrayBuffer
const buffer = new ArrayBuffer(8);
const view = new DataView(buffer);
view.setFloat64(0, Math.PI);
ws.send(buffer);

// Typed Array
const pixels = new Uint8Array([255, 0, 128, 255]);
ws.send(pixels.buffer);

// Blob
const blob = new Blob(['Hello'], { type: 'text/plain' });
ws.send(blob);

// File from input
fileInput.onchange = (e) => {
  const file = e.target.files[0];
  ws.send(file); // sends as binary
};

Receiving Binary Data

// Set binary type
ws.binaryType = 'arraybuffer'; // or 'blob'

ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    const view = new DataView(event.data);
    const value = view.getFloat64(0);
    console.log('Received float:', value);
  }
};

// Blob approach (for large files)
ws.binaryType = 'blob';
ws.onmessage = async (event) => {
  if (event.data instanceof Blob) {
    const arrayBuf = await event.data.arrayBuffer();
    const bytes = new Uint8Array(arrayBuf);
    renderImage(bytes);
  }
};

Basic Server

import { WebSocketServer } from 'ws';

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

wss.on('connection', (ws, req) => {
  const ip = req.socket.remoteAddress;
  console.log(`Client connected from ${ip}`);

  ws.on('message', (data, isBinary) => {
    const msg = isBinary ? data : data.toString();
    console.log('Received:', msg);

    // Echo to all clients
    wss.clients.forEach((client) => {
      if (client.readyState === WebSocket.OPEN) {
        client.send(msg);
      }
    });
  });

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

  ws.send('Welcome to the server!');
});

With Express / HTTP Server

import express from 'express';
import { createServer } from 'http';
import { WebSocketServer } from 'ws';

const app = express();
const server = createServer(app);
const wss = new WebSocketServer({ server });

// REST endpoints
app.get('/api/status', (req, res) => {
  res.json({
    clients: wss.clients.size,
    uptime: process.uptime()
  });
});

// WebSocket connections
wss.on('connection', (ws) => {
  ws.isAlive = true;
  ws.on('pong', () => { ws.isAlive = true; });
  ws.on('message', (msg) => {
    ws.send(`Echo: ${msg}`);
  });
});

server.listen(3000, () => {
  console.log('HTTP + WS on :3000');
});

Server

import { Server } from 'socket.io';

const io = new Server(3000, {
  cors: { origin: 'http://localhost:5173' }
});

// Namespaces
const chat = io.of('/chat');

chat.on('connection', (socket) => {
  // Join a room
  socket.join('room-42');

  // Listen for events
  socket.on('chat:message', (msg, callback) => {
    // Broadcast to room
    socket.to('room-42').emit('chat:message', {
      user: socket.data.username,
      text: msg,
      ts: Date.now()
    });
    callback({ status: 'ok' }); // acknowledgement
  });

  socket.on('disconnect', (reason) => {
    console.log(`Left: ${reason}`);
  });
});

Client

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000/chat', {
  auth: { token: 'jwt-token-here' },
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionAttempts: 5
});

socket.on('connect', () => {
  console.log('Connected:', socket.id);
});

// Send with acknowledgement
socket.emit('chat:message', 'Hello!', (res) => {
  console.log('Server ack:', res.status);
});

// Receive events
socket.on('chat:message', (data) => {
  renderMessage(data);
});

socket.on('connect_error', (err) => {
  console.log('Auth error:', err.message);
});

Token in Query String

// Client
const ws = new WebSocket(
  `wss://api.example.com/ws?token=${jwt}`
);

// Server (Node.js ws)
wss.on('connection', (ws, req) => {
  const url = new URL(req.url, 'http://localhost');
  const token = url.searchParams.get('token');
  try {
    const user = jwt.verify(token, SECRET);
    ws.userId = user.id;
  } catch (e) {
    ws.close(4001, 'Invalid token');
  }
});

First-Message Auth

ws.on('connection', (ws) => {
  ws.isAuthenticated = false;
  ws.on('message', (data) => {
    if (!ws.isAuthenticated) {
      const { token } = JSON.parse(data);
      if (verifyToken(token)) {
        ws.isAuthenticated = true;
        ws.send(JSON.stringify({ type: 'auth_ok' }));
      } else {
        ws.close(4001, 'Unauthorized');
      }
      return;
    }
    handleMessage(ws, data);
  });
});

Cookie-Based Auth

// Cookies are sent during handshake
// Server reads them from upgrade request
import cookie from 'cookie';

wss.on('connection', (ws, req) => {
  const cookies = cookie.parse(
    req.headers.cookie || ''
  );
  const sessionId = cookies['session_id'];
  const session = await sessionStore
    .get(sessionId);

  if (!session) {
    ws.close(4001, 'No valid session');
    return;
  }
  ws.user = session.user;
});

Server-Side Ping/Pong (ws)

// Server heartbeat interval
const HEARTBEAT_MS = 30_000;

wss.on('connection', (ws) => {
  ws.isAlive = true;
  ws.on('pong', () => { ws.isAlive = true; });
});

const interval = setInterval(() => {
  wss.clients.forEach((ws) => {
    if (!ws.isAlive) {
      console.log('Terminating dead connection');
      return ws.terminate();
    }
    ws.isAlive = false;
    ws.ping(); // client auto-responds pong
  });
}, HEARTBEAT_MS);

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

Client Reconnection with Backoff

class ReconnectingWebSocket {
  #url; #ws; #retries = 0;
  #maxRetries = 10;
  #baseDelay = 1000;

  constructor(url) {
    this.#url = url;
    this.#connect();
  }

  #connect() {
    this.#ws = new WebSocket(this.#url);

    this.#ws.onopen = () => {
      this.#retries = 0; // reset on success
    };

    this.#ws.onclose = (e) => {
      if (e.code !== 1000) this.#reconnect();
    };
  }

  #reconnect() {
    if (this.#retries >= this.#maxRetries) return;
    const delay = this.#baseDelay
      * Math.pow(2, this.#retries)
      + Math.random() * 1000; // jitter
    this.#retries++;
    setTimeout(() => this.#connect(), delay);
  }

  send(data) { this.#ws.send(data); }
}

WebSocket Close Codes

Graceful Error Handling

ws.onerror = (err) => {
  // error event has no useful info
  // in browsers; close follows
  console.error('WS error');
};

ws.onclose = (event) => {
  switch (event.code) {
    case 1000:
      break; // normal
    case 1006:
      scheduleReconnect(); // lost
      break;
    case 4001:
      refreshToken(); // auth failed
      break;
    default:
      logAndReconnect(event);
  }
};

Nginx Configuration

upstream websocket_backend {
    # Use ip_hash for sticky sessions
    ip_hash;
    server 10.0.1.1:8080;
    server 10.0.1.2:8080;
    server 10.0.1.3:8080;
}

server {
    listen 443 ssl;
    server_name ws.example.com;

    ssl_certificate     /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;

    location /ws {
        proxy_pass http://websocket_backend;
        proxy_http_version 1.1;

        # Critical: forward Upgrade headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;

        # Timeouts for idle connections
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;

        # Forward real IP
        proxy_set_header X-Real-IP
          $remote_addr;
        proxy_set_header X-Forwarded-For
          $proxy_add_x_forwarded_for;
    }
}

Origin Checking

wss.on('headers', (headers, req) => {
  const origin = req.headers.origin;
  const allowed = [
    'https://example.com',
    'https://app.example.com'
  ];
  if (!allowed.includes(origin)) {
    req.destroy(); // reject connection
  }
});

Rate Limiting

const rateMap = new Map();

ws.on('message', (data) => {
  const now = Date.now();
  const history = rateMap.get(ws) || [];

  // Remove msgs older than 1 minute
  const recent = history.filter(
    t => now - t < 60_000
  );
  recent.push(now);
  rateMap.set(ws, recent);

  if (recent.length > 100) { // 100/min
    ws.close(4008, 'Rate limit exceeded');
    return;
  }
  handleMessage(ws, data);
});

Integration Test (Jest + ws)

import { WebSocketServer } from 'ws';
import WebSocket from 'ws';

describe('Chat Server', () => {
  let wss, serverUrl;

  beforeAll((done) => {
    wss = new WebSocketServer({ port: 0 });
    setupHandlers(wss);
    const port = wss.address().port;
    serverUrl = `ws://localhost:${port}`;
    done();
  });

  afterAll(() => wss.close());

  test('echoes messages', (done) => {
    const ws = new WebSocket(serverUrl);
    ws.on('open', () => {
      ws.send('hello');
    });
    ws.on('message', (data) => {
      expect(data.toString())
        .toBe('Echo: hello');
      ws.close();
      done();
    });
  });

  test('rejects bad auth', (done) => {
    const ws = new WebSocket(
      `${serverUrl}?token=invalid`
    );
    ws.on('close', (code) => {
      expect(code).toBe(4001);
      done();
    });
  });
});

Load Testing with k6

// k6 script: ws_load.js
import ws from 'k6/ws';
import { check } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 1000 },
    { duration: '1m',  target: 1000 },
    { duration: '10s', target: 0 },
  ],
};

export default function () {
  const url = 'wss://api.example.com/ws';
  const res = ws.connect(url, {}, (socket) => {
    socket.on('open', () => {
      socket.send(JSON.stringify({
        type: 'ping'
      }));
    });
    socket.on('message', (msg) => {
      check(msg, {
        'is pong': (m) =>
          JSON.parse(m).type === 'pong',
      });
    });
    socket.setTimeout(() => {
      socket.close();
    }, 5000);
  });
  check(res, { 'status 101': (r) =>
    r && r.status === 101 });
}