WebSocket Architecture | The Garnet Wiki

WebSocket Architecture is the foundation for real-time, bidirectional communication between clients and servers. It matters when data must flow continuously—live dashboards, collaborative editing, chat applications, IoT telemetry, and financial trading systems—where HTTP’s request-response model becomes a bottleneck. Unlike polling or long-polling, WebSocket provides a persistent, full-duplex channel over a single TCP connection, reducing latency, overhead, and complexity.

Establishing a WebSocket Connection

A WebSocket connection begins with an HTTP Upgrade handshake. The client sends an HTTP GET request to a WebSocket endpoint, including the Upgrade header and Connection token. The server responds with a 101 Switching Protocols status code, and the connection transitions from HTTP to WebSocket.

GET /ws/chat HTTP/1.1
Host: chat.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: https://chat.example.com

The server responds:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Version: 13

The Sec-WebSocket-Key is a base64-encoded random value. The server computes the Sec-WebSocket-Accept by concatenating the key with the GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11, hashing it with SHA-1, and base64-encoding the result. This handshake is standardized in RFC 6455 and is used across all WebSocket implementations.

Clients must handle the handshake failure. A 101 response with a missing Sec-WebSocket-Accept or mismatched Sec-WebSocket-Version leads to a WebSocket Error 1002 (protocol error). Clients should retry with a fallback version if the server does not support 13.

Data Transfer and Frame Format

Once the connection is established, data flows as frames. Each frame consists of a header and payload. The header is at least 2 bytes, with an optional 2–14 bytes extension. The first byte contains the FIN bit (final frame), opcode (control or data), and masking flag. The second byte includes the length (7 bits), with extended lengths encoded in the next bytes.

Common opcodes:

0x1: Text frame (UTF-8 encoded)
0x2: Binary frame
0x8: Close frame
0x9: Ping frame
0xA: Pong frame

A client sending a message to a server might send:

{
  "type": "message",
  "user": "alice",
  "text": "Hello, world!",
  "timestamp": 1710203456
}

Serialized as a text frame with opcode 0x1, length 87, and a mask. The server replies with a binary frame (0x2) containing a serialized protobuf or a JSON array.

Clients must handle fragmented messages. A frame with FIN = 0 indicates the message is split across multiple frames. The first frame has FIN = 0, and subsequent frames have Opcode = 0x0 (continuation). The receiver must accumulate all fragments until FIN = 1 is received.

A common failure occurs when a server sends a large message with FIN = 1 but does not set the Opcode correctly. A client expecting a text frame may misinterpret a binary frame as a continuation, leading to corrupted messages.

Managing Connection Lifecycle

WebSocket connections are not eternal. Clients and servers must manage connection state, particularly during network instability.

The server sends periodic Ping frames (0x9) to keep the connection alive. The client responds with a Pong (0xA). If the client does not respond within a timeout (typically 30 seconds), the server closes the connection with Code 1006 (connection closed abnormally) and optionally includes a Reason string.

Clients should implement a reconnection strategy. When a connection drops, they:

Wait 1–5 seconds before reconnecting.
Use exponential backoff (1s, 2s, 4s, 8s, …).
Send a WebSocket Close frame (0x8) with a Code and optional Reason.

Close codes:

1000: Normal closure
1001: Going away
1002: Protocol error
1003: Unsupported data
1006: No status received
1011: Internal server error

A common mistake is sending a Close frame with Code = 1000 but omitting the Reason field. The receiving client may not distinguish between a clean shutdown and a network issue.

Clients should also handle the Close frame from the server. Upon receiving a Close frame, they:

Parse the Code and Reason.
Wait for the Ping timeout to confirm the connection is closed.
Reconnect with the same session ID if the client supports session persistence.

Message Handling and Routing

Clients send and receive messages in a structured format. The most common is JSON, but binary formats (Protocol Buffers, MessagePack) are used for high-throughput scenarios.

A typical message has a type, id, and payload. The type field determines how the server routes the message.

{
  "type": "subscribe",
  "channel": "stock:NASDAQ:AAPL",
  "id": "sub-123"
}

The server responds with:

{
  "type": "subscribed",
  "channel": "stock:NASDAQ:AAPL",
  "id": "sub-123",
  "timestamp": 1710203456
}

For real-time updates, the server sends data messages:

{
  "type": "data",
  "channel": "stock:NASDAQ:AAPL",
  "data": {
    "price": 172.45,
    "volume": 341200,
    "timestamp": 1710203457
  }
}

Clients must handle message ordering and deduplication. The id field allows the client to track which messages have been processed. The server can send ack messages to confirm receipt.

A critical failure mode arises when a client subscribes to multiple channels but receives messages in different orders. The server must send messages with consistent timestamp fields and use id to correlate events. A client that assumes in-order delivery without id or timestamp may merge updates incorrectly.

