The WebSocket JavaScript API

Technical Deep Dive & Specifications

The WebSocket Constructor

The standard browser constructor is defined in the WHATWG HTML / W3C WebSocket API specification:

const socket = new WebSocket(url: string, protocols?: string | string[]);

Parameters:

1. url (string, required): The target WebSocket endpoint. Must use either the ws:// (insecure, port 80) or wss:// (TLS encrypted, port 443) protocol scheme. Relative URLs are supported in modern browsers (e.g., new WebSocket('/api/feed') resolves to wss://current-origin/api/feed).
2. protocols (string | string[], optional): A subprotocol name or array of subprotocol strings (e.g., ['graphql-transport-ws', 'wamp.2.json']).

Subprotocol Negotiation (Sec-WebSocket-Protocol)

When multiple clients connect to a server, they may support different application protocols (e.g., GraphQL subscriptions, STOMP, or JSON-RPC 2.0).

Browser (Client)                                          Server
       |                                                     |
       |  GET /ws HTTP/1.1                                   |
       |  Sec-WebSocket-Protocol: graphql-ws, wamp.2.json   |
       |---------------------------------------------------->|
       |                                                     |
       |  HTTP/1.1 101 Switching Protocols                  |
       |  Sec-WebSocket-Protocol: graphql-ws                 |
       |<----------------------------------------------------|
       |                                                     |
  socket.protocol === "graphql-ws"

If the server accepts one of the requested subprotocols, it includes the selected string in its handshake response. After the socket opens, the active protocol is exposed on the read-only property socket.protocol.

Instance Properties Matrix

The Four Core Lifecycle Events

const socket = new WebSocket('wss://echo.websocket.events');

// 1. Connection established
socket.addEventListener('open', (event) => {
  console.log('Socket connection established:', event);
  socket.send(JSON.stringify({ type: 'GREETING', payload: 'Hello Server!' }));
});

// 2. Incoming message received
socket.addEventListener('message', (event) => {
  console.log('Received payload from server:', event.data);
});

// 3. Connection error
socket.addEventListener('error', (event) => {
  console.error('WebSocket encountered an error:', event);
});

// 4. Connection closed
socket.addEventListener('close', (event) => {
  console.log(`Socket closed with Code: ${event.code}, Reason: "${event.reason}", Clean: ${event.wasClean}`);
});

Event Object Details:

• open (Event): Fires when readyState transitions from 0 (CONNECTING) to 1 (OPEN). It indicates the handshake succeeded and messages can safely be dispatched.
• message (MessageEvent):
  • event.data: Contains the message payload (string, Blob, or ArrayBuffer).
  • event.origin: The origin of the server (wss://example.com).
• error (Event): Triggered when a transport error occurs (e.g., DNS resolution failure, TLS certificate error, or abnormal TCP drop).

  Security Note: The browser's error event deliberately omits specific network error details to prevent cross-origin port-scanning and network reconnaissance attacks.

• close (CloseEvent):
  • event.code: The RFC 6455 16-bit status code.
  • event.reason: A human-readable UTF-8 string explanation (up to 123 bytes) supplied by either client or server.
  • event.wasClean: A boolean indicating whether the TCP connection closed via a proper RFC 6455 close handshake (true) or was dropped abruptly (false).

Standard RFC 6455 Close Status Codes

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 84–97 (connectBtn.addEventListener): Instantiates new WebSocket(url) within a try/catch block to handle malformed URL strings.
• Lines 89–92 (open): Binds an event listener to open, updates the UI state badge to OPEN (1), and logs the negotiated subprotocol via socket.protocol.
• Lines 94–96 (message): Listens to incoming text messages and displays event.data.
• Lines 98–101 (error): Captures connection failures.
• Lines 103–106 (close): Inspects event.code, event.reason, and event.wasClean when the TCP socket terminates.
• Lines 111–116 (disconnectBtn.addEventListener): Calls socket.close(1000, "Client initiated closure") to initiate a clean RFC 6455 close handshake.

Expected Browser Render Output

WebSocket Lifecycle Monitor [OPEN (1)]
[ wss://echo.websocket.events        ] [Connect] [Disconnect]
[ Hello, WebSocket Server!           ] [Send Message]

Event Stream Log
[14:20:01.120] [INFO] Attempting connection to wss://echo.websocket.events...
[14:20:01.340] [OPEN] Connected successfully! Protocol: "none"
[14:20:05.812] [INFO] Dispatched frame: "Hello, WebSocket Server!"
[14:20:05.990] [MESSAGE] Data received: Hello, WebSocket Server!
[14:20:10.100] [INFO] Executing manual socket.close(1000, "Client initiated closure")...
[14:20:10.220] [CLOSE] Connection closed. Code: 1000, Reason: "Client initiated closure", WasClean: true