Project: Easegress (Orchestration & Management / API Gateway)
File: 2.6.Websocket.md

- Reverse proxy is one of most popular features of Easegress and it's suitable for many production and development scenarios. In reversed proxy use cases, `WebSocket` is a widely used protocol for a full-duplex communication solution between client and server. WebSocket relies on TCP.[1] Many reverse proxy support `WebSocket`,e.g., NGINX[2], Traefik, and so on. The `WebSocketProxy` is a filter of Easegress, and can be put into a pipeline. Easegress uses `nhooyr.io/websocket` to implement `WebSocketProxy` filter. Spec Pipeline with a `WebSocketProxy` filter: ```yaml name: websocket-pipeline kind: Pipeline flow: filter: wsproxy filters: kind: WebSocketProxy name: wsproxy defaultOrigin: http://127.0.0.1/hello pools: servers: url: ws://127.0.0.1:12345 keepHost: true url: ws://127.0.0.1:9095 url: ws://127.0.0.1:9096 url: ws://127.0.0.1:9097 loadBalance: policy: roundRobin clientMaxMsgSize: 32769 serverMaxMsgSize: 32769 ``` HTTPServer to route traffic to the websocket-pipeline: ```yaml name: demo-server kind: HTTPServer port: 8080 rules: paths: path: /ws clientMaxBodySize: -1 # REQUIRED! backend: websocket-pipeline ``` Note: `clientMaxBodySize` must be `-1`. Request sequence ```none +--+ +--+ +--+ | | 1 | | 2 | | | client +>| Easegress +>| websocket | | |<+ |<+ backend | | | 4 | | 3 | | +--+ +--+ +--+ ``` Headers We copy all headers from your HTTP request to websocket backend, except ones used by websocket package to build connection. Based on [3], we also add `X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Proto` to http headers that send to websocket backend. note: websocket use `Upgrade`, `Connection`, `Sec-Websocket-Key`, `Sec-Websocket-Version`, `Sec-Websocket-Extensions` and `Sec-Websocket-Protocol` in http headers to set connection. Perform a health check on the servers in the pool. If a server fails the check, it will be marked as unhealthy, and requests will be rerouted to other healthy servers until it regains health. Health check for websocket proxy contains both http way or websocket way. The HTTP check involves a request-response evaluation similar to a Proxy filter. In the WebSocket method, a successful connection yields a 101 status code. Additional headers can be set and evaluated in both methods. If you send both two ways of health check, then a server passes both HTTP and WebSocket health checks, it will be considered healthy. More details in . ```yaml kind: WebSocketProxy name: proxy-example-1 pools: servers: url: ws://127.0.0.1:9095 url: ws://127.0.0.1:9096 url: ws://127.0.0.1:9097 healthCheck: interval: 60s timeout: 3s fails: 1 pass: 1 ws: port: 10080 uri: /health/ws headers: X-Health-Check: easegress match: statusCodes: [101, 101] # 101 headers: name: X-Status value: healthy type: exact http: uri: /health ``` Send request ```bash curl --include \ --no-buffer \ --header "Connection: Upgrade" \ --header "Upgrade: websocket" \ --header "Host: 127.0.0.1:10020" \ --header "Sec-WebSocket-Key: your-key-here" \ --header "Sec-WebSocket-Version: 13" \ http://127.0.0.1:8080/ ``` This request to Easegress will be forwarded to websocket backend `ws://127.0.0.1:12345`. <https://datatracker.ietf.org/doc/html/rfc6455> <https://www.nginx.com/blog/websocket-nginx/> <https://docs.oracle.com/en-us/iaas/Content/Balance/Reference/httpheaders.htm>