WebSockets

One of the optional capabilities (represented as WebSockets) that a backend can support are websockets (see backends summary). Websocket requests are described exactly the same as regular requests, starting with basicRequest, adding headers, specifying the request method and uri.

A websocket request will be sent instead of a regular one if the response specification includes handling the response as a websocket. Depending on the backend you are using, there are three variants of websocket response specifications: synchronous, asynchronous and streaming. To use them, add one of the following imports:

• import sttp.client4.ws.sync._ if you are using a synchronous backend (such as DefaultSyncBackend), without any effect wrappers

• import sttp.client4.ws.async._ if you are using an asynchronous backend (e.g. based on Futures or IOs)

• import sttp.client4.ws.stream._ if you want to handle web socket messages using a non-blocking stream (e.g. fs2.Stream or akka.stream.scaladsl.Source)

The above imports will bring into scope a number of asWebSocket(...) methods, giving a couple of variants of working with websockets.

Using WebSocket

The first variant of interacting with web sockets is using sttp.client4.ws.SyncWebSocket (sync variant), or sttp.ws.WebSocket[F] (async variant), where F is the backend-specific effects wrapper, such as Future or IO. These classes contain two basic methods:

• def receive: WebSocketFrame (optionally wrapped with F[_] in the async variant) which will complete once a message is available, and return the next incoming frame (which can be a data, ping, pong or close)

• def send(f: WebSocketFrame, isContinuation: Boolean = false): Unit (again optionally wrapped with F[_]), which sends a message to the websocket. The WebSocketFrame companion object contains methods for creating binary/text messages. When using fragmentation, the first message should be sent using finalFragment = false, and subsequent messages using isContinuation = true.

The SyncWebSocket / WebSocket classes also contain other methods for receiving only text/binary messages, as well as automatically sending Pong responses when a Ping is received.

The following response specifications which use SyncWebSocket are available in the sttp.client4.ws.sync object (the second type parameter of WebSocketResponseAs specifies the type returned as the response body):

import sttp.client4._
import sttp.model.ResponseMetadata
import sttp.client4.ws.SyncWebSocket

// when using import sttp.client4.ws.sync._

def asWebSocket[T](f: SyncWebSocket => T): 
  WebSocketResponseAs[Identity, Either[String, T]] = ???

def asWebSocketWithMetadata[T](
   f: (SyncWebSocket, ResponseMetadata) => T
): WebSocketResponseAs[Identity, Either[String, T]] = ???

def asWebSocketAlways[T](f: SyncWebSocket => T): 
  WebSocketResponseAs[Identity, T] = ???

def asWebSocketAlwaysWithMetadata[T](
  f: (SyncWebSocket, ResponseMetadata) => T
): WebSocketResponseAs[Identity, T] = ???

def asWebSocketUnsafe: 
  WebSocketResponseAs[Identity, Either[String, SyncWebSocket]] = ???

def asWebSocketAlwaysUnsafe: 
  WebSocketResponseAs[Identity, SyncWebSocket] = ???

The first variant, asWebSocket, passes an open SyncWebSocket to the user-provided function. This function should only return once interaction with the websocket is finished. The backend can then safely close the websocket. The value that’s returned as the response body is either an error (represented as a String), in case the websocket upgrade didn’t complete successfully, or the value returned by the websocket-interacting method.

The second variant (asWebSocketAlways) is similar, but any errors due to failed websocket protocol upgrades are represented as exceptions.

The remaining two variants return the open SyncWebSocket directly, as the response body. It is then the responsibility of the client code to close the websocket, once it’s no longer needed.

Similar response specifications, but using an effect wrapper and WebSocket[F], are available in the sttp.client4.ws.async objet.

See also the examples, which include examples involving websockets.

Using streams

Another possibility is to work with websockets by providing a streaming stage, which transforms incoming data frames into outgoing frames. This can be e.g. an Akka Flow or a fs2 Pipe.

The following response specifications are available:

import sttp.client4._
import sttp.capabilities.{Streams, WebSockets}
import sttp.ws.WebSocketFrame

// when using import sttp.client4.ws.stream._

def asWebSocketStream[S](s: Streams[S])(p: s.Pipe[WebSocketFrame.Data[_], WebSocketFrame]): 
  WebSocketStreamResponseAs[Either[String, Unit], S] = ???

def asWebSocketStreamAlways[S](s: Streams[S])(p: s.Pipe[WebSocketFrame.Data[_], WebSocketFrame]): 
  WebSocketStreamResponseAs[Unit, S] = ???

Using streaming websockets requires the backend to support the given streaming capability (see also streaming). Streaming capabilities are described as implementations of Streams[S], and are provided by backend implementations, e.g. AkkaStreams or Fs2Streams[F].

When working with streams of websocket frames keep in mind that a text payload may be fragmented into multiple frames. sttp provides two useful methods (fromTextPipe, fromTextPipeF) for each backend to aggregate these fragments back into complete messages. These methods can be found in corresponding WebSockets classes for given effect type:

effect type	class name
monix.Task	sttp.client4.impl.monix.MonixWebSockets
ZIO	sttp.client4.impl.zio.ZioWebSockets
fs2.Stream	sttp.client4.impl.fs2.Fs2WebSockets

Compression

For those who plan to use a lot of websocket traffic, you could consider websocket compression. See the information on configuring individual backends for more information.

Implementation-specific configuration

OkHttp based backends

• supports compression (default: not enabled)

akka-http backend

Compression is not yet available, to track Akka developments in this area, see this issue.

async-http-client based backends (deprecated)

Note

Note that the async-http-client is no longer maintained, thus backends based on it should not be used in the new projects.

Web socket settings can be adjusted by providing a custom AsyncHttpClientConfig, which can be created using new DefaultAsyncHttpClientConfig.Builder().

Some available settings:

• maximum web socket frame size. Default: 10240, can be changed using .setWebSocketMaxFrameSize.

• compression. Default: false, can be changed using: .setEnablewebSocketCompression.