WebSocket frame format: opcodes, masking, fragmentation

After the WebSocket handshake the HTTP parser is gone. What flows on the wire is a compact binary format that carries every message — text, binary, keepalive pings, and graceful closes — in as few as 2 bytes of overhead. Understanding that format is what separates “it sometimes works” from “I know exactly what broke.”

The frame header anatomy

A WebSocket frame starts with 2 mandatory bytes, followed by optional length extension and masking key fields, and then the payload:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-------+-+-------------+-------------------------------+
|F|R|R|R| opcode|M| Payload len |    Extended payload length    |
|I|S|S|S|  (4)  |A|     (7)    |             (16/64)           |
|N|V|V|V|       |S|             |   (if payload len==126/127)   |
| |1|2|3|       |K|             |                               |
+-+-+-+-+-------+-+-------------+-------------------------------+
|     Masking-key (if MASK set, 4 bytes)                        |
+---------------------------------------------------------------+
|                    Payload data                               |
+---------------------------------------------------------------+

Byte 1 breakdown:

• FIN (bit 7) — 1 means this is the last (or only) fragment of a message.
• RSV1-3 (bits 6-4) — reserved for extensions (e.g., permessage-deflate sets RSV1=1).
• Opcode (bits 3-0) — what kind of data the frame carries:

Byte 2 breakdown:

• MASK (bit 7) — 1 = payload is XOR-masked (client→server always; server→client never).
• Payload length (bits 6-0):
  • 0–125 — the actual length.
  • 126 — next 2 bytes (uint16) hold the real length.
  • 127 — next 8 bytes (uint64) hold the real length.

Frame overhead totals:

• Small server→client frame: 2 bytes header only.
• Small client→server frame: 2 bytes header + 4 bytes masking key = 6 bytes.

Why client frames must be masked

Masking is not encryption — it is a cache-poisoning defense. Here is the attack it prevents:

A malicious JavaScript on site-a.com opens a WebSocket connection to an intermediate proxy. It then sends bytes that happen to spell out a valid HTTP response. If the proxy is naive and stateless, it treats those bytes as HTTP and reflects them to other clients — poisoning its cache.

With masking, the client XORs every payload byte with a 4-byte random key sent in the frame header:

masked_byte[i] = payload[i] XOR mask_key[i % 4]

The receiver XORs back with the same key to recover the original payload. Because the mask key is random per frame, the JavaScript on the malicious site cannot pre-craft bytes that both look like an HTTP response AND decode correctly under XOR. The attack becomes infeasible.

Server frames are not masked because JavaScript on site-a.com cannot read raw bytes from a server response on site-b.com anyway (same-origin policy blocks it).

Fragmentation and continuation frames

A large message can be split across multiple frames. Rules:

1. First fragment: real opcode (0x1 or 0x2), FIN=0.
2. Middle fragments: opcode 0x0 (continuation), FIN=0.
3. Last fragment: opcode 0x0, FIN=1.

The receiver reassembles in order. Control frames (ping, pong, close) cannot be fragmented and are limited to 125 bytes; they can arrive interleaved between data fragments.

Control frames: ping, pong, close

Ping (0x9): a keepalive probe. The receiver must reply with a pong carrying the same payload. Proxies often have idle timeouts (60 seconds is common); sending a ping every 25–30 seconds resets the proxy’s timer and keeps the connection alive.

Pong (0xA): the mandatory reply to a ping. Can also be sent unsolicited as a unilateral heartbeat.

Close (0x8): initiates the closing handshake. The body contains an optional 2-byte status code followed by UTF-8 reason text. Standard codes:

After sending a close frame, each side must wait for the peer’s close frame before closing the TCP connection.