More docs

8 files changed, 80 insertions, 44 deletions

diff --git a/docs/backends/akkahttp.rst b/docs/backends/akkahttp.rst
index 53ebfda..0cda636 100644
--- a/docs/backends/akkahttp.rst
+++ b/docs/backends/akkahttp.rst
@@ -1,7 +1,7 @@
 .. _akkahttp:
 
-``AkkaHttpBackend``
-===================
+akka-http backend
+=================
 
 To use, add the following dependency to your project::
 
diff --git a/docs/backends/asynchttpclient.rst b/docs/backends/asynchttpclient.rst
index 8408175..5afab37 100644
--- a/docs/backends/asynchttpclient.rst
+++ b/docs/backends/asynchttpclient.rst
@@ -1,5 +1,5 @@
-``AsyncHttpClientBackend``
-==========================
+async-http-client backend
+=========================
 
 To use, add the following dependency to your project::
 
@@ -44,10 +44,7 @@ Next you'll need to add an implicit value::
 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::
+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._
   
@@ -77,6 +74,5 @@ 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.
+It's also possible to use `fs2 <https://github.com/functional-streams-for-scala/fs2>`_ streams for sending request & receiving responses.
 
diff --git a/docs/backends/custom.rst b/docs/backends/custom.rst
index 4dd5208..0820a26 100644
--- a/docs/backends/custom.rst
+++ b/docs/backends/custom.rst
@@ -3,7 +3,7 @@
 Custom backends, logging, metrics
 =================================
 
-It is also entirely possible to write custom own backend (if doing so, please consider contributing!) or wrapping an existing one. One can even write completely generic wrappers for any delegate backend, as each backend comes equipped with a monad for the response type. This brings the possibility to ``map`` and ``flatMap`` over responses. 
+It is also entirely possible to write custom backends (if doing so, please consider contributing!) or wrap an existing one. One can even write completely generic wrappers for any delegate backend, as each backend comes equipped with a monad for the response type. This brings the possibility to ``map`` and ``flatMap`` over responses. 
 
 Possible use-cases for wrapper-backend include:
  
@@ -11,7 +11,64 @@ Possible use-cases for wrapper-backend include:
 * capturing metrics
 * request signing (transforming the request before sending it to the delegate)
 
-To pass some context to wrapper-backends, requests can be *tagged*. Each ``RequestT`` instance contains a ``tags: Map[String, Any]`` field. This is unused by http, but can be used e.g. to pass a metric name or logging context.
+Request tagging
+---------------
 
-Example backend logging
+Each request contains a ``tags: Map[String, Any]`` map. This map can be used to tag the request with any backend-specific information, and isn't used in any way by sttp itself.
 
+Tags can be added to a request using the ``def tag(k: String, v: Any)`` method, and read using the ``def tag(k: String): Option[Any]`` method.
+
+Backends, or backend wrappers can use tags e.g. for logging, passing a metric name, using different connection pools, or even different delegate backends.
+
+Example backend wrapper
+-----------------------
+
+Below is an example on how to implement a backend wrapper, which sends metrics for completed requests and wraps any ``Future``-based backend::
+
+  // the metrics infrastructure
+  trait MetricsServer {
+    def reportDuration(name: String, duration: Long): Unit
+  }
+
+  class CloudMetricsServer extends MetricsServer {
+    override def reportDuration(name: String, duration: Long): Unit = ???
+  }
+
+  // the backend wrapper
+  class MetricWrapper[S](delegate: SttpBackend[Future, S],
+                            metrics: MetricsServer)
+      extends SttpBackend[Future, S] {
+  
+    override def send[T](request: Request[T, S]): Future[Response[T]] = {
+      val start = System.currentTimeMillis()
+
+      def report(metricSuffix: String): Unit = {
+        val metricPrefix = request.tag("metric").getOrElse("?")
+        val end = System.currentTimeMillis()
+        metrics.reportDuration(metricPrefix + "-" + metricSuffix, end - start)
+      }
+
+      delegate.send(request).andThen {
+        case Success(response) if response.is200 => report("ok")
+        case Success(response)                   => report("notok")
+        case Failure(t)                          => report("exception")
+      }
+    }
+
+    override def close(): Unit = delegate.close()
+
+    override def responseMonad: MonadError[Future] = delegate.responseMonad
+  }
+
+  // example usage
+  implicit val backend = new MetricWrapper(
+    AkkaHttpBackend(),
+    new CloudMetricsServer()
+  )
+
+  sttp
+    .get(uri"http://company.com/api/service1")
+    .tag("metric", "service1")
+    .send()
+
+  
diff --git a/docs/backends/httpurlconnection.rst b/docs/backends/httpurlconnection.rst
index fdea9b0..e0f6594 100644
--- a/docs/backends/httpurlconnection.rst
+++ b/docs/backends/httpurlconnection.rst
@@ -1,5 +1,5 @@
-``HttpURLConnectionBackend``
-============================
+HttpURLConnection backend
+=========================
 
 The default **synchronous** backend. Sending a request returns a response wrapped in the identity type constructor, which is equivalent to no wrapper at all.
  
