Http4s backend

This backend is based on http4s (client) and is asynchronous. To use, add the following dependency to your project:

"com.softwaremill.sttp.client3" %% "http4s-backend" % "3.0.0"

Add some imports as well:

import cats.effect._
import sttp.client3.http4s._
import scala.concurrent._

// an implicit `cats.effect.ContextShift` is required to create an instance of `cats.effect.Concurrent` 
// for `cats.effect.IO`,  as well as a `cats.effect.Blocker` instance. 
// Note that you'll probably want to use a different thread pool for blocking.
implicit val cs: ContextShift[IO] = IO.contextShift(
val blocker: cats.effect.Blocker = Blocker.liftExecutionContext(

The backend can be created for any type implementing the cats.effect.ConcurrentEffect typeclass, such as cats.effect.IO. Moreover, an implicit ContextShift will have to be in scope as well.

If a blocker instance is not available, a new one can be created, and the resource definition can be chained, e.g. as follows:

implicit val cs: ContextShift[IO] = IO.contextShift( // or another instance
Blocker[IO].flatMap(Http4sBackend.usingDefaultBlazeClientBuilder[IO](_)).use { implicit backend => ... }

Sending a request is a non-blocking, lazily-evaluated operation and results in a wrapped response. There’s a transitive dependency on http4s.

There are also other cats-effect-based backends, which don’t depend on http4s.

Please note that:

  • the backend contains an optional dependency on http4s-blaze-client, to provide the Http4sBackend.usingBlazeClientBuilder and Http4sBackend.usingDefaultBlazeClientBuilder methods. This makes the client usable with other http4s client implementations, without the need to depend on blaze.
  • the backend does not support SttpBackendOptions,that is specifying proxy settings (proxies are not implemented in http4s, see this issue), as well as configuring the connect timeout
  • the backend does not support the RequestT.options.readTimeout option

Instead, all custom timeout configuration should be done by creating a org.http4s.client.Client[F], using e.g. org.http4s.client.blaze.BlazeClientBuilder[F] and passing it to the appropriate method of the Http4sBackend object.

The backend supports streaming using fs2. For usage details, see the documentation on streaming using fs2.

The backend doesn’t support websockets.