Merge pull request #79 from lancelet/docs-improvement-fs2-backend

Improve documentation for fs2

1 files 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 <https://github.com/AsyncHttpClient/async-http-client>`_.
 A fully **asynchronous** backend, which uses `Netty <http://netty.io>`_ behind the
@@ -21,6 +23,7 @@ The responses are wrapped depending on the dependency chosen in either a:
 * `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``.
+* `fs2 <https://github.com/functional-streams-for-scala/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 <https://github.com/functional-streams-for-scala/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()