Add support for choosing a process to reply to

4 files changed, 86 insertions, 22 deletions

diff --git a/doc/src/guide/http.asciidoc b/doc/src/guide/http.asciidoc
index 465a4c5..e856fb1 100644
--- a/doc/src/guide/http.asciidoc
+++ b/doc/src/guide/http.asciidoc
@@ -45,7 +45,7 @@ handling of responses will be explained further on.
 
 ==== GET and HEAD
 
-Use `gun:get/{2,3}` to request a resource.
+Use `gun:get/{2,3,4}` to request a resource.
 
 .GET "/organizations/ninenines"
 
@@ -64,7 +64,7 @@ Note that the list of headers has the field name as a binary.
 The field value is iodata, which is either a binary or an
 iolist.
 
-Use `gun:head/{2,3}` if you don't need the response body.
+Use `gun:head/{2,3,4}` if you don't need the response body.
 
 .HEAD "/organizations/ninenines"
 
@@ -101,7 +101,7 @@ desirable. The request body of a PATCH method may be a partial
 representation or a list of instructions on how to update the
 resource.
 
-The `gun:post/4`, `gun:put/4` and `gun:patch/4` functions
+The `gun:post/{4,5}`, `gun:put/{4,5}` and `gun:patch/{4,5}` functions
 take a body as their fourth argument. These functions do
 not require any body-specific header to be set, although
 it is always recommended to set the content-type header.
@@ -171,7 +171,7 @@ do_sendfile(ConnPid, StreamRef, IoDevice) ->
 
 ==== DELETE
 
-Use `gun:delete/{2,3}` to delete a resource.
+Use `gun:delete/{2,3,4}` to delete a resource.
 
 .DELETE "/organizations/ninenines"
 
@@ -211,7 +211,7 @@ StreamRef = gun:options(ConnPid, "*").
 
 ==== Requests with an arbitrary method
 
-The `gun:request/{4,5}` function can be used to send requests
+The `gun:request/{4,5,6}` function can be used to send requests
 with a configurable method name. It is mostly useful when you
 need a method that Gun does not understand natively.
 
@@ -360,3 +360,14 @@ gun:flush(ConnPid).
 
 [source,erlang]
 gun:flush(StreamRef).
