feat(#81): add docs for middleware API

README.md

@@ -223,12 +223,21 @@ In other words, you can create or use middleware as you already know with the ty
 
 As a kind of inversion of control, `rocky` exposes a tiny API in every `http.ClientRequest` passed via the middleware layer:
 
+##### Request
+
 - **req.rocky** `object`
   - **.options** `object` - Expose the [configuration](#configuration) options for the current request.
   - **.proxy** `Rocky` - Expose the rocky instance. Use only for hacking purposes!
   - **.route** `Route` - Expose the current running route. Only available in `route` type middleware
 - **req.stopReplay** `boolean` - Optional field internally checked by `rocky` to stop the request replay process.
 
+##### Response
+
+- **res.rocky** `object`
+  - **.options** `object` - Expose the [configuration](#configuration) options for the current request.
+  - **.proxy** `Rocky` - Expose the rocky instance. Use only for hacking purposes!
+  - **.route** `Route` - Expose the current running route. Only available in `route` type middleware
+
 This allows you way to extend or modify specific values from the middleware layer with HTTP request flow accuracy level, and therefore without having side-effects with other routes.
 
 Example replacing the target server URL:

lib/protocols/http/passes/forward.js

@@ -90,24 +90,6 @@ function forwardRetryRequest (route, opts, forwardReq, res, done) {
   }
 }
 
-function forwardRequest (route, opts, forwardReq, res, done) {
-  const proxy = new HttpProxy
-
-  // Use the proper request body
-  useRequestBody(forwardReq, opts)
-
-  // Prepare propagation of proxy events to parent bus
-  propagateEvents(proxy, route, finisher)
-
-  // Finally forward the request
-  proxy.web(forwardReq, res, opts, finisher)
-
-  function finisher () {
-    cleanup(proxy)
-    done.apply(null, arguments)
-  }
-}
-
 function defineHostHeader (forwardReq, opts) {
   const forwardHost = opts.forwardHost
   if (!forwardHost) return
@@ -127,6 +109,24 @@ function defineHostHeader (forwardReq, opts) {
   if (host) headers.host = host
 }
 
+function forwardRequest (route, opts, forwardReq, res, done) {
+  const proxy = new HttpProxy
+
+  // Use the proper request body
+  useRequestBody(forwardReq, opts)
+
+  // Prepare propagation of proxy events to parent bus
+  propagateEvents(proxy, route, finisher)
+
+  // Finally forward the request
+  proxy.web(forwardReq, res, opts, finisher)
+
+  function finisher () {
+    cleanup(proxy)
+    done.apply(null, arguments)
+  }
+}
+
 function useRequestBody (forwardReq, opts) {
   var body = forwardReq.body