WebSocket Implementation Guide

WebSockets enable bidirectional, real-time communication between clients and servers. Here's how to implement them effectively.

Basic WebSocket Server#

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

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

// Connection handling
wss.on('connection', (ws: WebSocket, req) => {
  const clientId = crypto.randomUUID();
  console.log(`Client connected: ${clientId}`);

  // Handle incoming messages
  ws.on('message', (data) => {
    try {
      const message = JSON.parse(data.toString());
      handleMessage(ws, clientId, message);
    } catch (error) {
      ws.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
    }
  });

  // Handle disconnection
  ws.on('close', () => {
    console.log(`Client disconnected: ${clientId}`);
    cleanupClient(clientId);
  });

  // Handle errors
  ws.on('error', (error) => {
    console.error(`WebSocket error for ${clientId}:`, error);
  });

  // Send welcome message
  ws.send(JSON.stringify({
    type: 'connected',
    clientId,
    timestamp: new Date().toISOString(),
  }));
});

function handleMessage(ws: WebSocket, clientId: string, message: any) {
  switch (message.type) {
    case 'ping':
      ws.send(JSON.stringify({ type: 'pong' }));
      break;
    case 'subscribe':
      subscribeToChannel(clientId, message.channel);
      break;
    case 'unsubscribe':
      unsubscribeFromChannel(clientId, message.channel);
      break;
    default:
      ws.send(JSON.stringify({ type: 'error', message: 'Unknown message type' }));
  }
}

server.listen(3000);

Socket.io Implementation#

import { Server } from 'socket.io';
import http from 'http';

const httpServer = http.createServer();
const io = new Server(httpServer, {
  cors: {
    origin: process.env.ALLOWED_ORIGINS?.split(','),
    credentials: true,
  },
  pingTimeout: 60000,
  pingInterval: 25000,
});

// Authentication middleware
io.use(async (socket, next) => {
  const token = socket.handshake.auth.token;

  try {
    const user = await verifyToken(token);
    socket.data.user = user;
    next();
  } catch {
    next(new Error('Authentication failed'));
  }
});

// Connection handling
io.on('connection', (socket) => {
  const user = socket.data.user;
  console.log(`User connected: ${user.id}`);

  // Join user's personal room
  socket.join(`user:${user.id}`);

  // Join organization room
  if (user.organizationId) {
    socket.join(`org:${user.organizationId}`);
  }

  // Handle room subscription
  socket.on('join', (room: string) => {
    if (canJoinRoom(user, room)) {
      socket.join(room);
      socket.emit('joined', { room });
    } else {
      socket.emit('error', { message: 'Cannot join room' });
    }
  });

  // Handle messages
  socket.on('message', async (data) => {
    try {
      const message = await saveMessage(user.id, data);
      io.to(data.room).emit('message', message);
    } catch (error) {
      socket.emit('error', { message: 'Failed to send message' });
    }
  });

  // Handle typing indicators
  socket.on('typing:start', (room) => {
    socket.to(room).emit('typing', { userId: user.id, typing: true });
  });

  socket.on('typing:stop', (room) => {
    socket.to(room).emit('typing', { userId: user.id, typing: false });
  });

  // Cleanup on disconnect
  socket.on('disconnect', () => {
    console.log(`User disconnected: ${user.id}`);
  });
});

httpServer.listen(3000);

Client Implementation#

// Socket.io client
import { io, Socket } from 'socket.io-client';

class WebSocketClient {
  private socket: Socket | null = null;
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 5;

  connect(token: string): void {
    this.socket = io(process.env.WS_URL!, {
      auth: { token },
      reconnection: true,
      reconnectionAttempts: this.maxReconnectAttempts,
      reconnectionDelay: 1000,
      reconnectionDelayMax: 5000,
    });

    this.socket.on('connect', () => {
      console.log('Connected to WebSocket');
      this.reconnectAttempts = 0;
    });

    this.socket.on('disconnect', (reason) => {
      console.log('Disconnected:', reason);
    });

    this.socket.on('connect_error', (error) => {
      console.error('Connection error:', error);
      this.reconnectAttempts++;
    });
  }

  join(room: string): void {
    this.socket?.emit('join', room);
  }

  sendMessage(room: string, content: string): void {
    this.socket?.emit('message', { room, content });
  }

  onMessage(callback: (message: any) => void): void {
    this.socket?.on('message', callback);
  }

  disconnect(): void {
    this.socket?.disconnect();
    this.socket = null;
  }
}

// React hook
function useWebSocket(token: string) {
  const [connected, setConnected] = useState(false);
  const [messages, setMessages] = useState<Message[]>([]);
  const clientRef = useRef<WebSocketClient>();

  useEffect(() => {
    const client = new WebSocketClient();
    client.connect(token);
    clientRef.current = client;

    client.socket?.on('connect', () => setConnected(true));
    client.socket?.on('disconnect', () => setConnected(false));

    client.onMessage((message) => {
      setMessages((prev) => [...prev, message]);
    });

    return () => client.disconnect();
  }, [token]);

  const sendMessage = useCallback((room: string, content: string) => {
    clientRef.current?.sendMessage(room, content);
  }, []);

  return { connected, messages, sendMessage };
}

Scaling with Redis#

import { Server } from 'socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

// Create Redis clients
const pubClient = createClient({ url: process.env.REDIS_URL });
const subClient = pubClient.duplicate();