diff --git a/docs/backends/okhttp.rst b/docs/backends/okhttp.rst
index 52fbc49..04796f1 100644
--- a/docs/backends/okhttp.rst
+++ b/docs/backends/okhttp.rst
@@ -1,5 +1,5 @@
-``OkHttpClientBackend``
-=======================
+OkHttp backend
+==============
 
 To use, add the following dependency to your project::
 
diff --git a/docs/backends/summary.rst b/docs/backends/summary.rst
index 36e50b0..d58bb54 100644
--- a/docs/backends/summary.rst
+++ b/docs/backends/summary.rst
@@ -5,7 +5,7 @@ Supported backends
 
 sttp suports a number of synchornous and asynchronous backends. It's the backends that take care of managing connections, sending requests and receiving responses: sttp defines only the API to describe the requests to be send and handle the response data. It's the backends where all the heavy-lifting is done.
 
-Choosing the right backend depends on a number of factors: if you are using sttp to explore some data, or is it a production system; are you using a synchornous, blocking architecture or an asynchronous one; do you work mostly with Scala's ``Future``, or maybe you use some form of a ``Task`` abstraction; finally, if you want to stream requests/responses, or not.
+Choosing the right backend depends on a number of factors: if you are using sttp to explore some data, or is it a production system; are you using a synchronous, blocking architecture or an asynchronous one; do you work mostly with Scala's ``Future``, or maybe you use some form of a ``Task`` abstraction; finally, if you want to stream requests/responses, or not.
 
 Each backend has two type parameters:
 
@@ -15,7 +15,7 @@ Each backend has two type parameters:
 Below is a summary of all the backends. See the sections on individual backend implementations for more information.
 
 ================================ ============================ ================================================
-Class                            Result wrapper               Supported stream type
+Class                            Response wrapper             Supported stream type
 ================================ ============================ ================================================
 ``HttpURLConnectionBackend``     None (``Id``)                n/a 
 ``AkkaHttpBackend``              ``scala.concurrent.Future``  ``akka.stream.scaladsl.Source[ByteString, Any]``
diff --git a/docs/backends/tagging.rst b/docs/backends/tagging.rst
deleted file mode 100644
index 15773ff..0000000
--- a/docs/backends/tagging.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Request tagging
-===============
-
-Each request contains a ``tags: Map[String, Any]`` map. This map can be used to tag the request with any backend-specific information, and isn't used in any way by sttp itself.
-
-Tags can be added to a request using the ``def tag(k: String, v: Any)`` method, and read using the ``def tag(k: String): Option[Any]`` method.
-
-Backends, or :ref:`backend wrappers <custombackends>` can use tags e.g. for logging, passing a metric name, using different connection pools, or even different delegate backends.
-
diff --git a/docs/backends/testing.rst b/docs/backends/testing.rst
index 0ac21c2..c0cfc6f 100644
--- a/docs/backends/testing.rst
+++ b/docs/backends/testing.rst
@@ -1,13 +1,9 @@
 Testing
 =======
 
-If you need a stub backend for use in tests instead of a "real" backend (you 
-probably don't want to make HTTP calls during unit tests), you can use the
-``SttpBackendStub`` class. It allows specifying how the backend should respond
-to requests matching given predicates.
+If you need a stub backend for use in tests instead of a "real" backend (you probably don't want to make HTTP calls during unit tests), you can use the ``SttpBackendStub`` class. It allows specifying how the backend should respond to requests matching given predicates.
 
-A backend stub can be created using an instance of a "real" backend, or by
-explicitly giving the response wrapper monad and supported streams type.
+A backend stub can be created using an instance of a "real" backend, or by explicitly giving the response wrapper monad and supported streams type.
 
 For example::
 
@@ -23,18 +19,14 @@ For example::
   val response2 = sttp.post(uri"http://example.org/d/e").send()
   // response2.code will be 500
 
-However, this approach has one caveat: the responses are not type-safe. That
-is, the backend cannot match on or verify that the type included in the 
-response matches the response type requested.
+However, this approach has one caveat: the responses are not type-safe. That is, the backend cannot match on or verify that the type included in the response matches the response type requested.
 
-It is also possible to create a stub backend which delegates calls to another
-(possibly "real") backend if none of the specified predicates match a request.
-This can be useful during development, to partially stub a yet incomplete
-API with which we integrate::
+It is also possible to create a stub backend which delegates calls to another (possibly "real") backend if none of the specified predicates match a request. This can be useful during development, to partially stub a yet incomplete API with which we integrate::
 
-  implicit val testingBackend = SttpBackendStub.withFallback(HttpURLConnectionBackend())
-    .whenRequestMatches(_.uri.path.startsWith(List("a")))
-    .thenRespond("I'm a STUB!")
+  implicit val testingBackend =
+    SttpBackendStub.withFallback(HttpURLConnectionBackend())
+      .whenRequestMatches(_.uri.path.startsWith(List("a")))
+      .thenRespond("I'm a STUB!")
       
   val response1 = sttp.get(uri"http://api.internal/a").send()
   // response1.body will be Right("I'm a STUB")