Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 30 ยท Proxying and Load Balancing

WebSockets, Streaming and Long Requests

Make long-lived connections work through a proxy: WebSocket Upgrade headers, proxy_http_version, read timeouts, SSE without buffering and client_max_body_size.

A normal request is short: the browser asks, the backend answers, the connection is done. A proxy tuned for that pattern can break three kinds of traffic: WebSockets (a connection that stays open for hours), streaming responses such as Server-Sent Events (the answer arrives in pieces over minutes), and large uploads (a request body that is far bigger than a typical form).

Each one fails in a recognizable way. WebSockets fail with a handshake error, streams arrive all at once at the end, and uploads are rejected with 413 Request Entity Too Large. In this lesson you learn why, and the few directives that fix each case in nginx and Apache. It builds on Reverse Proxy Basics, so keep proxy_pass, buffering and timeouts in mind.

Three traffic types that need care

WebSocket Needs the Upgrade headers passed on.
Streaming Needs buffering turned off.
Big upload Needs a higher body limit.

Defaults are tuned for short pages, not for these.

1 / 2

WebSockets through a proxy

A WebSocket starts life as an ordinary HTTP request that asks to be upgraded. The client sends:

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

If the server agrees, it replies 101 Switching Protocols with Sec-WebSocket-Accept, and from then on the same TCP connection carries WebSocket frames in both directions.

The trouble is that Connection and Upgrade are hop-by-hop headers: they describe one connection, not the end-to-end request. A proxy is expected to drop them, and nginx does. It also talks to backends with HTTP/1.0 by default, which has no upgrade mechanism. So the backend receives a plain request and answers with a normal page or an error instead of 101.

The fix tells nginx to use HTTP/1.1 and to pass the two headers on explicitly:

NGINX
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    location /ws/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host       $host;
        proxy_read_timeout 1h;
    }
}

The map (placed in the http context) produces upgrade when the client sent an Upgrade header and close otherwise, so ordinary requests on the same location still behave normally. Simpler configs hard-code Connection "upgrade" on a location that only serves WebSockets.

The last line matters as much as the headers. Remember that proxy_read_timeout is the silence allowed between two reads. A chat connection that is quiet for 61 seconds would be cut by the 60 second default. Either raise the timeout or make the application send a ping frame more often than the timeout.

Apache needs mod_proxy_wstunnel (plus mod_proxy). From version 2.4.47 the regular ProxyPass can upgrade a connection by itself when you add upgrade=websocket; older setups use a separate ws:// URL:

APACHE
# 2.4.47 and newer
ProxyPass        "/ws/" "http://127.0.0.1:3000/ws/" upgrade=websocket
ProxyPassReverse "/ws/" "http://127.0.0.1:3000/ws/"

# any 2.4 version
ProxyPass        "/ws/" "ws://127.0.0.1:3000/ws/"

Put the WebSocket rule before a broad ProxyPass "/", because Apache uses the first matching rule.

What the handshake proves

The Sec-WebSocket-Accept value is not encryption. It is the Base64 of the SHA-1 hash of the client's key plus a fixed GUID from the specification, and it only proves that the server really understood the upgrade. This stand-in performs that handshake with a real Node server against both kinds of request: one that arrives with its upgrade headers intact, and one with them stripped, as a default proxy would.

Node.js The Upgrade handshake, with and without the headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first attempt is upgraded, and its accept value matches the example key from the WebSocket specification. The second attempt is what a proxy without the Upgrade and Connection settings produces: the backend sees an ordinary request and refuses. The stand-in stops at the handshake; real WebSocket traffic after 101 is binary frames that this page does not implement.

Streaming responses and SSE

Server-Sent Events (SSE) keep one HTTP response open and write small text messages into it (Content-Type: text/event-stream). Live dashboards, progress bars and AI chat answers often work this way. It is plain HTTP, so no upgrade is needed. The problem is buffering: with proxy_buffering on (the default) nginx collects the backend's output and sends it to the client in larger blocks, so the browser sees nothing until a buffer fills or the response ends.

