Mastering WebSocket: From API Basics to Advanced Protocol Insights

Preface

Before WebSocket was widely supported, developers relied on hacks like long polling to simulate real‑time connections, which consumed extra CPU, memory, and bandwidth. WebSocket, introduced with HTML5, offers full‑duplex communication, allowing browsers to exchange text and binary messages over a TCP‑based API.

Connection negotiation and same‑origin policy

Interoperability with existing HTTP infrastructure

Message‑based communication and efficient framing

Sub‑protocol negotiation and extensibility

While WebSocket simplifies many tasks, it does not provide built‑in services such as state management, compression, or caching, so developers must handle these themselves.

1. WebSocket API

The WebSocket object provides a simple API for creating and managing connections and sending/receiving data.

var ws = new WebSocket('wss://example.com/socket'); // create secure WebSocket connection
ws.onerror = function (error) { ... } // error handling
ws.onclose = function () { ... } // close handling
ws.onopen = function () {
  ws.send("Connection established. Hello server!"); // send message
}
ws.onmessage = function(msg) {
  if (msg.data instanceof Blob) {
    processBlob(msg.data);
  } else {
    processText(msg.data);
  }
}

1.1 Receiving and Sending Data

WebSocket supports both text and binary data. Binary messages can be received as ArrayBuffer or Blob, and the API handles buffering and parsing automatically.

var wss = new WebSocket('wss://example.com/socket');
ws.binaryType = "arraybuffer";

// Receive data
wss.onmessage = function(msg) {
  if (msg.data instanceof ArrayBuffer) {
    processArrayBuffer(msg.data);
  } else {
    processText(msg.data);
  }
}

// Send data
ws.onopen = function () {
  socket.send("Hello server!");
  socket.send(JSON.stringify({msg: 'payload'}));
  var buffer = new ArrayBuffer(128);
  socket.send(buffer);
  var intview = new Uint32Array(buffer);
  socket.send(intview);
  var blob = new Blob([buffer]);
  socket.send(blob);
}

Blob objects contain read‑only raw data and are stored on disk; ArrayBuffer represents a fixed‑length binary buffer in memory. Choose Blob for immutable file‑like data and ArrayBuffer when further processing is needed.

WebSocket’s send() method is asynchronous; large messages are queued, and the bufferedAmount property can be used to monitor queued data and avoid head‑of‑line blocking.

var ws = new WebSocket('wss://example.com/socket');
ws.onopen = function () {
  subscribeToApplicationUpdates(function(evt) {
    if (ws.bufferedAmount == 0) ws.send(evt.data);
  });
};

1.2 Sub‑protocol Negotiation

Since WebSocket does not define a built‑in way to convey message metadata, clients and servers can agree on a sub‑protocol during the handshake. The optional second argument to the constructor specifies an array of protocol names.

var ws = new WebSocket('wss://example.com/socket', ['appProtocol', 'appProtocol-v2']);
ws.onopen = function () {
  if (ws.protocol == 'appProtocol-v2') {
    // use version 2
  } else {
    // fallback
  }
};

If the server supports one of the offered protocols, the connection succeeds and ws.protocol reflects the selected protocol; otherwise the handshake fails.

1.3 WS vs WSS

WebSocket URIs use ws:// for unencrypted traffic (port 80) and wss:// for TLS‑encrypted traffic (port 443). Encrypted connections hide data from intermediate devices, preventing special handling or inspection.

2. WebSocket Protocol

RFC 6455 defines a two‑stage process: an HTTP‑based handshake to negotiate parameters, followed by a binary framing layer for low‑overhead message exchange.

2.1 Data Framing

Each message is split into one or more frames. A frame header contains fields such as FIN, RSV1‑3, opcode, MASK, and payload length. The payload may include optional extension data followed by application data.

FIN : 1 bit, indicates final frame of a message.

RSV1‑3 : 1 bit each, must be 0 unless an extension defines otherwise.

opcode : 4 bits, defines frame type (text, binary, close, ping, pong, etc.).

Mask : 1 bit, set to 1 for client‑to‑server frames.

Payload length : 7, 7+16, or 7+64 bits depending on size.

Masking‑key : 0 or 4 bytes, used by client to mask payload.

Extension data and Application data : variable length.

Frames are the smallest communication unit; a message may consist of multiple frames.

Control frames (close, ping, pong) must be ≤125 bytes and cannot be fragmented.

2.2 Protocol Extensions

Two notable extensions are:

Multiplexing : adds a channel ID to share a single TCP connection among multiple logical WebSocket streams.

Compression : negotiates per‑message compression similar to HTTP’s content‑encoding.

2.3 Upgrade Negotiation

During the handshake the client sends an HTTP GET request with headers such as Upgrade: websocket, Connection: Upgrade, Sec-WebSocket-Key, Sec-WebSocket-Version, and optional Sec-WebSocket-Protocol and Sec-WebSocket-Extensions. The server must respond with status 101 and matching headers, including Sec-WebSocket-Accept (a SHA‑1 hash of the key plus a GUID) and, if applicable, the selected protocol and extensions.

GET /socket HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: appProtocol, appProtocol-v2
Sec-WebSocket-Extensions: x-webkit-deflate-message, x-custom-extension

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: appProtocol-v2
Sec-WebSocket-Extensions: x-custom-extension

If any required header is missing or mismatched, the client must abort the connection.

3. Use Cases and Performance

WebSocket’s minimal API and binary framing make it ideal for real‑time applications, but it is not a universal replacement for XHR or Server‑Sent Events (SSE). Choosing the right transport impacts latency, bandwidth, and resource consumption.

Request/Response Flow

XHR is request‑response oriented; SSE provides server‑to‑client streaming but cannot send data from client to server. WebSocket enables full‑duplex communication over a single persistent TCP connection, reducing round‑trip latency.

Message Overhead

After the handshake, each WebSocket frame adds 2–14 bytes of overhead. By contrast, XHR carries 500–800 bytes of HTTP headers, while HTTP/2 can reduce header overhead to ~8 bytes. SSE adds 5 bytes per UTF‑8 message.

These figures exclude lower‑layer IP/TCP/TLS overhead (≈60–100 bytes per packet).

Efficiency and Compression

HTTP can negotiate gzip compression per request; SSE can compress the whole stream; WebSocket lacks built‑in compression, requiring custom per‑message compression extensions, which are not yet widely supported.

Custom Application Protocols

WebSocket allows developers to define their own message formats, but they must implement features normally provided by HTTP such as caching, state management, and metadata delivery.

Deployment Considerations

Long‑lived connections can be disrupted by aggressive idle‑timeout settings on routers, load balancers, and proxies. Developers should ensure infrastructure components support persistent connections and monitor resource usage (sockets, memory). Fallback mechanisms like Socket.IO can provide alternative transports when WebSocket is blocked.

Conclusion

WebSocket is designed for real‑time bidirectional communication, offering efficient text and binary transfer while requiring developers to handle services normally supplied by HTTP. Selecting the appropriate transport—WebSocket, XHR, or SSE—depends on the specific scenario to achieve optimal performance.

Socket.IO

Socket.IO abstracts differences between browsers and provides fallback transports (WebSocket, Flash socket, AJAX long polling, multipart streaming, forever iframe, JSONP polling) to achieve real‑time communication across platforms.

References

WEB Performance Guide – WebSocket

RFC 6455

WebSocket Summary

MDN – WebSocket API

ABNF Syntax Specification

HTTP 1.1 Study Notes

HTTP 2.0 Brief Notes