NGINX WebSocket Proxying

References

• NGINX WebSocket Proxying

Related

• protocol switch mechanism
• • The Upgrade general-header allows the client to specify what additional communication protocols it supports and would like to use if the server finds it appropriate to switch protocols. The server MUST use the Upgrade header field within a 101 (Switching Protocols) response to indicate which protocols are being switched.
  • The Upgrade header field is intended to provide a simple mechanism for transition from HTTP/1.1 to some other, incompatible protocol. It does so by allowing the client to advertise its desire to use another protocol, such as a later version of HTTP with a higher major version number, even though the current request has been made using HTTP/1.1.
• hop-by-hop header
• • For the purpose of defining the behavior of caches and non-caching proxies, we divide HTTP headers into two categories:

1. 1. 1. End-to-End headers, which are transmitted to the ultimate recipient of a request or response. End-to-end headers in responses MUST be stored as part of a cache entry and MUST be transmitted in any response formed from a cache entry.
      2. Hop-by-hop headers, which are meaningful only for a single transport-level connection, are not stored by caches or forwarded by proxies.

• • The following HTTP/1.1 headers are hop-by-hop headers:

• • • Connection
    • Keep-Alive
    • Proxy-Authenticate
    • Proxy-Authorization
    • TE
    • Trailers
    • Transfer-Encoding
    • Upgrade
  • All other headers defined by HTTP/1.1 are end-to-end headers.
• proxy_read_timeout

Syntax: proxy_read_timeout time;
Syntax: proxy_read_timeout 60s;
Context: http, server, location

• • This nginx directive defines a timeout for reading a response from the proxied server. The timeout is set only between two successive read operations, not for the transmission of the whole response. if the proxied server does not transmit anything within this time, the connection is closed.

Notes

To turn a connection between a client and a server form HTTP/1.1 into WebSocket, the protocol switch mechanism available in HTTP/1.1 is used.

There is one subtlety, however: since the "Upgrade" is a hop-by-hop header, it is not passed from a client to the proxied server. With forward proxying, clients may use the CONNECT method to circumvent this issue. This does not work with reverse proxying, however, since clients are not aware of any proxy servers, and special processing on a proxy server is required.

nginx implements special mode of operation that allows setting up a tunnel between a client and proxied server if the proxied server returned a response with the code 101 (Switching Protocols), and the client asked for a protocol switch via the Upgrade header in a request.

hop-by-hop headers including Upgrade and Connection are not passed form a client to proxied server, therefore in order for the proxied server to know about the client's intention to switch a protocol to WebSocket, these headers have to be passed explicitly:

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

A more sophisticated example in which a value of the Connection header field in a request to the proxied server depends on the presence of the Upgrade field in the client request header.

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

    server {
        ...

        location /chat/ {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
        }
    }
}

By default, the connection will be closed if the proxied server does not transmit any data within 60 seconds. This timeout can be increased with the proxy_read_timeout directive. Alternatively, the proxied server can be configured to periodically send WebSocket ping frames to reset the timeout and check if the connection is still alive.