From 2b588340af501825f3ab03f2e76dba0353c98fae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 4 Jun 2018 12:59:26 +0200 Subject: Update documentation for Gun 1.0 --- docs/en/gun/1.0/guide/http/index.html | 141 +++++++++++++++++----------------- 1 file changed, 69 insertions(+), 72 deletions(-) (limited to 'docs/en/gun/1.0/guide/http/index.html') diff --git a/docs/en/gun/1.0/guide/http/index.html b/docs/en/gun/1.0/guide/http/index.html index 2753588e..6c32ab5d 100644 --- a/docs/en/gun/1.0/guide/http/index.html +++ b/docs/en/gun/1.0/guide/http/index.html @@ -7,8 +7,6 @@ - - Nine Nines: HTTP @@ -71,7 +69,7 @@ communicating with an HTTP/1.1 or HTTP/2 server.

Every time a request is initiated, Gun creates a stream. A stream reference uniquely identifies a set of request and -response(s) and must be used to perform additional operations +response and must be used to perform additional operations with a stream or to identify its messages.

Stream references use the Erlang reference data type and are therefore unique.

@@ -107,7 +105,7 @@ header if it has not been provided in the request arguments.

handling of responses will be explained further on.

GET and HEAD

-

Use gun:get/{2,3,4} to request a resource.

+

Use gun:get/2,3,4 to request a resource.

GET "/organizations/ninenines"
StreamRef = gun:get(ConnPid, "/organizations/ninenines", [
-        {<<"accept">>, "application/json"},
-        {<<"user-agent">>, "revolver/1.0"}
+    {<<"accept">>, "application/json"},
+    {<<"user-agent">>, "revolver/1.0"}
 ]).

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,4} 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"
StreamRef = gun:head(ConnPid, "/organizations/ninenines", [
-        {<<"accept">>, "application/json"},
-        {<<"user-agent">>, "revolver/1.0"}
+    {<<"accept">>, "application/json"},
+    {<<"user-agent">>, "revolver/1.0"}
 ]).

It is not possible to send a request body with a GET or HEAD request.

@@ -153,7 +151,7 @@ request.

POST, PUT and PATCH

HTTP defines three methods to create or update a resource.

POST is generally used when the resource identifier (URI) isn’t known -in advance when creating the resource. POST can also be used to +in advance when creating a resource. POST can also be used to replace an existing resource, although PUT is more appropriate in that situation.

PUT creates or replaces a resource identified by the URI.

@@ -163,7 +161,7 @@ request body. The PATCH method can be used when this is not 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,5}, gun:put/{4,5} and gun:patch/{4,5} 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. @@ -179,7 +177,7 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 

Body = "{\"msg\": \"Hello world!\"}",
 StreamRef = gun:post(ConnPid, "/organizations/ninenines", [
-        {<<"content-type">>, "application/json"}
+    {<<"content-type">>, "application/json"}
 ], Body).

The gun:post/3, gun:put/3 and gun:patch/3 functions do not take a body in their arguments. If a body is to be @@ -200,8 +198,8 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 

Body = "{\"msg\": \"Hello world!\"}",
 StreamRef = gun:post(ConnPid, "/organizations/ninenines", [
-        {<<"content-length">>, integer_to_binary(length(Body))},
-        {<<"content-type">>, "application/json"}
+    {<<"content-length">>, integer_to_binary(length(Body))},
+    {<<"content-type">>, "application/json"}
 ]),
 gun:data(ConnPid, StreamRef, fin, Body).

The atom fin indicates this is the last chunk of data to @@ -209,7 +207,6 @@ be sent. You can call the gun:data/4 function as many times as needed until you have sent the entire body. The last call must use fin and all the previous calls must use nofin. The last chunk may be empty.

-

@todo what to do about empty chunk, ignore?

Streaming the request body
sendfile(ConnPid, StreamRef, Filepath) ->
-        {ok, IoDevice} = file:open(Filepath, [read, binary, raw]),
-        do_sendfile(ConnPid, StreamRef, IoDevice).
+    {ok, IoDevice} = file:open(Filepath, [read, binary, raw]),
+    do_sendfile(ConnPid, StreamRef, IoDevice).
 
 do_sendfile(ConnPid, StreamRef, IoDevice) ->
-        case file:read(IoDevice, 8000) of
-                eof ->
-                        gun:data(ConnPid, StreamRef, fin, <<>>),
-                        file:close(IoDevice);
-                {ok, Bin} ->
-                        gun:data(ConnPid, StreamRef, nofin, Bin),
-                        do_sendfile(ConnPid, StreamRef, IoDevice)
-        end.
+ case file:read(IoDevice, 8000) of + eof -> + gun:data(ConnPid, StreamRef, fin, <<>>), + file:close(IoDevice); + {ok, Bin} -> + gun:data(ConnPid, StreamRef, nofin, Bin), + do_sendfile(ConnPid, StreamRef, IoDevice) + end.

DELETE

-

Use gun:delete/{2,3,4} to delete a resource.

+

Use gun:delete/2,3,4 to delete a resource.

DELETE "/organizations/ninenines"
StreamRef = gun:delete(ConnPid, "/organizations/ninenines", [
-        {<<"user-agent">>, "revolver/1.0"}
+    {<<"user-agent">>, "revolver/1.0"}
 ]).

OPTIONS

-

Use gun:options/{2,3} to request information about a resource.

+

Use gun:options/2,3 to request information about a resource.

