Merge pull request #223 from tallarium/update-docs

Update docs

README.md

@@ -6,16 +6,17 @@
 [![License](https://img.shields.io/hexpm/l/reverse_proxy_plug.svg)](https://github.com/tallarium/reverse_proxy_plug/blob/master/LICENSE.md)
 [![Last Updated](https://img.shields.io/github/last-commit/tallarium/reverse_proxy_plug.svg)](https://github.com/tallarium/reverse_proxy_plug/commits/master)
 
-A reverse proxy plug for proxying a request to another URL using [HTTPoison](https://github.com/edgurgel/httpoison).
-Perfect when you need to transparently proxy requests to another service but
-also need to have full programmatic control over the outgoing requests.
+A reverse proxy plug for proxying a request to another URL using a choice of
+Elixir HTTP client libraries. Perfect when you need to transparently proxy
+requests to another service but also need to have full programmatic control
+over the outgoing requests.
 
 This project grew out of a fork of
 [elixir-reverse-proxy](https://github.com/slogsdon/elixir-reverse-proxy).
 Advantages over the original include more flexible upstreams, zero-delay
-chunked transfer encoding support, HTTP2 support with Cowboy 2 and focus on
-being a composable Plug instead of providing a standalone reverse proxy
-application.
+chunked transfer encoding support, HTTP2 support with Cowboy 2, several options
+for HTTP client libraries and focus on being a composable Plug instead of
+providing a standalone reverse proxy application.
 
 ## Installation
 
@@ -28,24 +29,27 @@ def deps do
 end
 ```
 
-Then add an HTTP client library, either
-[httpoison](https://hex.pm/packages/httpoison) or
-[tesla](https://hex.pm/packages/tesla), and configure depending on your choice:
+Then add an HTTP client library, one of:
+- [HTTPoison](https://hex.pm/packages/httpoison)
+- [Tesla](https://hex.pm/packages/tesla)
+- [Finch](https://hex.pm/packages/finch)
+- [Req](https://hex.pm/packages/req)
+
+and configure depending on your choice, e.g.:
 
 ```elixir
 config :reverse_proxy_plug, :http_client, ReverseProxyPlug.HTTPClient.Adapters.HTTPoison
-# OR
-config :reverse_proxy_plug, :http_client, ReverseProxyPlug.HTTPClient.Adapters.Tesla
 ```
 
 You can also set the config as a per-plug basis, which will override any global config.
-Either of those must be set, otherwise the system will attempt to default to the HTTPoison
-adapter or raise if it's not present.
 
 ```elixir
 plug ReverseProxyPlug, client: ReverseProxyPlug.HTTPClient.Adapters.Tesla
 ```
 
+Either of those must be set, otherwise the system will attempt to default to the HTTPoison
+adapter or raise if it's not present.
+
 ## Usage
 
 The plug works best when used with
@@ -126,7 +130,7 @@ headers.
 - `:stream` (default) - The response from the plug will always be chunk
 encoded. If the upstream server sends a chunked response, ReverseProxyPlug
 will pass chunks to the clients as soon as they arrive, resulting in zero
-delay.
+delay. Not all adapters support the `:stream` response mode currently.
 
 - `:buffer` - The plug will wait until the whole response is received from
 the upstream server, at which point it will send it to the client using
@@ -138,6 +142,17 @@ You can choose the response mode by passing a `:response_mode` option:
 forward("/foo", to: ReverseProxyPlug, response_mode: :buffer, upstream: "//example.com/bar")
 ```
 
+### Response header processing mode
+
+You can specify the behaviour of how headers from the upstream response are incorporated
+into the response that is sent from `reverse_proxy_plug`:
+- `:replace` - use `Conn.put_resp_header` to overwrite any existing headers present
+- `:prepend` - use `Conn.prepend_resp_header` to prepend headers from the upstream to existing
+response headers in `conn`.
+
+The defaults differ per response mode - `:stream_headers_mode` defaults to `:replace`, `:buffer_headers_mode`
+to `:prepend`.
+
 ### Client options
 
 You can pass options to the configured HTTP client. Valid options depend on the HTTP client used.

lib/reverse_proxy_plug/http_client/adapters/req.ex

@@ -3,7 +3,10 @@ if Code.ensure_loaded?(Req) do
     @moduledoc """
     Req adapter for the `ReverseProxyPlug.HTTPClient` behaviour
 
-    Only synchronous responses are supported.
+    Buffer resposne mode is supported for all Req versions.
+
+    Stream response mode is supported for Req 0.4.0 and up, when using
+    the Finch adapter.
 
     See the [Req documentation](https://hexdocs.pm/req/Req.html#new/1) for client-specific options.
     """

lib/reverse_proxy_plug/http_client/adapters/tesla.ex

@@ -3,7 +3,10 @@ if Code.ensure_loaded?(Tesla) do
     @moduledoc """
     Tesla adapter for the `ReverseProxyPlug.HTTPClient` behaviour
 
-    Only synchronous responses are supported.
+    Buffer response mode is supported for all Tesla versions.
+
+    Stream response mode is supported for Tesla 1.9.0 and up when using
+    the Finch adapter.
 
     ## Options