Server-Side Architecture Patterns

A scalable WebSocket server must handle thousands of concurrent connections. Common patterns include:

Single process with async I/O: A single server process uses epoll (Linux), kqueue (BSD), or IOCP (Windows) to multiplex connections. Libraries like libuv, Netty, and Tokio provide the underlying event loop.

Worker processes: The server uses a load balancer (e.g., HAProxy, Nginx) to distribute connections across multiple worker processes. Each worker runs an event loop and maintains its own set of active connections.

Message queue integration: For pub/sub systems, the server connects to a message broker (e.g., RabbitMQ, Apache Kafka) to route messages between clients and services.

Example: A chat server uses Nginx as a reverse proxy with WebSocket support.

upstream chat_servers {
    server 10.0.1.10:8080;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
}

server {
    listen 443 ssl;
    server_name chat.example.com;

    location /ws/chat {
        proxy_pass http://chat_servers;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-WebSocket-Session $remote_addr;
        proxy_set_header X-WebSocket-User $http_user_id;

        # Keep-alive for WebSocket
        proxy_cache_bypass $http_upgrade;
        proxy_buffering off;
        proxy_cache_key "$remote_addr:$proxy_port";
    }
}

The X-WebSocket-Session and X-WebSocket-User headers allow the server to correlate messages across workers.

A common failure occurs when the load balancer does not preserve the WebSocket connection. If proxy_set_header Connection "upgrade"; is missing, the server may receive a Connection: keep-alive header but the connection is not upgraded. The client receives a 101 Switching Protocols response but the server still uses HTTP for the connection, leading to frequent round trips and latency spikes.

Error Handling and Debugging

WebSocket errors are signaled through the Close frame and error codes. The server can send Close frames with Code and Reason to diagnose issues.

Common error codes:

1000: Normal closure
1001: Server shutting down
1002: Protocol error (e.g., invalid JSON)
1003: Unsupported data (e.g., unknown message type)
1006: No status received (connection dropped without close frame)
1011: Internal server error (e.g., database timeout)

Clients should log the Reason string and Code to aid debugging.

A silent failure occurs when a client sends a Ping frame but the server does not respond with Pong. The client may detect the failure after 30 seconds but has no visibility into the cause. The server should log Ping timeouts and track which clients are unresponsive.

When a client reconnects, it should send a Reconnect message with the last id and timestamp it processed. The server can resume sending updates from that point.

Scaling and Fault Tolerance

For high availability, WebSocket servers must handle server crashes and network partitions.

Session persistence: The server stores active sessions in a shared store (e.g., Redis, PostgreSQL). When a client reconnects, it sends its session ID, and the server restores its state.

Heartbeat monitoring: Clients send Ping frames every 30 seconds. The server tracks last_seen timestamps. If a client’s last_seen is older than 60 seconds, the server marks it as disconnected.

Load balancing with sticky sessions (session affinity): The load balancer uses X-WebSocket-Session or X-WebSocket-User headers to route all messages from a client to the same worker.

Graceful shutdown: When a server shuts down, it:

Stops accepting new connections.
Sends Close frames to all connected clients.
Waits for acknowledgments.
Closes the connection after a timeout.

A failure mode: a server crashes while sending a large data message. The client receives part of the message but the server fails before sending the final frame. The client must detect incomplete messages and request retransmission.

Common Pitfalls and Best Practices

Masking: Clients must apply masking to all frames sent to the server. Servers must verify the mask. A masked frame sent without masking leads to corrupted payload.

Fragmentation and streaming: A server sends a large JSON object as multiple frames. The client must concatenate the data until FIN = 1, but it may not handle partial frames correctly.

Message size limits: Servers often limit the maximum message size (e.g., 64 KB, 1 MB). A client sending a 2 MB message may receive a 1009 (message too big) error.

Compression: Use permessage-deflate extension to reduce bandwidth. Clients and servers must negotiate the Extensions header during handshake.

  Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits=10; server_max_window_bits=10

Protocol versioning: Servers may support multiple WebSocket versions. Clients should handle version negotiation and fallback.

Error propagation: When a client sends an invalid message, the server should send a 1007 (invalid data) error with the Reason field.

Connection upgrades: Ensure the server supports Upgrade: websocket and Connection: Upgrade in the handshake. A missing Connection: Upgrade leads to incomplete handshakes.

In summary, WebSocket Architecture is not just a protocol—it is a pattern of real-time, stateful communication. Success depends on careful handling of the handshake, frame format, lifecycle, error codes, and message routing. The smallest misstep—missing Connection: Upgrade, unmasked frames, or incorrect FIN bits—can manifest as subtle, hard-to-diagnose issues in production.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.