Validating WebSocket Messages

Analogy categoryAnalogies

Why Message Validation Matters

A REST API typically gets schema validation almost for free from framework middleware and a documented contract per endpoint, but a WebSocket connection is a single open pipe carrying an arbitrary stream of messages that the developer must parse and validate one at a time, by hand, for the life of the connection. Every incoming frame is untrusted input — it could be malformed JSON, an unexpected type, an oversized payload, or a deliberately crafted message designed to crash a naive parser or trigger unintended server behavior — and unlike a REST request that fails once and returns a 400, a bad WebSocket message that isn't validated can corrupt in-memory state that persists for the rest of the connection's lifetime.

🏏

Cricket analogy: A stadium's ticket scanner checks each ticket at the gate once, but a season-long member entering through a special gate needs their credentials effectively re-verified every single match, since one bad admission early on could let an unauthorized person into every future game, mirroring why every WebSocket message needs its own validation rather than trusting the initial handshake.

Schema Validation Approaches

The most reliable pattern is to define a strict schema for every message type your protocol supports — using a library like Zod (TypeScript-first, runtime validation) or Ajv (JSON Schema-based) — and run every parsed message through that schema before any business logic touches it, rejecting anything that doesn't match with a structured error frame sent back to the client rather than a thrown exception that could crash the connection handler. This turns 'is this message shaped correctly' from an ad-hoc series of if-checks scattered through your handler code into a single declarative gate that's easy to test, easy to extend when you add new message types, and hard to accidentally bypass.

🏏

Cricket analogy: The ICC's standardized pitch report template forces every ground curator to fill in the same fields in the same format before a match is sanctioned, rather than each ground submitting free-form notes, mirroring a schema forcing every WebSocket message into a validated, predictable shape.

Handling Untrusted Payloads Safely

Beyond shape validation, a WebSocket server needs explicit guardrails against resource-exhaustion and injection risks: set a maxPayload option (the ws library defaults to no limit unless you configure one) to reject oversized messages before they're even fully buffered into memory, never use unsafe deserialization functions like eval() or Function() on message content, and — critically for chat or collaborative apps — sanitize any user-supplied text before broadcasting it to other connected clients, since an unsanitized message containing HTML or script tags becomes a stored cross-site scripting vector the moment it's relayed to another user's browser and rendered without escaping.

🏏

Cricket analogy: A stadium enforces a strict bag-size limit at security, rejecting oversized bags before they even reach the seating area, mirroring a maxPayload limit rejecting oversized WebSocket messages before they're fully buffered into memory.

Versioning and Type Discrimination

Most WebSocket protocols multiplex several logical message kinds over one connection — chat messages, presence updates, typing indicators — so a discriminated 'type' field is the standard way to route each parsed message to the correct handler, with the schema for the rest of the payload varying by that type value. Unknown or unrecognized type values should be handled gracefully (logged and ignored, or answered with an explicit 'unsupported message type' error) rather than crashing the handler, which also gives you a forward-compatible path for rolling out new message types to a subset of clients without breaking older ones still connected.

🏏

Cricket analogy: A single stadium PA system routes different announcement types (boundary alerts, wicket updates, weather delays) through different templates based on a category tag, gracefully ignoring any category it doesn't recognize rather than crashing, mirroring type-based message routing.

typescript

import { z } from 'zod';

const ChatMessage = z.object({
  type: z.literal('chat'),
  roomId: z.string().uuid(),
  text: z.string().min(1).max(2000),
});

const TypingIndicator = z.object({
  type: z.literal('typing'),
  roomId: z.string().uuid(),
});

const IncomingMessage = z.discriminatedUnion('type', [ChatMessage, TypingIndicator]);

ws.on('message', (raw) => {
  let parsed;
  try {
    parsed = IncomingMessage.parse(JSON.parse(raw.toString()));
  } catch (err) {
    ws.send(JSON.stringify({ type: 'error', message: 'Invalid message format' }));
    return;
  }

  switch (parsed.type) {
    case 'chat':
      broadcastChat(parsed.roomId, sanitizeHtml(parsed.text), ws.userId);
      break;
    case 'typing':
      broadcastTyping(parsed.roomId, ws.userId);
      break;
  }
});

The ws library's maxPayload option (e.g., new WebSocket.Server({ maxPayload: 64 * 1024 })) rejects oversized frames at the protocol level before they're fully buffered into memory, which is your first line of defense against memory-exhaustion attacks via giant messages.

Broadcasting unsanitized user-supplied text to other connected clients is a stored XSS vector — if a chat message containing <script> tags is relayed as-is and rendered without escaping in another user's browser, it executes with that victim's session privileges. Always sanitize or escape before broadcast, and again on render as defense in depth.

Every WebSocket message is untrusted input that must be individually parsed and validated, unlike REST endpoints that get schema validation largely for free.
A bad, unvalidated message can corrupt in-memory connection state for the rest of the connection's lifetime, not just fail once like a REST request.
Schema libraries like Zod or Ajv turn ad-hoc validation checks into a single declarative, testable gate applied to every message.
Set an explicit maxPayload limit to reject oversized messages before they're fully buffered into memory.
Never use unsafe deserialization (eval, Function) on message content, and always sanitize user text before broadcasting to other clients.
Use a discriminated 'type' field to route messages to handlers, gracefully ignoring unrecognized types for forward compatibility.