webSocketHandler function

Handler webSocketHandler(ConnectionCallback onConnection, { Iterable<String>? protocols, Iterable<String>? allowedOrigins, Duration? pingInterval, })

Creates a Shelf handler that upgrades HTTP requests to WebSocket connections.

Only valid WebSocket upgrade requests are upgraded. If a request doesn't look like a WebSocket upgrade request, a 404 Not Found is returned; if a request looks like an upgrade request but is invalid, a 400 Bad Request is returned; and if a request is a valid upgrade request but has an origin that doesn't match allowedOrigins (see below), a 403 Forbidden is returned. This means that this can be placed first in a Cascade and only upgrade requests will be handled.

The onConnection takes a WebSocketChannel as its first argument and a nullable string, the WebSocket subprotocol, as its second argument. The subprotocol is determined by looking at the client's Sec-WebSocket-Protocol header and selecting the first entry that also appears in protocols. If no subprotocols are shared between the client and the server, null will be passed instead and no subprotocol header will be sent to the client which may cause it to disconnect.

If allowedOrigins is passed, browser connections will only be accepted if they're made by a script from one of the given origins. This ensures that malicious scripts running in the browser are unable to fake a WebSocket handshake. Note that non-browser programs can still make connections freely. See also the WebSocket spec's discussion of origin considerations.

If pingInterval is specified, it will get passed to the created channel instance, enabling round-trip disconnect detection. See WebSocketChannel for more details.

Implementation

Handler webSocketHandler(
  ConnectionCallback onConnection, {
  Iterable<String>? protocols,
  Iterable<String>? allowedOrigins,
  Duration? pingInterval,
}) {
  return WebSocketHandler(
    onConnection,
    protocols?.toSet(),
    allowedOrigins?.map((origin) => origin.toLowerCase()).toSet(),
    pingInterval,
  ).handle;
}