Web and networkingDive 07 of 12
WebSockets, down to the frame
Why the web needed a full-duplex pipe, how an HTTP request turns into one, and what every bit of a WebSocket frame means on top of a TCP stream.
- Levels
- 8
- Reading
- 40 min
- Depth
- Idea to Machine
- Published
The word Hello
, as your browser puts it on the wire inside a WebSocket:
FIN + textlast fragment, opcode 1
Mask + lengthmasked, 5 bytes follow
Masking key32 random bits, new for every frame
PayloadH e l l o, each byte XORed with the key
Key 37 FA 21 3D is the one RFC 6455 uses in its own example. Send it again to draw a fresh key, like a browser does.
The web was built to answer, not to talk
Picture a team chat. Ana types Hello
and presses Enter. Ben, in another city, should see it appear in his window before Ana's finger has left the key. That is the whole requirement: when something happens on the server, tell the browser now.
The web was not built for that. HTTP is a request and response protocol: the client asks, the server answers, and the server never speaks first. Ana's browser can send her message to the server easily enough, as a POST. The hard part is the other half. The server has a message for Ben and no way to deliver it, because Ben's browser hasn't asked for anything.
For about a decade, the web worked around this with tricks. Each one bent HTTP a little further, and each one taught the next generation what a real solution would need.
Short polling: ask again and again
The simplest trick is to ask on a timer. Every few seconds, Ben's browser sends GET /messages?since=1041. Most of the time the answer is empty. When Ana's message lands on the server it sits there until Ben's next poll comes by, so the delay is anywhere between zero and a full polling interval, plus the round trip. Make the interval shorter and the delay falls, but the number of requests climbs, and each one drags a full set of HTTP headers along: often several hundred bytes, and more once cookies get involved, to learn that nothing happened.
Long polling: ask, and let the server hold the answer
Long polling, part of a family of techniques that got the name An umbrella term coined by Alex Russell in 2006 for server push over plain HTTP: long polling, hidden iframes streaming script tags, and similar tricks., flips the waiting around. The browser sends a request, and the server doesn't answer until it has something to say, or until a timeout of 20 to 30 seconds expires. When the answer arrives, the browser immediately sends the next request. Delivery is now nearly instant, with one catch: right after a response, there is a gap of a full round trip before the next request reaches the server. A burst of messages lands in that gap and waits. RFC 6202 catalogues the remaining problems: header overhead on every message, connection limits, and proxies that time out or buffer held requests.
Server-sent events: one response that never ends
The next step was to never finish the response at all. With EventSource in the browser, text/event-stream on the wire. Specified in the WHATWG HTML standard. Reconnects automatically and can resume with the Last-Event-ID header. (SSE), the server answers once with Content-Type: text/event-stream and then keeps writing data: lines whenever it has news. That gives true push, with tiny per-message overhead and automatic reconnection built into the browser. But it only goes one way. Ana's message still travels to the server as a separate request, and SSE carries UTF-8 text only, so binary data has to be encoded. Over HTTP/1.1 each open stream also uses up one of the roughly six connections a browser allows per host.
Try them side by side. Every lane below handles the same 30 seconds of messages on the same network. The bars show how long each message waited between reaching the server and reaching Ben's browser.
The last lane is the subject of this dive. A WebSocket starts life as one ordinary HTTP request, asks the server to switch protocols, and from then on the TCP connection belongs to a much simpler protocol: small binary frames, sent by either side whenever it likes. Ana's message travels up as a frame; the server pushes it down to Ben as a frame. No headers, no new requests, no polling. Each message costs 2 to 14 bytes of framing.
| Short polling | Long polling | SSE | WebSocket | |
|---|---|---|---|---|
| Server can push | No, waits for the next poll | Yes, if a request is waiting | Yes | Yes |
| Client to server | Separate requests | Separate requests | Separate requests | Same connection |
| Overhead per message | Full HTTP request and response | Full HTTP request and response | A few bytes of text framing | 2 to 14 bytes |
| Binary data | Yes | Yes | No, UTF-8 text only | Yes |
| Reconnects by itself | Every poll is a fresh start | Every poll is a fresh start | Yes, with Last-Event-ID | No, your code must do it |
| Plain HTTP all the way | Yes | Yes | Yes | Only the first request |
The last two rows are the price. SSE and polling are plain HTTP, so every cache, proxy, load balancer and debugging tool on the path understands them. A WebSocket stops being HTTP after its first exchange, and a lot of this dive is about what that costs and why the protocol looks the way it does as a result.
A short history, because it explains some odd details later. Ian Hickson's HTML5 drafts sketched a TCPConnection API around 2006 and 2007, and it was renamed WebSocket in 2008. The protocol went through many drafts, at least one serious security scare (you'll meet it in level 7), and was published as RFC 6455 in December 2011. The browser API now lives in the WHATWG WebSockets Standard. Later RFCs added compression (RFC 7692) and ways to run WebSockets over HTTP/2 (RFC 8441) and HTTP/3 (RFC 9220).
A WebSocket is one HTTP request that turns into a long-lived, two-way channel of framed messages.
Four events and a send button
Before looking at the wire, look at what a web developer actually touches. The browser API is small: a constructor, two methods, four events and a handful of read-only properties. Here is Ben's chat client.
const ws = new WebSocket("wss://chat.example/rooms/42", ["chat.v1"]);
ws.binaryType = "arraybuffer";
ws.addEventListener("open", () => {
ws.send("Hello");
});
ws.addEventListener("message", (event) => {
// a string for text frames, an ArrayBuffer for binary ones
render(event.data);
});
ws.addEventListener("close", (event) => {
console.log(event.code, event.reason, event.wasClean);
});
ws.addEventListener("error", () => {
// no details on purpose; a close event always follows
});The constructor takes a ws: or wss: URL, the WebSocket equivalents of http: and https:, and an optional list of Application-level protocol names the client offers, sent in Sec-WebSocket-Protocol. The server picks at most one, and ws.protocol tells you which.. It returns immediately. The connection happens in the background, and the socket starts in the CONNECTING state. From then on, everything is events.
openfires once the handshake succeeds. Now you may send.messagefires once per complete message.event.datais a string for text messages, and aBloborArrayBufferfor binary ones depending onbinaryType.errorfires when something went wrong. It carries no details at all, deliberately: if scripts could tellconnection refused
fromnot a WebSocket server
orTLS failed
, any page could map your internal network by trying addresses.closealways comes last, exactly once, with a numericcode, areasonstring and awasCleanflag.
Drive a socket through its life below. The rules are the real ones from the WHATWG standard: try sending before it opens, closing before it opens, or closing with a code you aren't allowed to use.
- 0CONNECTING
- 1OPEN
- 2CLOSING
- 3CLOSED
Your code
The other side
readyState- none
bufferedAmount- 0
What your handlers see
- Start with
new WebSocket(url).
A few of those rules deserve a closer look, because they bite in production.
Messages, not streams. You send a message and the other side receives that message, whole, in one event. You never get half of one, and you never get two glued together. That is a big step up from raw TCP, where you would have to invent framing yourself. The flip side: a 50 MB message is buffered entirely before your message handler runs, and the API has no way to stream it.
No custom headers. The constructor has no options for headers, so you can't add Authorization: Bearer …. Cookies for the target host do go along with the handshake. Otherwise, the usual workarounds are a short-lived ticket in the URL's query string, a token sent as the first message after open, or, as a hack, smuggling the token in the subprotocol list.
send() never blocks and never says no. It queues the data and returns. The amount queued but not yet handed to the network is visible in bufferedAmount, and nothing stops you from queueing gigabytes. After the socket starts closing, send() silently discards your data while still counting it in bufferedAmount. Level 4 comes back to this.
Close codes are partly reserved. Scripts may only close with 1000 or a code from 3000 to 4999. The other codes describe things only the protocol layer can know, such as 1002 for a protocol error, and some, like 1006, may never appear on the wire at all. Level 6 has the full list.
No reconnection. Once a socket is closed it is dead; you create a new one. Unlike EventSource, a WebSocket never retries on its own, so every serious client contains a reconnect loop. Level 4 shows how to write one that won't take your servers down.
An HTTP request that stops being HTTP
How does one HTTP request turn into a two-way channel? Through a mechanism HTTP/1.1 has had since its first specification, RFC 2068 in 1997: the Upgrade header. A client sends a normal request that says, in effect, I'd like to stop speaking HTTP on this connection and speak this other protocol instead.
If the server agrees, it answers 101 Switching Protocols, and from the next byte on, both sides speak the new protocol on the same TCP connection.
Here is the full sequence for Ben's chat client, from a cold start.
- First, an ordinary TCP connection to port 443 (or 80 for plain
ws:). WebSockets don't get their own port. Reusing the web's ports is what lets them through firewalls. - For
wss:, TLS is negotiated exactly as for HTTPS, which costs one more round trip with TLS 1.3. Everything after this point is encrypted, which, as you'll see in level 4, matters for more than privacy. - The browser sends a GET request with
Upgrade: websocket,Connection: Upgrade, a randomSec-WebSocket-KeyandSec-WebSocket-Version: 13. - A server that speaks WebSocket answers 101, echoing the upgrade headers and proving it read the key with
Sec-WebSocket-Accept. Any other status, including a redirect, makes the browser fail the connection. - HTTP is over on this connection. The next byte either side sends is the first byte of a WebSocket frame. The
openevent fires, and Ben's client sends its first message.
GET /rooms/42 HTTP/1.1
Host: chat.example
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: https://app.chat.example
Sec-WebSocket-Protocol: chat.v1
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
Cookie: session=7f3a9cHTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat.v1
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits=15| Header | What it does |
|---|---|
Upgrade: websocketConnection: Upgrade | The standard HTTP/1.1 upgrade request. Connection marks Upgrade as a hop-by-hop header meant for the next hop only, a detail that matters for proxies. |
Sec-WebSocket-Key | 16 random bytes, base64 encoded. A fresh nonce for every handshake. Not a secret and not an authentication token. |
Sec-WebSocket-Version: 13 | The protocol version from RFC 6455. If the server speaks another version, it answers 426 Upgrade Required and lists what it supports. |
Origin | The site whose script opened the socket. The server must check it, as the warning below explains. |
Sec-WebSocket-Protocol | Subprotocols the client offers, in order of preference. The server picks one, or none. |
Sec-WebSocket-Extensions | Extensions the client supports, with parameters. In practice this means permessage-deflate compression. |
Sec-WebSocket-Accept | Proof that the server understood this specific handshake, computed from the key. You'll compute it yourself in a moment. |
The key and the accept
The server has to prove it actually processed the handshake. RFC 6455 section 1.3 defines the proof: take the key exactly as it appeared in the header, append the fixed string 258EAFA5-E914-47DA-95CA-C5AB0DC85B11, hash the result with SHA-1, and base64 encode the 20-byte digest. That fixed string is a GUID, picked because no software that isn't a WebSocket server would ever produce it by accident.
The calculator below does that, live, in your browser, with the Web Crypto API. It starts with the example key from the RFC, which decodes to the ASCII text the sample nonce
.
1. What the key is: 16 random bytes, base64 encoded
2. The server appends the fixed GUID to the key text, unchanged
258EAFA5-E914-47DA-95CA-C5AB0DC85B11
3. SHA-1 of those ASCII bytes: 20 bytes
4. Base64 of the digest goes back as
Sec-WebSocket-Accept
Why SHA-1, which is broken for collision resistance? Because nothing here needs a secure hash. The accept value isn't a signature and protects nothing secret; anyone can compute it, as you just did. Its job is to make sure the answer came from a server that understood the WebSocket handshake, and not from a confused HTTP server, or a cache returning an old 101 response for a different key. Any hash would do; SHA-1 was simply everywhere in 2011.
The Sec- prefix on the header names is the other half of the design. Browsers treat any header starting with Sec- as a Header names that fetch() and XMLHttpRequest refuse to set, so only the browser itself can produce them.: a script calling fetch() or XMLHttpRequest can't set them. So a server that sees Sec-WebSocket-Key knows the request came from a browser's WebSocket implementation (or from a non-browser client), not from a page trying to trick a WebSocket server with a crafted HTTP request.
Agreeing on extras
Two headers negotiate optional behavior, and both follow the same pattern: the client offers, the server picks, and only what the server echoes back is in effect. Sec-WebSocket-Protocol names the application protocol spoken inside the messages, such as graphql-transport-ws or your own chat.v1. If the client offered subprotocols and the server picks one the client didn't offer, the browser fails the connection. Sec-WebSocket-Extensions negotiates changes to the framing itself. The only one in wide use, permessage-deflate, compresses message payloads and gets its own section in the next level.
The handshake is ordinary HTTP until the 101. After it, the same TCP connection carries only WebSocket frames.
Keeping a connection alive for hours
An HTTP request lives for milliseconds. A WebSocket might live for hours, and the infrastructure between Ben's browser and the chat server was mostly designed for the first kind of traffic. This level follows the connection through that infrastructure, down into the kernel's socket buffers, and collects what goes wrong.
Proxies and the upgrade
Upgrade and Connection are hop-by-hop headers: by HTTP's rules, a proxy consumes them and does not pass them on. So a reverse proxy in front of your app silently turns a WebSocket handshake into a plain GET unless you tell it otherwise. In nginx, that means three lines, plus a fourth for the timeout.
location /rooms/ {
proxy_pass http://chat_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 120s;
}Forward proxies, such as the ones companies run, are a bigger problem, because you don't control them. Old ones may not understand Upgrade, may buffer the response, or may cut the connection after a fixed time. This is the practical reason to always use wss:. Inside TLS, a proxy sees an opaque encrypted stream (for an explicit proxy, a CONNECT tunnel) and has nothing to misunderstand. Encryption is the best compatibility layer the web has.
Idle timeouts and heartbeats
Chat rooms go quiet. A connection with no traffic looks exactly like a connection whose other end vanished, and every stateful box on the path eventually reclaims idle entries. AWS Application Load Balancers default to a 60-second idle timeout, and nginx closes a proxied connection if the upstream sends nothing for 60 seconds. NAT devices in home routers and mobile networks keep their own mappings for anywhere from a few minutes to hours, and you can't know which one your users have.
The cure is a heartbeat: send something small more often than the shortest timeout on the path. The protocol has frames for it, ping and pong, which you'll see bit by bit in level 6. Servers usually send a ping every 20 to 30 seconds, and browsers answer pings automatically. But the JavaScript API gives your page no way to send a ping or to notice one arriving. So many apps add their own heartbeat messages, which also solves the second problem: detecting a dead peer.
That second problem is nastier than it sounds. If Ben's laptop drops off the network, no FIN or RST ever reaches the server. TCP only notices when it tries to send something and retransmissions run out, which on Linux takes around 15 minutes with default settings. If nothing is sent, it never notices: TCP keepalive is off by default for most sockets, and when on, the first probe on Linux comes after two hours. Meanwhile the server holds a connection
to nobody. Heartbeats with a deadline turn that into a prompt, clean close.
// Protocol pings and pongs are invisible to page JavaScript: the browser
// answers them on its own. So the server also sends an app-level "hb"
// message every 25 s, and 60 s of silence means the connection is dead.
let silence;
function armWatchdog(ws) {
clearTimeout(silence);
silence = setTimeout(() => ws.close(4000, "heartbeat timeout"), 60_000);
}
ws.addEventListener("open", () => armWatchdog(ws));
ws.addEventListener("message", (event) => {
armWatchdog(ws);
if (event.data === "hb") return; // app-level heartbeat from the server
handle(event.data);
});Backpressure: who is filling which buffer
Suppose Ana pastes a 200 MB file into the chat, and the client sends it in 64 KB chunks as fast as a loop can call send(). Her uplink moves maybe 2 MB per second. Where do the other 198 MB go?
bufferedAmountUnbounded. Grows until memory runs out.Everything to the right of the page is bounded and pushes back. When the server reads slowly, its receive buffer fills, TCP advertises a zero window, Ana's kernel stops sending, its send buffer fills, and the browser's writes stall. The browser keeps accepting send() calls anyway and queues them in its own memory, where they show up as bufferedAmount. The classic API has no drain event and no promise to await, so the only defense is to poll.
const HIGH_WATER = 1 << 20; // 1 MiB queued in the browser
async function sendAll(ws, chunks) {
for (const chunk of chunks) {
while (ws.bufferedAmount > HIGH_WATER) {
await new Promise((r) => setTimeout(r, 50)); // there is no "drain" event
}
ws.send(chunk);
}
}The same problem exists in reverse on the server. A slow client, perhaps a phone on a bad train connection, fills the server's send buffer for that socket. A server that keeps queueing messages for it in user space will grow without bound, so good server libraries let you cap the per-connection queue and drop or disconnect slow consumers. The classic browser API can't do the receiving side of this at all: messages are pulled off the socket and turned into events as fast as they arrive, whether or not your code keeps up.
Many connections, few servers
Each open socket costs a file descriptor, kernel buffers and whatever state your application keeps. With care, a single machine can hold hundreds of thousands of mostly idle connections; the limits you'll hit first are usually the process's file descriptor limit, memory per connection, and, on a reverse proxy, local ports. A proxy talking to one backend address needs one local port per upstream connection, and Linux's default ephemeral range of 32768 to 60999 holds about 28,000 of them.
Load balancing changes character too. With HTTP, a balancer spreads requests; with WebSockets it can only place each connection once, when it opens. Start a new server and it gets no traffic until clients reconnect. Restart an old one and all its clients reconnect at the same moment. That moment is where good intentions go wrong.
Reconnecting without a stampede
A thousand clients are connected to one server. It restarts, which takes four seconds, and can complete about 240 handshakes per second once it's back (TLS and authentication aren't free). Every client sees its close event at the same instant. Pick a reconnect strategy and watch.
Notice that plain exponential backoff did worse than retrying every second. Backing off lowers the number of attempts, but without jitter every client still retries at the same instants. Each wave lands on the server in a single 250 ms slot, swamps it, and most clients fail together and wait twice as long for the next wave. Backoff without jitter keeps clients in lockstep. Jitter is what breaks the lockstep, and it only works together with backoff.
The fix has two parts. Exponential backoff makes each client wait longer after each failure, which lowers the total load. Jitter randomizes each wait so clients that failed together don't retry together. With full jitter
, popularized by an AWS article on the subject, each delay is a uniform random number between zero and the exponential ceiling. Reset the attempt counter once a connection actually opens.
function connect(attempt = 0) {
const ws = new WebSocket(URL);
ws.addEventListener("open", () => (attempt = 0));
ws.addEventListener("close", (event) => {
if (event.code === 1000) return; // we closed on purpose
const ceiling = Math.min(10_000, 500 * 2 ** attempt);
const delay = Math.random() * ceiling; // "full jitter"
setTimeout(() => connect(attempt + 1), delay);
});
return ws;
}Compression: permessage-deflate
Chat messages, JSON and other text compress well. The permessage-deflate extension (RFC 7692) compresses each message's payload with DEFLATE, the algorithm inside gzip, and marks compressed messages by setting the RSV1 bit in the first frame's header. By default both sides keep their compression context across messages (context takeover
), so a JSON key that appeared in the last message costs almost nothing in the next one.
That window costs memory. With zlib's default settings the compressor's state is a few hundred kilobytes per connection, on each side, which adds up quickly across 100,000 connections. The negotiation parameters server_no_context_takeover, client_no_context_takeover and the *_max_window_bits options trade compression ratio for memory. And compression has a security edge: if a single compression context mixes secrets with attacker-influenced data, the size of the compressed output can leak the secret, the trick behind the CRIME and BREACH attacks on HTTPS.
The next generation
Two newer APIs address the classic API's blind spots.
WebSocketStream wraps the same protocol in the Streams API. Reading is pull-based, so a slow consumer makes the browser stop reading from the socket and TCP flow control pushes back on the server. Writes return promises, so the sender is paced too. It's the same wire protocol, so servers don't change. As of late 2026 it has shipped only in Chromium-based browsers, so treat it as a progressive enhancement.
const wss = new WebSocketStream("wss://chat.example/rooms/42");
const { readable, writable } = await wss.opened;
const writer = writable.getWriter();
await writer.write("Hello"); // awaiting each write paces the sender
for await (const message of readable) {
await render(message); // the next read waits for this, so the
} // browser stops reading from the socketWebTransport is a different protocol altogether, built on HTTP/3 and QUIC. One session carries many independent streams, so a lost packet on one stream doesn't stall the others, plus unreliable datagrams for data where late equals useless, such as game state or live media. It needs an HTTP/3-capable server, and its browser support is younger than WebSocket's. Chromium and Firefox have shipped it; Safari support arrived later, so check the current status for the browsers your users run. For chat-shaped problems, WebSockets remain the default.
| WebSocket | WebSocketStream | WebTransport | |
|---|---|---|---|
| Transport | TCP, or a stream in HTTP/2 or HTTP/3 | Same as WebSocket | HTTP/3 over QUIC, with an HTTP/2 fallback in the works |
| Unit | Messages | Messages, through streams | Byte streams and datagrams |
| Backpressure | Manual, via bufferedAmount | Built in, both directions | Built in |
| Head-of-line blocking | Yes | Yes | Only within one stream |
| Unreliable delivery | No | No | Yes, datagrams |
| Server changes | Standard everywhere | None, same protocol | An HTTP/3 server with WebTransport support |
Frames, bit by bit
After the 101, the connection carries frames. Every message Ana and Ben exchange, every ping and every goodbye is one or more frames, and each frame is a small header followed by a payload. The header is two bytes at minimum and fourteen at most. Here is its layout, as RFC 6455 section 5.2 draws it, 32 bits to a row:
- FIN (1 bit): this frame is the last one of its message. Most messages are a single frame with FIN set.
- RSV1, RSV2, RSV3 (1 bit each): reserved for extensions. They must be 0 unless an extension negotiated in the handshake says otherwise;
permessage-deflateuses RSV1 to flag a compressed message. A receiver that sees an unexpected RSV bit must fail the connection. - Opcode (4 bits): what the frame is.
0x1text,0x2binary,0x0continuation of a fragmented message,0x8close,0x9ping,0xApong. Opcodes with the top bit set, 0x8 to 0xF, are control frames. The unlisted values are reserved. - MASK (1 bit): the payload is masked with the 32-bit key that follows. Every frame from a client must set it; no frame from a server may.
- Payload length (7 bits, plus 16 or 64): explained in the table below.
Now build frames yourself. The starting point is the example from RFC 6455 section 5.7: a masked text frame containing Hello
, with the RFC's own masking key. Change the text, flip FIN, switch the opcode, or push the length past 125 and 65,535 bytes to watch the length encoding change.
Header, bit by bit
The whole frame, byte by byte
Masking, one byte at a time
Payload byte i is XORed with key byte i mod 4. Doing it again with the same key gives the original back.
| i | Original | Key byte | On the wire |
|---|
Three sizes of length
Most messages are small, so the format optimizes for them. Lengths up to 125 fit in the 7-bit field directly. The values 126 and 127 are escape codes: 126 means the real length follows as a 16-bit unsigned integer, 127 means it follows as a 64-bit one. Both are in network byte order, which means big-endian, and the most significant bit of the 64-bit form must be 0. A sender must always use the shortest form that fits, so each length has exactly one valid encoding.
| Payload | 7-bit field | Extended length | Header, unmasked | Header, masked |
|---|---|---|---|---|
| 0 to 125 bytes | The length itself | None | 2 bytes | 6 bytes |
| 126 to 65,535 bytes | 126 (0x7E) | 16 bits | 4 bytes | 8 bytes |
| 65,536 bytes and up | 127 (0x7F) | 64 bits | 10 bytes | 14 bytes |
Two more examples from the same section of the RFC, both unmasked binary frames as a server would send them. The first byte, 0x82, is FIN plus opcode 2.
- FIN + binary1000 0010
- No mask, length escape 126
- 16-bit length256
- Payload256 bytes follow; the first two shown
- FIN + binary
- No mask, length escape 127
- 64-bit length65,536
Text frames have one more rule: the complete message must be valid UTF-8, and a receiver that finds invalid UTF-8 closes the connection with code 1007. Binary frames carry anything. The opcode is the only thing that tells a receiver which is which, and it's what the browser uses to decide whether event.data becomes a string or binary data.
Fragments, pings and goodbyes
A message is not always one frame. A sender may split a message into fragments, and it may slip control frames between those fragments. This is how the protocol stays responsive while a large message is in flight, and how it says goodbye.
Fragmentation
The first fragment carries the message's real opcode, text or binary, with FIN set to 0. Any middle fragments use opcode 0x0, continuation, also with FIN 0. The last fragment is a continuation with FIN 1. The receiver concatenates the payloads and delivers one message.
Why bother? Two reasons. A sender that doesn't know a message's length in advance, such as one streaming generated output, can send it in pieces without buffering it all. And a sender in the middle of a 100 MB message can still answer a ping within milliseconds, because control frames may be interleaved between fragments. Fragments of two different data messages, however, may never interleave.
Below, the server sends Ben Hello, world
in three fragments, with a ping in the middle.
01 03text, FIN 0"Hel"89 04ping, FIN 1"t=42"00 04continuation, FIN 0"lo, "80 05continuation, FIN 1"world""Hel""Hel" (untouched)"Hello, "message event: "Hello, world"0x01is FIN 0 with opcode 1: a text message begins, and more is coming.0x03is the length. The browser buffersHel
and delivers nothing yet.- A ping arrives mid-message. Control frames are handled immediately: the browser sends back a pong with the same
t=42
payload, masked because it comes from the client. The buffer is untouched. - A continuation frame,
0x00: opcode 0, FIN still 0. Its payload is appended. 0x80is FIN 1 with opcode 0: the final fragment. The message is complete and yourmessagehandler seesHello, world
as a single string. The fragmentation was invisible.
Control frames
The three defined control frames, opcodes 0x8 to 0xA, obey three rules that make them cheap to handle anywhere, even mid-message: their payload is at most 125 bytes, so the length always fits in 7 bits; they can't be fragmented, so FIN is always 1; and they can appear between the fragments of a data message.
Ping (0x9) asks are you there?
, and the receiver must answer with a pong (0xA) carrying exactly the same payload, as soon as practical. If several pings arrive before it can answer, it may answer only the latest. An unsolicited pong is also allowed and needs no reply, which makes it a one-way heartbeat. These are the frames behind the heartbeats of level 4. Browsers answer pings for you and never show them to your code.
The closing handshake
TCP has its own way to close a connection, so why does WebSocket need another? Because a TCP close can't say why, and because closing TCP while data is still in flight can lose that data. A WebSocket close is a polite, two-step exchange on top.
- Ben's page calls
ws.close(1000). The browser sends a close frame:0x88is FIN plus opcode 8, the payload is the 2-byte status code 1000 (03 E8) plus an optional UTF-8 reason. The socket is now CLOSING, and the browser sends no more data frames. - The server answers with its own close frame, usually echoing the code. Once each side has sent and received a close frame, the WebSocket is closed and no further frames are allowed.
- The server closes the TCP connection first. The RFC asks for this so the server, not the client, ends up holding the TCP TIME_WAIT state. Your
closeevent fires withwasClean: true.
The close payload is either empty or a 2-byte, big-endian status code followed by an optional UTF-8 reason. With the 125-byte control frame limit, that leaves at most 123 bytes for the reason. These are the codes you'll meet:
| Code | Name | Meaning |
|---|---|---|
1000 | Normal closure | The purpose is fulfilled. What your code should send for an ordinary close. |
1001 | Going away | A server shutting down, or a browser navigating away from the page. |
1002 | Protocol error | The peer broke the framing rules: an unmasked client frame, a reserved opcode, an unexpected RSV bit. |
1003 | Unsupported data | For example, binary data sent to an endpoint that only accepts text. |
1005 | No status received | Reserved, never sent. What your close event reports when the close frame had no code. |
1006 | Abnormal closure | Reserved, never sent. The connection dropped without a close frame. |
1007 | Invalid payload data | Typically invalid UTF-8 in a text message. |
1008 | Policy violation | A generic you broke our rules, when nothing more specific fits. |
1009 | Message too big | Larger than the receiver is willing to process. |
1010 | Mandatory extension | Sent by a client whose required extension the server didn't negotiate. |
1011 | Internal error | The endpoint hit an unexpected condition. Originally worded for servers only; RFC 6455 erratum 3227 extends it to clients. |
1012 to 1014 | Service restart, try again later, bad gateway | Registered with IANA after RFC 6455. Useful hints for a client's reconnect logic. |
1015 | TLS handshake failure | Reserved, never sent. |
3000 to 3999 | Registered | For libraries and frameworks, registered with IANA. |
4000 to 4999 | Private use | Yours. Agree on their meaning between your client and server. |
Why clients scramble their bytes
You have seen the MASK bit in every client frame: a fresh 32-bit key, and every payload byte XORed with one key byte. It looks like encryption, but the key travels in the clear right in front of the data, so anyone on the path can undo it. It's not about privacy, and it's not about integrity. It exists because of a specific attack on infrastructure that you don't control.
Talking to yourself for fun and profit
In 2010, while the protocol was still a draft, Lin-Shung Huang, Eric Chen, Adam Barth, Eric Rescorla and Collin Jackson studied what happens when a web page can put chosen bytes on a socket that passes through network middleboxes. Their paper, Talking to Yourself for Fun and Profit (W2SP 2011), showed that the early WebSocket handshake, and the socket APIs of Flash and Java at the time, could be used to poison the caches of A proxy the client doesn't know about: it sits on the network path, often in an ISP or a company network, intercepts port 80 traffic and serves cached responses..
The trick is a disagreement between two parsers. The attacker's page talks to the attacker's own server, which is allowed. But a transparent proxy on the path doesn't understand the upgrade and keeps parsing the connection as HTTP. If the page can write bytes that look like an HTTP request, the proxy believes them.
- The victim's network sends all web traffic through a transparent proxy: one the browser does not know about, sitting on the path and caching responses. The victim opens a page with an ad from
attacker.example. - The ad's script opens a socket back to
attacker.example, which is allowed: it is the script's own origin. The proxy does not understand theUpgradeheader, forwards the request anyway, and the attacker's server answers as if it agreed. - Now the script writes bytes into the socket. Without masking, they go out exactly as written, and the attacker writes
GET /lib.js HTTP/1.1andHost: cdn.example. To the proxy, still parsing HTTP, this looks like a fresh request on a kept-alive connection. - The proxy routes by the connection's destination IP address, which is the attacker's server. That server replies with a malicious
lib.js. - The proxy files the response under the
Hostheader it parsed:cdn.example/lib.js. The cache is now poisoned. - Every other user behind the proxy who loads
cdn.example/lib.jsgets the attacker's script from the cache. The realcdn.examplewas never involved. Masking breaks step 3: the script no longer controls the bytes on the wire.
The authors measured this in the wild with a real ad campaign and found proxies that were vulnerable. The fix they proposed became the masking in RFC 6455 section 5.3. Every frame a client sends is masked with a new key that the browser picks from a strong source of randomness, and the page's script never learns that key before the bytes are sent. The script still chooses the payload, but it can't predict what the payload looks like on the wire, so it can't make those bytes spell GET /lib.js HTTP/1.1.
Try it: type an attack payload and see what a proxy would read, with and without masking.
\r\n stands for the two bytes 0D 0A, the line ending HTTP expects.
Unmasked, as early drafts sent it
Masked, as RFC 6455 requires
Why only clients mask
The attacker in this story is a script running in a victim's browser, writing bytes into the request direction where proxies parse requests. A server is not in that position: its bytes flow in the response direction, and a server that wants to send poison can do so with plain HTTP responses already. So the RFC requires masking only from client to server, and in fact forbids servers from masking. A server must close the connection, usually with 1002, if a client frame arrives unmasked, and a client must do the same if a server frame arrives masked.
Masking costs almost nothing. XOR is the cheapest operation a CPU has, and implementations apply the key four or eight bytes at a time, or with SIMD instructions across 16 or 32 bytes at once, by repeating the 4-byte key to fill a wider register. The payload's position in the frame doesn't matter because the key index is just the byte offset modulo 4.
Masking keeps a web page from choosing the exact bytes that appear on the wire, so it can't impersonate HTTP to a confused proxy.
Frames on a byte stream
One layer left. Frames don't travel on their own: they are bytes written into a TCP connection, and TCP is a byte stream. It delivers every byte, in order, exactly once, and it promises nothing about how they are grouped.
When Ana's browser writes an 11-byte frame, TCP may send it in one segment, or combine it with the next frame, or (with a larger frame) split it across several segments sized by the path's MTU. With wss:, TLS adds its own grouping: the bytes are packed into encrypted records of up to 16 KB, which are again cut into TCP segments. And on the receiving side, each read() or recv() call returns whatever happens to be in the kernel's buffer at that moment, which may be half a header or three frames and a bit.
So the frame boundaries you designed and the chunk boundaries your parser sees are unrelated. A WebSocket parser is a state machine that must accept the stream in pieces of any size, including one byte at a time, and produce exactly the same frames.
Parser state
- Header2 bytes
- Length 162 bytes, if len = 126
- Length 648 bytes, if len = 127
- Mask key4 bytes, if MASK = 1
- Payloadlen bytes
What the parser hands up
Step through the cuts inside headers and watch what the parser does with a read that ends after the first byte of a header. It can't decide anything yet: it doesn't know the opcode's length rules, whether a mask follows, or how long the payload is. So it keeps the partial header, returns, and waits. That's the core loop of every WebSocket implementation, sketched below.
function onBytes(chunk) {
buffer.append(chunk);
while (true) {
if (buffer.length < 2) return; // need the 2-byte header
const len7 = buffer[1] & 0x7f;
const extra = len7 === 126 ? 2 : len7 === 127 ? 8 : 0;
const maskLen = buffer[1] & 0x80 ? 4 : 0;
const headerLen = 2 + extra + maskLen;
if (buffer.length < headerLen) return; // header split across reads
const len = readLength(buffer, len7, extra);
if (len > MAX_FRAME) return fail(1009); // check before buffering
if (buffer.length < headerLen + len) return; // payload still arriving
handleFrame(buffer.take(headerLen + len));
}
}The highlighted lines are where parsers get attacked. A sender can claim a payload length of 263 − 1 bytes in ten bytes of header, and a naive parser that allocates a buffer of that size, or keeps reading until it has the whole thing, falls over. Every production implementation enforces a maximum frame size and a maximum message size (fragments add up, too), and closes with 1009 when they're exceeded. The parser must check the limit as soon as it knows the length, before buffering the payload.
The other direction has the same issue in mirror image: writes. A write() to a TCP socket may accept only part of a frame when the send buffer is nearly full. The sender's code must keep the rest and write it when the socket becomes writable again, without letting another frame's bytes cut in. Interleave two half-written frames and the receiver's parser sees garbage, which is why WebSocket libraries serialize all writes to one connection through a single queue.
That is the whole stack. Ana's Hello
became a send() call, a masked 11-byte frame, a TLS record, a TCP segment or two, and on the far side a parser that reassembled the frame from whatever pieces arrived, unmasked it, and handed the server five bytes of UTF-8. The server wrapped them in a new, unmasked frame, 81 05 48 65 6C 6C 6F, and pushed it down Ben's long-lived connection, where his browser parsed it in the same way and fired a message event. All of it in roughly one round trip's worth of network time after Ana pressed Enter.
TCP delivers bytes, not frames. A WebSocket parser is a state machine that rebuilds frames from chunks of any size.
End of WebSockets · 8 levels, Idea to Machine
Where to next
Next in Web and networking · 08 of 12
WebRTC, from Join call to the wire
Ana is behind her home router. Ben is behind a carrier NAT. Follow their video call through negotiation, hole punching, encryption and the packets that arrive just in time.
Practical notes
SSE vs WebSockets vs long polling
Use SSE for server-to-page text updates, WebSockets for bidirectional streams, and long polling when ordinary request handling is the simplest fit.