WebSockets passthrough

WebSockets are two-way communication channels between a client device (such as a web browser) and a server, allowing the server to send messages to the client at any time without the client having to make a request.

Unlike the HTTP requests which make up the bulk of web traffic handled by Fastly, WebSockets are long-lived connections and do not have a request-response cycle, but instead can carry data in either direction at any time. As a result, WebSockets don't fit Fastly's normal processing model for edge traffic, but since WebSocket connections begin life as HTTP requests, you can upgrade a request to a WebSocket connection.

HINT: WebSocket passthrough creates one WebSocket connection to origin for every connection from a client device to Fastly. To have Fastly broker messages for you, with channels, and one-to-many publishing, consider using Fanout instead.

Enabling websocket passthrough

IMPORTANT: WebSocket passthough is a feature that must be enabled by a Fastly employee. Once you have created a service, reach out to your account contact or support@fastly.com, citing your service ID, to request that passthrough be enabled on it.

To use WebSocket passthrough, you need a Rust-based Fastly compute service. You can create one, automatically populated with the code needed to perform websocket passthrough, using fastly compute init:

$ fastly compute init --from=https://github.com/fastly/compute-starter-kit-rust-websockets
$ fastly compute publish

Compute@Edge programs are typically invoked for each client request and end when you deliver a response. To handle the WebSocket connection, the request must be handed off from Compute@Edge so that Fastly can continue to hold the connection and relay traffic in both directions.

This is performed by the upgrade_websocket method on the Request struct. If you are expecting your service to handle more than just WebSockets traffic, it's a good idea to only do this when the request has an Upgrade: websocket header:

use fastly::experimental::RequestUpgradeWebsocket;
use fastly::{Error, Request};
fn main() -> Result<(), Error> {
let req = Request::from_client();
if let Some("websocket") = req.get_header_str("Upgrade") {
return Ok(req.upgrade_websocket("ws_backend_name")?);

The following tips and best practices may help you get the most out of WebSockets passthrough:

  • Unlike most Rust-based Compute@Edge programs, you cannot use the #[fastly::main] macro in a program that does upgrade_websocket. This is because upgrade_websocket will immediately start a response to the client, making it impossible to return a Response from the main() function without causing an error.
  • It is not currently possible to modify the Request (or use a constructed Request) for the upgrade_websocket invocation. If you try this, the WebSocket upgrade will be based on the original request as presented by the client.
  • WebSocket connections, once upgraded, are not subject to the between_bytes_timeout, and will only drop when either the client or server disconnects.
  • If either the client or server disconnects, Fastly will relay that disconnect to the other party.