await Promise.all([pubClient.connect(), subClient.connect()]);

// Configure Socket.io with Redis adapter
const io = new Server(httpServer);
io.adapter(createAdapter(pubClient, subClient));

// Now events are shared across all instances
io.to('room1').emit('message', { text: 'Hello' }); // Reaches all clients in room1

// Broadcast to all connected clients across instances
io.emit('announcement', { text: 'Server maintenance in 5 minutes' });

// Get connected sockets count across instances
const sockets = await io.fetchSockets();
console.log(`Total connected: ${sockets.length}`);

Presence System#

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

class PresenceManager {
  private readonly TTL = 30; // seconds

  async setOnline(userId: string, socketId: string): Promise<void> {
    const key = `presence:${userId}`;
    await redis.hset(key, 'socketId', socketId, 'lastSeen', Date.now().toString());
    await redis.expire(key, this.TTL);
  }

  async setOffline(userId: string): Promise<void> {
    await redis.del(`presence:${userId}`);
  }

  async isOnline(userId: string): Promise<boolean> {
    return (await redis.exists(`presence:${userId}`)) === 1;
  }

  async getOnlineUsers(userIds: string[]): Promise<string[]> {
    const pipeline = redis.pipeline();
    userIds.forEach((id) => pipeline.exists(`presence:${id}`));
    const results = await pipeline.exec();

    return userIds.filter((_, index) => results?.[index]?.[1] === 1);
  }

  async heartbeat(userId: string): Promise<void> {
    const key = `presence:${userId}`;
    await redis.hset(key, 'lastSeen', Date.now().toString());
    await redis.expire(key, this.TTL);
  }
}

const presence = new PresenceManager();

// In Socket.io connection handler
io.on('connection', async (socket) => {
  const userId = socket.data.user.id;

  // Mark as online
  await presence.setOnline(userId, socket.id);

  // Notify friends
  const friends = await getFriends(userId);
  friends.forEach((friendId) => {
    io.to(`user:${friendId}`).emit('presence', {
      userId,
      status: 'online',
    });
  });

  // Heartbeat interval
  const heartbeatInterval = setInterval(() => {
    presence.heartbeat(userId);
  }, 10000);

  socket.on('disconnect', async () => {
    clearInterval(heartbeatInterval);
    await presence.setOffline(userId);

    // Notify friends
    friends.forEach((friendId) => {
      io.to(`user:${friendId}`).emit('presence', {
        userId,
        status: 'offline',
      });
    });
  });
});

Room-Based Chat#

interface Room {
  id: string;
  name: string;
  members: Set<string>;
}

const rooms = new Map<string, Room>();

io.on('connection', (socket) => {
  const userId = socket.data.user.id;

  socket.on('room:create', async (name: string, callback) => {
    const room: Room = {
      id: crypto.randomUUID(),
      name,
      members: new Set([userId]),
    };

    rooms.set(room.id, room);
    socket.join(room.id);

    callback({ success: true, room: { id: room.id, name: room.name } });
  });

  socket.on('room:join', async (roomId: string, callback) => {
    const room = rooms.get(roomId);

    if (!room) {
      return callback({ success: false, error: 'Room not found' });
    }

    room.members.add(userId);
    socket.join(roomId);

    // Notify room members
    socket.to(roomId).emit('room:user_joined', {
      userId,
      roomId,
    });

    callback({ success: true });
  });

  socket.on('room:message', async (data: { roomId: string; content: string }) => {
    const room = rooms.get(data.roomId);

    if (!room || !room.members.has(userId)) {
      return socket.emit('error', { message: 'Not a room member' });
    }

    const message = {
      id: crypto.randomUUID(),
      roomId: data.roomId,
      userId,
      content: data.content,
      timestamp: new Date().toISOString(),
    };

    // Save to database
    await saveMessage(message);

    // Broadcast to room
    io.to(data.roomId).emit('room:message', message);
  });
});

Error Handling and Reconnection#

// Client-side reconnection handling
const socket = io(WS_URL, {
  reconnection: true,
  reconnectionAttempts: 10,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 10000,
  timeout: 20000,
});

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

  // Rejoin rooms after reconnection
  const rooms = getStoredRooms();
  rooms.forEach((room) => socket.emit('join', room));
});

socket.on('disconnect', (reason) => {
  if (reason === 'io server disconnect') {
    // Server initiated disconnect, need to manually reconnect
    socket.connect();
  }
  // Otherwise socket.io will auto-reconnect
});

socket.on('reconnect_attempt', (attempt) => {
  console.log(`Reconnection attempt ${attempt}`);
});

socket.on('reconnect_failed', () => {
  console.error('Failed to reconnect');
  showReconnectionDialog();
});

Best Practices#

Connection:
✓ Implement authentication
✓ Handle reconnection gracefully
✓ Use heartbeats for presence
✓ Clean up on disconnect

Scaling:
✓ Use Redis adapter for multiple instances
✓ Implement sticky sessions or Redis
✓ Monitor connection counts
✓ Set appropriate timeouts

Performance:
✓ Batch messages when possible
✓ Use binary data for large payloads
✓ Implement message compression
✓ Rate limit messages per client

WebSockets enable powerful real-time features. Use Socket.io for easier handling, Redis for scaling, and implement proper presence and reconnection logic. Monitor connection health and plan for graceful degradation when WebSockets aren't available.