OPTIONS "/organizations/ninenines"
StreamRef = gun:options(ConnPid, "/organizations/ninenines", [
-        {<<"user-agent">>, "revolver/1.0"}
+    {<<"user-agent">>, "revolver/1.0"}
 ]).

You can also use this function to request information about the server itself.

@@ -281,7 +278,7 @@ http://www.gnu.org/software/src-highlite -->

Requests with an arbitrary method

-

The gun:request/{4,5,6} 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.

@@ -291,7 +288,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
gun:request(ConnPid, "TRACE", "/", [
-        {<<"max-forwards">>, "30"}
+    {<<"max-forwards">>, "30"}
 ]).
@@ -319,32 +316,32 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
print_body(ConnPid, MRef) ->
-        StreamRef = gun:get(ConnPid, "/"),
-        receive
-                {gun_response, ConnPid, StreamRef, fin, Status, Headers} ->
-                        no_data;
-                {gun_response, ConnPid, StreamRef, nofin, Status, Headers} ->
-                        receive_data(ConnPid, MRef, StreamRef);
-                {'DOWN', MRef, process, ConnPid, Reason} ->
-                        error_logger:error_msg("Oops!"),
-                        exit(Reason)
-        after 1000 ->
-                exit(timeout)
-        end.
+    StreamRef = gun:get(ConnPid, "/"),
+    receive
+        {gun_response, ConnPid, StreamRef, fin, Status, Headers} ->
+            no_data;
+        {gun_response, ConnPid, StreamRef, nofin, Status, Headers} ->
+            receive_data(ConnPid, MRef, StreamRef);
+        {'DOWN', MRef, process, ConnPid, Reason} ->
+            error_logger:error_msg("Oops!"),
+            exit(Reason)
+    after 1000 ->
+        exit(timeout)
+    end.
 
 receive_data(ConnPid, MRef, StreamRef) ->
-        receive
-                {gun_data, ConnPid, StreamRef, nofin, Data} ->
-                        io:format("~s~n", [Data]),
-                        receive_data(ConnPid, MRef, StreamRef);
-                {gun_data, ConnPid, StreamRef, fin, Data} ->
-                        io:format("~s~n", [Data]);
-                {'DOWN', MRef, process, ConnPid, Reason} ->
-                        error_logger:error_msg("Oops!"),
-                        exit(Reason)
-        after 1000 ->
-                exit(timeout)
-        end.
+ receive + {gun_data, ConnPid, StreamRef, nofin, Data} -> + io:format("~s~n", [Data]), + receive_data(ConnPid, MRef, StreamRef); + {gun_data, ConnPid, StreamRef, fin, Data} -> + io:format("~s~n", [Data]); + {'DOWN', MRef, process, ConnPid, Reason} -> + error_logger:error_msg("Oops!"), + exit(Reason) + after 1000 -> + exit(timeout) + end.

While it may seem verbose, using messages like this has the advantage of never locking your process, allowing you to easily debug your code. It also allows you to start more than @@ -352,13 +349,13 @@ one connection and concurrently perform queries on all of them at the same time.

You can also use Gun in a synchronous manner by using the await functions.

-

The gun:await/{2,3,4} function will wait until it receives +

The gun:await/2,3,4 function will wait until it receives a response to, a pushed resource related to, or data from the given stream.

-

When calling gun:await/{2,3} and not passing a monitor +

When calling gun:await/2,3 and not passing a monitor reference, one is automatically created for you for the duration of the call.

-

The gun:await_body/{2,3,4} works similarly, but returns the +

The gun:await_body/2,3,4 works similarly, but returns the body received. Both functions can be combined to receive the response and its body sequentially.

@@ -369,11 +366,11 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
StreamRef = gun:get(ConnPid, "/"),
 case gun:await(ConnPid, StreamRef) of
-        {response, fin, Status, Headers} ->
-                no_data;
-        {response, nofin, Status, Headers} ->
-                {ok, Body} = gun:await_body(ConnPid, StreamRef),
-                io:format("~s~n", [Body])
+    {response, fin, Status, Headers} ->
+        no_data;
+    {response, nofin, Status, Headers} ->
+        {ok, Body} = gun:await_body(ConnPid, StreamRef),
+        io:format("~s~n", [Body])
 end.
@@ -397,11 +394,11 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
receive
-        {gun_push, ConnPid, OriginalStreamRef, PushedStreamRef,
-                        Method, Host, Path, Headers} ->
-                enjoy()
+    {gun_push, ConnPid, OriginalStreamRef, PushedStreamRef,
+            Method, Host, Path, Headers} ->
+        enjoy()
 end.
-

If you use the gun:await/{2,3,4} function, however, Gun +

If you use the gun:await/2,3,4 function, however, Gun will use the original reference to identify the message but will return a tuple that doesn’t contain it.

@@ -410,10 +407,10 @@ will return a tuple that doesn’t contain it.

by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -
{push, PushedStreamRef, Method, Host, Path, Headers}
-        = gun:await(ConnPid, OriginalStreamRef).
-

The PushedStreamRef variable can then be used with gun:await_body/{2,3,4} -if needed.

+
{push, PushedStreamRef, Method, URI, Headers}
+    = gun:await(ConnPid, OriginalStreamRef).
+

The PushedStreamRef variable can then be used with gun:await/2,3,4 +and gun:await_body/2,3,4.

@@ -451,7 +448,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
StreamRef = gun:get(ConnPid, "/organizations/ninenines", [],
-        #{reply_to => Pid}).
+ #{reply_to => Pid}). -- cgit v1.2.3