WebSocket and Nginx Reverse Proxy Configuration Guide

1. Introduction

WebSocket is a bi-directional, full-duplex communication protocol that operates over a single TCP connection. Unlike traditional HTTP, where the client sends a request and the server responds, WebSocket allows both client and server to send messages to each other at any time during the session.

This makes it highly suitable for real-time applications such as chat systems, live dashboards, and streaming services.

2. How WebSocket Works

Traditional HTTP

In HTTP:

The client sends a request.
The server sends a response.
The connection is then closed (unless using persistent connections).

WebSocket

In WebSocket:

The client initiates an HTTP request with special headers to upgrade the connection from HTTP to WebSocket.
The server accepts the upgrade and switches protocols.
Once established, both sides can exchange data freely over a persistent TCP connection.

3. Establishing a WebSocket Connection

Client → Server (Upgrade Request)

The WebSocket connection starts as a standard HTTP request with additional headers:

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

Server → Client (Upgrade Response)

If the server supports WebSocket, it responds with:

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

4. Header Explanation

Upgrade: Indicates the protocol the client wants to switch to (in this case, websocket).
Connection: Must include the value Upgrade to signal the intention to upgrade the connection.
Sec-WebSocket-Key: A randomly generated Base64-encoded value (16 bytes) sent by the client. It ensures a unique connection and prevents cross-protocol attacks.
Sec-WebSocket-Version: Specifies the WebSocket protocol version the client supports. Most servers use version 13. If not supported, the server responds with:
```
HTTP/1.1 426 Upgrade Required
Sec-WebSocket-Version: 13
```
Sec-WebSocket-Accept: Returned by the server as proof that it successfully accepted the handshake. It’s derived from the client’s Sec-WebSocket-Key using a predefined GUID.

5. HTTP Version Requirement

WebSocket requires HTTP/1.1 or higher because:

HTTP/1.0 opens a new TCP connection for each request, leading to high overhead.
HTTP/1.1 introduced persistent connections (Keep-Alive), allowing multiple requests to share a single TCP connection.

For example:

In HTTP/1.0, downloading 4 images would open 4 separate TCP connections.
In HTTP/1.1, one TCP connection can handle all 4 requests.

WebSocket leverages this concept to maintain a single long-lived TCP connection between the client and server.

6. Enabling WebSocket Support in Nginx

When using Nginx as a reverse proxy, the connection upgrade must be explicitly configured.

Example Configuration

location / {
    proxy_pass http://backend:8080;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_http_version 1.1;
}

Explanation

proxy_pass: Forwards the request to the backend service.
proxy_set_header Upgrade $http_upgrade; Passes the Upgrade header from the client to the backend.
proxy_set_header Connection "upgrade"; Ensures Nginx forwards the Connection: Upgrade header required for WebSocket.
proxy_http_version 1.1; Enables HTTP/1.1 support in proxying, required for WebSocket functionality.

7. Summary

Feature	Description
Protocol	Bi-directional, full-duplex
Base Protocol	HTTP/1.1
Upgrade Mechanism	HTTP 101 Switching Protocols
Persistent Connection	Yes
Key Headers	Upgrade, Connection, Sec-WebSocket-Key, Sec-WebSocket-Version, Sec-WebSocket-Accept
Nginx Requirement	Must enable `proxy_http_version 1.1` and pass upgrade headers

4.6 KiB Raw Blame History Unescape Escape