+
+=== Redirecting responses to a different process
+
+Gun allows you to specify which process will handle responses
+to a request via the `reply_to` request option.
+
+.GET "/organizations/ninenines" to a different process
+
+[source,erlang]
+StreamRef = gun:get(ConnPid, "/organizations/ninenines", [],
+	#{reply_to => Pid}).
diff --git a/doc/src/guide/protocols.asciidoc b/doc/src/guide/protocols.asciidoc
index 2180c5b..5e3b273 100644
--- a/doc/src/guide/protocols.asciidoc
+++ b/doc/src/guide/protocols.asciidoc
@@ -10,7 +10,7 @@ sends a request, the server sends back a response.
 
 Gun provides convenience functions for performing GET, HEAD,
 OPTIONS, POST, PATCH, PUT, and DELETE requests. All these
-functions are aliases of `gun:request/{4,5}` for each respective
+functions are aliases of `gun:request/{4,5,6}` for each respective
 methods. Gun also provides a `gun:data/4` function for streaming
 the request body.
 
diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
index 4869a2e..f99dea7 100644
--- a/doc/src/guide/websocket.asciidoc
+++ b/doc/src/guide/websocket.asciidoc
@@ -64,6 +64,10 @@ after 1000 ->
 	exit(timeout)
 end.
 
+Note that you shouldn't use the `reply_to` request option
+for connections you plan to upgrade, because only the
+owner of the connection will receive messages about it.
+
 === Sending data
 
 Once the Websocket upgrade has completed successfully, you no
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 83f119a..7b9ddd0 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -64,6 +64,15 @@ keepalive => pos_integer()::
 version => 'HTTP/1.1' | 'HTTP/1.0'::
 	HTTP version to use. Defaults to 'HTTP/1.1'.
 
+=== req_opts() = map()
+
+Configuration for a particular request.
+
+The following keys are defined:
+
+reply_to => pid()::
+	The pid of a process that is responsible for the response handling.
+
 === spdy_opts() = map()
 
 Configuration for the SPDY protocol.
@@ -241,41 +250,56 @@ Gracefully close the connection.
 A monitor can be used to be notified when the connection is
 effectively closed.
 
-=== delete(ConnPid, Path) -> delete(ConnPid, Path, [])
+=== delete(ConnPid, Path) -> delete(ConnPid, Path, [], #{})
+
+Alias of `gun:delete/4`.
 
-Alias of `gun:delete/3`.
+=== delete(ConnPid, Path, Headers) -> delete(ConnPid, Path, Headers, #{})
 
-=== delete(ConnPid, Path, Headers) -> StreamRef
+Alias of `gun:delete/4`.
+
+=== delete(ConnPid, Path, Headers, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Path = iodata():: Path to the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Delete a resource.
 
-=== get(ConnPid, Path) -> get(ConnPid, Path, [])
+=== get(ConnPid, Path) -> get(ConnPid, Path, [], #{})
+
+Alias of `gun:get/4`.
+
+=== get(ConnPid, Path, Headers) -> get(ConnPid, Path, Headers, #{})
 
-Alias of `gun:get/3`.
+Alias of `gun:get/4`.
 
-=== get(ConnPid, Path, Headers) -> StreamRef
+=== get(ConnPid, Path, Headers, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Path = iodata():: Path to the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Get a resource.
 
-=== head(ConnPid, Path) -> head(ConnPid, Path, [])
+=== head(ConnPid, Path) -> head(ConnPid, Path, [], #{})
+
+Alias of `gun:head/4`.
+
+=== head(ConnPid, Path, Headers) -> head(ConnPid, Path, Headers, #{})
 
-Alias of `gun:head/3`.
+Alias of `gun:head/4`.
 
-=== head(ConnPid, Path, Headers) -> StreamRef
+=== head(ConnPid, Path, Headers, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Path = iodata():: Path to the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Get headers of a resource.
@@ -288,15 +312,20 @@ While servers should send the same headers they would if the
 request was a GET, like `content-length`, it is not always
 the case and differences may exist.
 
-=== options(ConnPid, Path) -> options(ConnPid, Path, [])
+=== options(ConnPid, Path) -> options(ConnPid, Path, [], #{})
 
-Alias of `gun:options/3`.
+Alias of `gun:options/4`.
 
-=== options(ConnPid, Path, Headers) -> StreamRef
+=== options(ConnPid, Path, Headers) -> options(ConnPid, Path, Headers, #{})
+
+Alias of `gun:options/4`.
+
+=== options(ConnPid, Path, Headers, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Path = iodata():: Path to the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Obtain information about the capabilities of the server or of a resource.
@@ -324,12 +353,17 @@ with instructions on how to update the resource.
 
 You can use the `gun:data/4` function to send the body, if any.
 
-=== patch(ConnPid, Path, Headers, Body) -> StreamRef
+=== patch(ConnPid, Path, Headers, Body) -> patch(ConnPid, Path, Headers, Body, #{})
+
+Alias of `gun:patch/5`.
+
+=== patch(ConnPid, Path, Headers, Body, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Path = iodata():: Path to the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
 Body = iodata():: Body of the request.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Request that a set of changes be applied to the resource.
@@ -366,12 +400,17 @@ located at a different URI.
 
 You can use the `gun:data/4` function to send the body, if any.
 
-=== post(ConnPid, Path, Headers, Body) -> StreamRef
+=== post(ConnPid, Path, Headers, Body) -> post(ConnPid, Path, Headers, Body, #{})
+
+Alias of `gun:post/5`.
+
+=== post(ConnPid, Path, Headers, Body, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Path = iodata():: Path to the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
 Body = iodata():: Body of the request.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Process the enclosed representation according to the resource's own semantics.
@@ -407,12 +446,17 @@ highly recommended to set both when possible.
 
 You can use the `gun:data/4` function to send the body, if any.
 
-=== put(ConnPid, Path, Headers, Body) -> StreamRef
+=== put(ConnPid, Path, Headers, Body) -> put(ConnPid, Path, Headers, Body, #{})
+
+Alias of `gun:put/5`.
+
+=== put(ConnPid, Path, Headers, Body, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Path = iodata():: Path to the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
 Body = iodata():: Body of the request.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Create or replace a resource.
@@ -447,13 +491,18 @@ highly recommended to set both when possible.
 
 You can use the `gun:data/4` function to send the body, if any.
 
-=== request(ConnPid, Method, Path, Headers, Body) -> StreamRef
+=== request(ConnPid, Method, Path, Headers, Body) -> request(ConnPid, Method, Path, Headers, Body, #{})
+
+Alias of `gun:request/6`.
+
+=== request(ConnPid, Method, Path, Headers, Body, ReqOpts) -> StreamRef
 
 ConnPid = pid():: The pid of the Gun connection process.
 Method = iodata():: Request method.
 Path = iodata():: Path of the resource.
 Headers = [{binary(), iodata()}]:: Additional request headers.
 Body = iodata():: Body of the request.
+ReqOpts = req_opts():: Request options.
 StreamRef = reference():: Identifier of the stream for this request.
 
 Perform the given request.