From 0a181681223aead4043b2437fe493652db6e5f8a Mon Sep 17 00:00:00 2001 From: Andrei Nesterov Date: Wed, 16 Nov 2016 20:57:11 +0300 Subject: Add support for choosing a process to reply to --- doc/src/guide/http.asciidoc | 21 ++++++++--- doc/src/guide/protocols.asciidoc | 2 +- doc/src/guide/websocket.asciidoc | 4 ++ doc/src/manual/gun.asciidoc | 81 ++++++++++++++++++++++++++++++++-------- 4 files changed, 86 insertions(+), 22 deletions(-) (limited to 'doc') 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. -- cgit v1.2.3