diff options
Diffstat (limited to 'docs/backends/asynchttpclient.rst')
-rw-r--r-- | docs/backends/asynchttpclient.rst | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/docs/backends/asynchttpclient.rst b/docs/backends/asynchttpclient.rst new file mode 100644 index 0000000..cd359b1 --- /dev/null +++ b/docs/backends/asynchttpclient.rst @@ -0,0 +1,82 @@ +``AsyncHttpClientBackend`` +========================== + +To use, add the following dependency to your project:: + + "com.softwaremill.sttp" %% "async-http-client-backend-future" % "0.0.20" + // or + "com.softwaremill.sttp" %% "async-http-client-backend-scalaz" % "0.0.20" + // or + "com.softwaremill.sttp" %% "async-http-client-backend-monix" % "0.0.20" + // or + "com.softwaremill.sttp" %% "async-http-client-backend-cats" % "0.0.20" + +This backend depends on `async-http-client <https://github.com/AsyncHttpClient/async-http-client>`_. +A fully **asynchronous** backend, which uses `Netty <http://netty.io>`_ behind the +scenes. + +The responses are wrapped depending on the dependency chosen in either a: + +* standard Scala ``Future`` +* `Scalaz <https://github.com/scalaz/scalaz>`_ ``Task``. There's a transitive dependency on ``scalaz-concurrent``. +* `Monix <https://monix.io`_ ``Task``. There's a transitive dependency on ``monix-eval``. +* Any type implementing the `Cats Effect <https://github.com/typelevel/cats-effect>`_ ``Async`` typeclass, such as ``cats.effect.IO``. There's a transitive dependency on ``cats-effect``. + +Next you'll need to add an implicit value:: + + implicit val sttpBackend = AsyncHttpClientFutureBackend() + + // or, if you're using the scalaz version: + implicit val sttpBackend = AsyncHttpClientScalazBackend() + + // or, if you're using the monix version: + implicit val sttpBackend = AsyncHttpClientMonixBackend() + + // or, if you're using the cats effect version: + implicit val sttpBackend = AsyncHttpClientCatsBackend[cats.effect.IO]() + + // or, if you'd like to use custom configuration: + implicit val sttpBackend = AsyncHttpClientFutureBackend.usingConfig(asyncHttpClientConfig) + + // or, if you'd like to instantiate the AsyncHttpClient yourself: + implicit val sttpBackend = AsyncHttpClientFutureBackend.usingClient(asyncHttpClient) + +Streaming using Monix +--------------------- + +The Monix backend supports streaming (as both Monix and Async Http Client +support reactive streams ``Publisher``s out of the box). The type of +supported streams in this case is ``Observable[ByteBuffer]``. That is, you can +set such an observable as a request body:: + + import com.softwaremill.sttp._ + + import java.nio.ByteBuffer + import monix.reactive.Observable + + val obs: Observable[ByteBuffer] = ... + + sttp + .streamBody(obs) + .post(uri"...") + +And receive responses as an observable stream:: + + import com.softwaremill.sttp._ + import com.softwaremill.sttp.asynchttpclient.monix._ + + import java.nio.ByteBuffer + import monix.eval.Task + import monix.reactive.Observable + + implicit val sttpBackend = AsyncHttpClientMonixBackend() + + val response: Task[Response[Observable[ByteBuffer]]] = + sttp + .post(uri"...") + .response(asStream[Observable[ByteBuffer]]) + .send() + +It's also possible to use `fs2 <https://github.com/functional-streams-for-scala/fs2>`_ +streams for sending request & receiving responses. + |