WebSockets Quick Reference
This reference distills the WebSocket protocol and browser API down to the pieces you reach for most often: the constructor and its readyState values, the four events every socket emits, the handshake headers that make the upgrade happen, and the close codes worth recognizing at a glance. Keep it nearby when writing or reviewing WebSocket code so you're not re-deriving these details from scratch each time.
Cricket analogy: A quick reference is like a fielding position chart taped inside a captain's cap — you don't relearn where cover point stands every over, you glance and act, exactly how you'd glance at readyState values instead of re-deriving them.
The Browser WebSocket API
The WebSocket constructor takes a URL (ws:// or wss://) and an optional array of subprotocols, and exposes a readyState property with four numeric values: 0 (CONNECTING), 1 (OPEN), 2 (CLOSING), and 3 (CLOSED). Four events cover the entire lifecycle — open when the handshake completes, message for every incoming frame, error when something goes wrong (with minimal detail by design), and close with a code and reason explaining why the connection ended — and send() accepts strings, Blob, ArrayBuffer, or typed array views.
Cricket analogy: The four readyState values are like a match's status states: 'toss pending' (connecting), 'play in progress' (open), 'innings break called' (closing), and 'match ended' (closed) — a scorer app checks this state before deciding whether to log a ball.
Handshake Headers
// Client request
GET /chat HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: https://app.example.com
// Server response
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=Close Codes Cheat Sheet
1000 Normal Closure - clean, expected close
1001 Going Away - page navigation, server shutdown
1002 Protocol Error - endpoint received a malformed frame
1003 Unsupported Data - received data type it can't accept
1006 Abnormal Closure - no close frame received (network/proxy/crash)
1008 Policy Violation - generic rejection, e.g. failed auth
1009 Message Too Big - frame exceeded server's size limit
1011 Internal Error - server hit an unexpected error
1015 TLS Handshake Failure - reserved, not settable by application codereadyState 0-3 map directly to XMLHttpRequest-style numeric constants for consistency with older browser APIs, but you should still use the named constants (WebSocket.OPEN, WebSocket.CLOSED, etc.) in code for readability rather than hardcoding the numbers.
Calling send() while readyState is not OPEN (i.e. still CONNECTING) throws an InvalidStateError. Always guard sends with a readyState check or queue messages until the open event fires.
- readyState values: 0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED — check before calling send().
- Four lifecycle events: open, message, error, close — close carries a code and reason, error carries almost nothing.
- Handshake requires Upgrade, Connection, Sec-WebSocket-Key/Version headers from the client and a computed Sec-WebSocket-Accept from the server.
- send() accepts strings, Blob, ArrayBuffer, and typed array views for binary data.
- Close code 1000 is normal, 1006 is abnormal (no close frame), 1008 is policy violation (e.g. auth failure), 1011 is server internal error.
- Use ws:// for plain connections and wss:// for TLS-secured connections, analogous to http:// and https://.
- Subprotocols can be negotiated via the constructor's second argument and confirmed in the server's Sec-WebSocket-Protocol response header.
Practice what you learned
1. What numeric readyState value corresponds to OPEN?
2. Which event fires for every incoming WebSocket frame?
3. What happens if you call send() while readyState is CONNECTING?
4. What data types can be passed to WebSocket.send()?
5. What is the difference between ws:// and wss://?
Was this page helpful?
You May Also Like
WebSockets vs WebRTC
A practical comparison of WebSockets and WebRTC, covering their transport models, connection setup, and when to reach for each in a real-time application.
Debugging WebSocket Connections
Practical techniques for diagnosing failed handshakes, dropped connections, and mysterious silent disconnects in WebSocket-based applications.
WebSockets Interview Questions
Common WebSockets interview questions with clear, technically grounded answers covering the protocol, scaling, security, and comparisons to alternatives.
Building a Real-Time Chat App
A hands-on walkthrough of designing a WebSocket-based chat application, from connection lifecycle and message schema to rooms, presence, and delivery guarantees.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics