Foundations · Lesson 09

WebSockets & real-time

Plain HTTP is one-sided: the client asks, the server answers, done. But chat, live scores, and collaborative editing need the server to speak first — to push data the moment it changes. WebSockets keep a single connection open in both directions so it can.

The problem: the server can't start the conversation

In normal HTTP the client always speaks first. So how does a chat app show a message the instant a friend sends it? The naive answer is polling: ask "anything new?" every couple of seconds. It works, but it's wasteful — most requests come back empty, and there's still up-to-2-second lag. Picture phoning the post office every 30 seconds to ask if mail arrived, versus them ringing you when it does.

How a WebSocket starts: the upgrade

A WebSocket begins life as an ordinary HTTP request carrying a special header — Upgrade: websocket. If the server agrees, it replies 101 Switching Protocols and from that point the same TCP connection (Lesson 04) stops speaking HTTP and starts speaking the WebSocket protocol: a long-lived, two-way channel where either side can send a message at any time, with very little per-message overhead.

# client asks to upgrade an existing HTTP connection
GET /chat HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade

# server agrees — the pipe is now bidirectional
HTTP/1.1 101 Switching Protocols
Upgrade: websocket

Because it reuses the HTTP port (443) and handshake, it sails through firewalls and proxies that already allow web traffic — a big reason it won over older hacks.

Three tools, increasing power

The instinct: don't reach for WebSockets if you only need server→client updates — SSE is simpler and rides plain HTTP. Use WebSockets when the client must also send frequently and instantly (typing, game moves, cursor positions).

Under the hood: how it actually works

The Upgrade handshake — exact bytes

A WebSocket starts as a perfectly ordinary HTTP/1.1 request. The client sends four special headers; the server's 101 response is the signal that the TCP connection has been handed off from HTTP to the WebSocket protocol.

## Client → Server (the HTTP Upgrade request)
GET /chat HTTP/1.1\r\n
Host: api.example.com\r\n
Upgrade: websocket\r\n
Connection: Upgrade\r\n
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n
Sec-WebSocket-Version: 13\r\n
\r\n

## Server → Client (101 = "I'm switching protocols")
HTTP/1.1 101 Switching Protocols\r\n
Upgrade: websocket\r\n
Connection: Upgrade\r\n
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=\r\n
\r\n
# After this blank line: no more HTTP — pure WebSocket frames both ways

The Sec-WebSocket-Accept value is not a secret — it is derived from the client's key using a fixed GUID. The server concatenates the key with the magic GUID "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", takes SHA-1 of the result, then Base64-encodes it:

# How Sec-WebSocket-Accept is computed (pseudocode)
key     = "dGhlIHNhbXBsZSBub25jZQ=="          # from client header
magic   = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
accept  = base64( sha1( key + magic ) )
# = "s3pPLMBiTxaQ9kYGzzhZRbK+xOo="

# Verify it yourself:
$ echo -n "dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11" \
  | openssl sha1 -binary | base64
s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

The client validates this value before trusting the upgrade. The purpose is to prove the server intended a WebSocket upgrade (not a misrouted HTTP cache response accidentally being reused as a WebSocket).

The WebSocket frame format

After the handshake, data is exchanged as frames — binary structures with a compact 2–14 byte header:

## WebSocket frame layout (RFC 6455 §5.2)
 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|             |                               |
| |1|2|3|       |K|             |                               |
+-+-+-+-+-------+-+-------------+-------------------------------+
|                  Masking-key (if MASK=1, 32 bits)             |
+---------------------------------------------------------------+
|                        Payload data                           |
+---------------------------------------------------------------+

## Key fields:
FIN (1 bit)   — 1 = this is the final fragment of the message
opcode (4 bits):
  0x0 = continuation frame
  0x1 = text frame (UTF-8)
  0x2 = binary frame
  0x8 = close frame (+ 2-byte close code + optional UTF-8 reason)
  0x9 = ping frame
  0xA = pong frame
MASK (1 bit)  — 1 = payload is XOR-masked (clients MUST mask; servers MUST NOT)
Payload len  — 0–125: actual length; 126: next 2 bytes = length; 127: next 8 bytes

The masking requirement is security-related: browsers must mask frames they send so a malicious page can't craft a WebSocket message that looks like an HTTP request to a proxy — a cache-poisoning attack. Server-sent frames are never masked.

Ping / pong and the close handshake

Either side can send a ping (opcode 0x9); the receiver must immediately reply with a pong (opcode 0xA) echoing the payload. This detects dead connections: if pings go unanswered, the side that sent them closes the connection. Servers typically send a ping every 30–60 seconds.

To close a connection cleanly, either side sends a close frame (opcode 0x8) with a 2-byte close code. The other side must reply with its own close frame, then both sides close the TCP connection. This two-step ensures both sides know the session ended intentionally.

How to debug & inspect it

Two tools cover most WebSocket debugging: wscat (a CLI client) and Chrome DevTools (captures every frame in the browser).

In Chrome DevTools: open Network → filter by WS → click the connection row → open the Messages tab. You see each frame with direction (↑ = sent, ↓ = received), timestamp, length, and payload. The Headers tab shows the upgrade request/response including Sec-WebSocket-Key and Sec-WebSocket-Accept.

Debug checklist:

1. Does wscat -c URL connect? If not, the issue is at the HTTP upgrade layer — check the HTTP status code it prints.
2. In DevTools → Network → WS → Headers: confirm 101 Switching Protocols and that Sec-WebSocket-Accept is present.
3. In DevTools → Messages: do you see sent/received frames? If the connection opens but no messages arrive, the issue is application-level (routing, room assignment).
4. Check close frame codes when a connection drops unexpectedly — 1006 (TCP drop) vs 1000 (clean close) tells you whether it was a network problem or intentional.
5. Add server-side ping/pong (e.g. every 30s) to detect half-open connections — a client that disconnected without a close frame won't be noticed otherwise.

Sources & further reading

• MDN — WebSockets API · RFC 6455 — The WebSocket Protocol
• MDN — Server-Sent Events
• RFC 6455 §5.5 — Control frames (ping, pong, close)
• IANA — WebSocket Close Codes registry