There are two ways to stop that for a streaming location:

NGINX
location /events {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 1h;
}

The backend can also opt out per response by sending the header X-Accel-Buffering: no, which nginx honors. This is convenient because the app that streams knows it is streaming, while the proxy config can stay generic. Other hops matter too: if gzip is enabled for text/event-stream, the compressor may hold data back, so exclude that type from compression (see HTTP/2, HTTP/3, gzip and Brotli). A CDN or a second proxy in front may also buffer unless told otherwise.

In Apache, mod_proxy streams by default for most responses, but mod_deflate and other output filters can buffer. Apache's ProxyPass option flushpackets=on forces data out as it arrives, and flushwait sets a delay in milliseconds when you want some batching.

The next stand-in shows the effect. A Node backend emits three events 60 ms apart. One proxy buffers the whole answer, the other forwards each chunk immediately. The client reads the stream and reports how many chunks it received and whether the first one arrived while the backend was still talking. The checks are about order and counts, not exact timing, so the result is stable.

Node.js Buffered or streaming: what the client sees

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

With buffering, the client gets all three events in one chunk after the backend has finished, which in a browser would look like a frozen page followed by a sudden burst. Without buffering, the events arrive separately and the first one shows up while the backend is still working. Real nginx behaves like this on a larger scale: the buffer sizes are proxy_buffer_size and proxy_buffers, and nginx may also spill a big response to a temporary file.

Large uploads

nginx refuses request bodies larger than client_max_body_size, which defaults to 1 MB. The client receives 413 Request Entity Too Large, often with a confusing browser-side network error. Set the limit where the upload happens and, if needed, raise the timeout as well:

NGINX
location /upload {
    client_max_body_size 200m;
    client_body_timeout  120s;
    proxy_pass http://127.0.0.1:3000;
    proxy_request_buffering off;   # stream the body straight to the backend
}

proxy_request_buffering off sends the body to the backend as it arrives instead of storing it first. That saves disk space and shows progress to the backend sooner, but a slow client then occupies a backend worker for the whole upload, so use it only for backends built to handle that. Setting client_max_body_size 0 disables the check completely, which is rarely a good idea on a public server.

Remember that the backend and your framework have their own limits. A PHP app also needs upload_max_filesize and post_max_size raised, and many frameworks cap request bodies as well. The smallest limit in the chain wins.

Apache's equivalent is LimitRequestBody (bytes, default unlimited), set inside the right Directory or Location. Behind mod_proxy the limit that most often bites is the one on the backend.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a WebSocket handshake fail through a default nginx proxy?

    You need proxy_http_version 1.1 plus proxy_set_header Upgrade $http_upgrade and Connection so the backend sees the upgrade request.
  2. 2. An SSE endpoint works directly, but through the proxy messages arrive in a burst at the end. What is the likely cause?

    With buffering on, the proxy holds back data. proxy_buffering off on that location, or an X-Accel-Buffering: no header from the app, fixes it.
  3. 3. A user uploads a 5 MB file and receives 413. What is the first nginx setting to check?

    The default limit is 1 MB. 413 means the request body was larger than the allowed size.
  4. 4. Why raise proxy_read_timeout for a quiet WebSocket location?

    An idle but healthy connection looks like silence. Use a long timeout, or have the app send periodic pings.

Summary

  • WebSockets need proxy_http_version 1.1 and the Upgrade and Connection headers passed on; in Apache use mod_proxy_wstunnel or upgrade=websocket.
  • Raise proxy_read_timeout on such locations, or have the app ping more often than the timeout.
  • SSE and other streams need proxy_buffering off (or X-Accel-Buffering: no) and no compression of text/event-stream.
  • client_max_body_size defaults to 1 MB and produces 413; remember the backend's own limits too.
  • proxy_request_buffering off streams uploads through, at the cost of tying up a backend worker.

Next: combine the two servers in Nginx in Front of Apache.