From 1322692b7f6bf311366b98b47550bd13a981ef5f Mon Sep 17 00:00:00 2001 From: Jonathan Merritt Date: Thu, 19 Apr 2018 13:10:19 +1000 Subject: Improve documentation for fs2 - Add fs2 dependencies and implicit backend val. - Add fs2 streaming example. - Fix Monix request example to include the implicit backend val. --- docs/backends/asynchttpclient.rst | 49 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/docs/backends/asynchttpclient.rst b/docs/backends/asynchttpclient.rst index 00180b7..d8fabb5 100644 --- a/docs/backends/asynchttpclient.rst +++ b/docs/backends/asynchttpclient.rst @@ -10,6 +10,8 @@ To use, add the following dependency to your project:: "com.softwaremill.sttp" %% "async-http-client-backend-monix" % "1.1.12" // or "com.softwaremill.sttp" %% "async-http-client-backend-cats" % "1.1.12" + // or + "com.softwaremill.sttp" %% "async-http-client-backend-fs2" % "1.1.12" This backend depends on `async-http-client `_. A fully **asynchronous** backend, which uses `Netty `_ behind the @@ -21,6 +23,7 @@ The responses are wrapped depending on the dependency chosen in either a: * `Scalaz `_ ``Task``. There's a transitive dependency on ``scalaz-concurrent``. * `Monix `_ ``Task``. There's a transitive dependency on ``monix-eval``. * Any type implementing the `Cats Effect `_ ``Async`` typeclass, such as ``cats.effect.IO``. There's a transitive dependency on ``cats-effect``. +* `fs2 `_ ``Stream``. There are transitive dependencies on ``fs2``, ``fs2-reactive-streams``, and ``cats-effect``. Next you'll need to add an implicit value:: @@ -34,6 +37,9 @@ Next you'll need to add an implicit value:: // or, if you're using the cats effect version: implicit val sttpBackend = AsyncHttpClientCatsBackend[cats.effect.IO]() + + // or, if you're using the fs2 version: + implicit val sttpBackend = AsyncHttpClientFs2Backend[cats.effect.IO]() // or, if you'd like to use custom configuration: implicit val sttpBackend = AsyncHttpClientFutureBackend.usingConfig(asyncHttpClientConfig) @@ -47,12 +53,15 @@ 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 com.softwaremill.sttp.asynchttpclient.monix._ import java.nio.ByteBuffer import monix.reactive.Observable + implicit val sttpBackend = AsyncHttpClientMonixBackend() + val obs: Observable[ByteBuffer] = ... - + sttp .streamBody(obs) .post(uri"...") @@ -74,5 +83,41 @@ And receive responses as an observable stream:: .response(asStream[Observable[ByteBuffer]]) .send() -It's also possible to use `fs2 `_ streams for sending request & receiving responses. +Streaming using fs2 +------------------- + +The fs2 backend supports streaming in any instance of the ``cats.effect.Effect`` typeclass, such as ``cats.effect.IO``. If ``IO`` is used then the type of supported streams is ``fs2.Stream[IO, ByteBuffer]``. + +Requests can be sent with a streaming body like this:: + + import com.softwaremill.sttp._ + import com.softwaremill.sttp.asynchttpclient.fs2.AsyncHttpClientFs2Backend + + import java.nio.ByteBuffer + import cats.effect.IO + import fs2.Stream + + implicit val sttpBackend = AsyncHttpClientFs2Backend[IO]() + val stream: Stream[IO, ByteBuffer] = ... + + sttp + .streamBody(stream) + .post(uri"...") + +Responses can also be streamed:: + + import com.softwaremill.sttp._ + import com.softwaremill.sttp.asynchttpclient.fs2.AsyncHttpClientFs2Backend + + import java.nio.ByteBuffer + import cats.effect.IO + import fs2.Stream + + implicit val sttpBackend = AsyncHttpClientFs2Backend[IO]() + + val response: IO[Response[Stream[IO, ByteBuffer]]] = + sttp + .post(uri"...") + .response(asStream[Stream[IO, ByteBuffer]]) + .send() -- cgit v1.2.3