diff options
Diffstat (limited to 'docs/en/gun/1.0/guide')
| -rw-r--r-- | docs/en/gun/1.0/guide/connect.asciidoc | 94 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/connect/index.html | 57 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/gun.sty | 8 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/http.asciidoc | 199 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/http/index.html | 141 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/index.html | 2 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/introduction.asciidoc | 38 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/introduction/index.html | 45 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/protocols.asciidoc | 46 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/protocols/index.html | 51 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/start.asciidoc | 46 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/start/index.html | 42 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/websocket.asciidoc | 97 | ||||
| -rw-r--r-- | docs/en/gun/1.0/guide/websocket/index.html | 62 |
14 files changed, 452 insertions, 476 deletions
diff --git a/docs/en/gun/1.0/guide/connect.asciidoc b/docs/en/gun/1.0/guide/connect.asciidoc index e0b09d6c..dd4297d1 100644 --- a/docs/en/gun/1.0/guide/connect.asciidoc +++ b/docs/en/gun/1.0/guide/connect.asciidoc @@ -1,3 +1,4 @@ +[[connect]] == Connection This chapter describes how to open, monitor and close @@ -26,31 +27,33 @@ to reconnect automatically. === Opening a new connection -The `gun:open/{2,3}` function must be used to open a connection. +The `gun:open/2,3` function must be used to open a connection. .Opening a connection to example.org on port 443 - [source,erlang] +---- {ok, ConnPid} = gun:open("example.org", 443). +---- If the port given is 443, Gun will attempt to connect using -SSL. The protocol will be selected automatically using the +TLS. The protocol will be selected automatically using the ALPN extension for TLS. By default Gun supports HTTP/2 -and HTTP/1.1 when connecting using SSL. +and HTTP/1.1 when connecting using TLS. -For any other port, Gun will attempt to connect using TCP -and will use the HTTP/1.1 protocol. +For any other port, Gun will attempt to connect using +plain TCP and will use the HTTP/1.1 protocol. -The transport and protocol used can be overriden using +The transport and protocol used can be overriden via options. The manual documents all available options. Options can be provided as a third argument, and take the form of a map. -.Opening an SSL connection to example.org on port 8443 - +.Opening a TLS connection to example.org on port 8443 [source,erlang] -{ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}). +---- +{ok, ConnPid} = gun:open("example.org", 8443, #{transport => tls}). +---- === Waiting for the connection to be established @@ -58,22 +61,23 @@ When Gun successfully connects to the server, it sends a `gun_up` message with the protocol that has been selected for the connection. -Gun provides the functions `gun:await_up/{1,2,3}` that wait +Gun provides the functions `gun:await_up/1,2,3` that wait for the `gun_up` message. They can optionally take a monitor reference and/or timeout value. If no monitor is provided, one will be created for the duration of the function call. .Synchronous opening of a connection - [source,erlang] +---- {ok, ConnPid} = gun:open("example.org", 443), {ok, Protocol} = gun:await_up(ConnPid). +---- === Handling connection loss When the connection is lost, Gun will send a `gun_down` message indicating the current protocol, the reason the -connection was lost and two list of stream references. +connection was lost and two lists of stream references. The first list indicates open streams that _may_ have been processed by the server. The second list indicates open @@ -81,41 +85,41 @@ streams that the server did not process. === Monitoring the connection process -@todo Gun should detect the owner process being killed - Because software errors are unavoidable, it is important to detect when the Gun process crashes. It is also important to detect when it exits normally. Erlang provides two ways to do that: links and monitors. Gun leaves you the choice as to which one will be used. -However, if you use the `gun:await/{2,3}` or `gun:await_body/{2,3}` +However, if you use the `gun:await/2,3` or `gun:await_body/2,3` functions, a monitor may be used for you to avoid getting stuck waiting for a message that will never come. If you choose to monitor yourself you can do it on a permanent basis rather than on every message you will receive, saving -resources. Indeed, the `gun:await/{3,4}` and `gun:await_body/{3,4}` +resources. Indeed, the `gun:await/3,4` and `gun:await_body/3,4` functions both accept a monitor argument if you have one already. .Monitoring the connection process - [source,erlang] +---- {ok, ConnPid} = gun:open("example.org", 443). MRef = monitor(process, ConnPid). +---- This monitor reference can be kept and used until the connection process exits. .Handling `DOWN` messages - [source,erlang] +---- receive - %% Receive Gun messages here... - {'DOWN', Mref, process, ConnPid, Reason} -> - error_logger:error_msg("Oops!"), - exit(Reason); + %% Receive Gun messages here... + {'DOWN', Mref, process, ConnPid, Reason} -> + error_logger:error_msg("Oops!"), + exit(Reason) end. +---- What to do when you receive a `DOWN` message is entirely up to you. @@ -125,30 +129,32 @@ The connection can be stopped abruptly at any time by calling the `gun:close/1` function. .Immediate closing of the connection - [source,erlang] +---- gun:close(ConnPid). +---- The process is stopped immediately without having a chance to perform the protocol's closing handshake, if any. -=== Closing the connection gracefully - -The connection can also be stopped gracefully by calling the -`gun:shutdown/1` function. - -.Graceful shutdown of the connection - -[source,erlang] -gun:shutdown(ConnPid). - -Gun will refuse any new requests or messages after you call -this function. It will however continue to send you messages -for existing streams until they are all completed. - -For example if you performed a GET request just before calling -`gun:shutdown/1`, you will still receive the response before -Gun closes the connection. - -If you set a monitor beforehand, you will receive a message -when the connection has been closed. +//=== Closing the connection gracefully +// +//The connection can also be stopped gracefully by calling the +//`gun:shutdown/1` function. +// +//.Graceful shutdown of the connection +//[source,erlang] +//---- +//gun:shutdown(ConnPid). +//---- +// +//Gun will refuse any new requests or messages after you call +//this function. It will however continue to send you messages +//for existing streams until they are all completed. +// +//For example if you performed a GET request just before calling +//`gun:shutdown/1`, you will still receive the response before +//Gun closes the connection. +// +//If you set a monitor beforehand, you will receive a message +//when the connection has been closed. diff --git a/docs/en/gun/1.0/guide/connect/index.html b/docs/en/gun/1.0/guide/connect/index.html index 1e35e16b..ac1e6eb3 100644 --- a/docs/en/gun/1.0/guide/connect/index.html +++ b/docs/en/gun/1.0/guide/connect/index.html @@ -7,8 +7,6 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: Connection</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -89,7 +87,7 @@ to reconnect automatically.</p></div> <div class="sect1"> <h2 id="_opening_a_new_connection">Opening a new connection</h2> <div class="sectionbody"> -<div class="paragraph"><p>The <code>gun:open/{2,3}</code> function must be used to open a connection.</p></div> +<div class="paragraph"><p>The <code>gun:open/2,3</code> function must be used to open a connection.</p></div> <div class="listingblock"> <div class="title">Opening a connection to example.org on port 443</div> <div class="content"><!-- Generator: GNU source-highlight @@ -98,22 +96,22 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>)<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>If the port given is 443, Gun will attempt to connect using -SSL. The protocol will be selected automatically using the +TLS. The protocol will be selected automatically using the ALPN extension for TLS. By default Gun supports HTTP/2 -and HTTP/1.1 when connecting using SSL.</p></div> -<div class="paragraph"><p>For any other port, Gun will attempt to connect using TCP -and will use the HTTP/1.1 protocol.</p></div> -<div class="paragraph"><p>The transport and protocol used can be overriden using +and HTTP/1.1 when connecting using TLS.</p></div> +<div class="paragraph"><p>For any other port, Gun will attempt to connect using +plain TCP and will use the HTTP/1.1 protocol.</p></div> +<div class="paragraph"><p>The transport and protocol used can be overriden via options. The manual documents all available options.</p></div> <div class="paragraph"><p>Options can be provided as a third argument, and take the form of a map.</p></div> <div class="listingblock"> -<div class="title">Opening an SSL connection to example.org on port 8443</div> +<div class="title">Opening a TLS connection to example.org on port 8443</div> <div class="content"><!-- Generator: GNU source-highlight by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">8443</span>, #{<span style="color: #0000FF">transport</span><span style="color: #990000">=></span><span style="color: #FF6600">ssl</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">8443</span>, #{<span style="color: #0000FF">transport</span> <span style="color: #990000">=></span> <span style="color: #FF6600">tls</span>})<span style="color: #990000">.</span></tt></pre></div></div> </div> </div> <div class="sect1"> @@ -122,7 +120,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>When Gun successfully connects to the server, it sends a <code>gun_up</code> message with the protocol that has been selected for the connection.</p></div> -<div class="paragraph"><p>Gun provides the functions <code>gun:await_up/{1,2,3}</code> that wait +<div class="paragraph"><p>Gun provides the functions <code>gun:await_up/1,2,3</code> that wait for the <code>gun_up</code> message. They can optionally take a monitor reference and/or timeout value. If no monitor is provided, one will be created for the duration of the function call.</p></div> @@ -141,7 +139,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody"> <div class="paragraph"><p>When the connection is lost, Gun will send a <code>gun_down</code> message indicating the current protocol, the reason the -connection was lost and two list of stream references.</p></div> +connection was lost and two lists of stream references.</p></div> <div class="paragraph"><p>The first list indicates open streams that <em>may</em> have been processed by the server. The second list indicates open streams that the server did not process.</p></div> @@ -150,18 +148,17 @@ streams that the server did not process.</p></div> <div class="sect1"> <h2 id="_monitoring_the_connection_process">Monitoring the connection process</h2> <div class="sectionbody"> -<div class="paragraph"><p>@todo Gun should detect the owner process being killed</p></div> <div class="paragraph"><p>Because software errors are unavoidable, it is important to detect when the Gun process crashes. It is also important to detect when it exits normally. Erlang provides two ways to do that: links and monitors.</p></div> <div class="paragraph"><p>Gun leaves you the choice as to which one will be used. -However, if you use the <code>gun:await/{2,3}</code> or <code>gun:await_body/{2,3}</code> +However, if you use the <code>gun:await/2,3</code> or <code>gun:await_body/2,3</code> functions, a monitor may be used for you to avoid getting stuck waiting for a message that will never come.</p></div> <div class="paragraph"><p>If you choose to monitor yourself you can do it on a permanent basis rather than on every message you will receive, saving -resources. Indeed, the <code>gun:await/{3,4}</code> and <code>gun:await_body/{3,4}</code> +resources. Indeed, the <code>gun:await/3,4</code> and <code>gun:await_body/3,4</code> functions both accept a monitor argument if you have one already.</p></div> <div class="listingblock"> <div class="title">Monitoring the connection process</div> @@ -180,10 +177,10 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - <span style="font-style: italic"><span style="color: #9A1900">%% Receive Gun messages here...</span></span> - {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">Mref</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>); + <span style="font-style: italic"><span style="color: #9A1900">%% Receive Gun messages here...</span></span> + {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">Mref</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>) <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>What to do when you receive a <code>DOWN</code> message is entirely up to you.</p></div> </div> @@ -204,28 +201,6 @@ http://www.gnu.org/software/src-highlite --> perform the protocol’s closing handshake, if any.</p></div> </div> </div> -<div class="sect1"> -<h2 id="_closing_the_connection_gracefully">Closing the connection gracefully</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The connection can also be stopped gracefully by calling the -<code>gun:shutdown/1</code> function.</p></div> -<div class="listingblock"> -<div class="title">Graceful shutdown of the connection</div> -<div class="content"><!-- Generator: GNU source-highlight -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:shutdown</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Gun will refuse any new requests or messages after you call -this function. It will however continue to send you messages -for existing streams until they are all completed.</p></div> -<div class="paragraph"><p>For example if you performed a GET request just before calling -<code>gun:shutdown/1</code>, you will still receive the response before -Gun closes the connection.</p></div> -<div class="paragraph"><p>If you set a monitor beforehand, you will receive a message -when the connection has been closed.</p></div> -</div> -</div> diff --git a/docs/en/gun/1.0/guide/gun.sty b/docs/en/gun/1.0/guide/gun.sty new file mode 100644 index 00000000..d5e0d3be --- /dev/null +++ b/docs/en/gun/1.0/guide/gun.sty @@ -0,0 +1,8 @@ +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{asciidoc-dblatex}[2012/10/24 AsciiDoc DocBook Style] + +%% Just use the original package and pass the options. +\RequirePackageWithOptions{docbook} + +%% Define an alias for make snippets to be compatible with source-highlighter. +\lstalias{makefile}{make} diff --git a/docs/en/gun/1.0/guide/http.asciidoc b/docs/en/gun/1.0/guide/http.asciidoc index ff4aa0aa..652030a3 100644 --- a/docs/en/gun/1.0/guide/http.asciidoc +++ b/docs/en/gun/1.0/guide/http.asciidoc @@ -1,3 +1,4 @@ +[[http]] == HTTP This chapter describes how to use the Gun client for @@ -7,7 +8,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 @@ -24,7 +25,9 @@ not be used. .Cancelling a stream [source,erlang] +---- gun:cancel(ConnPid, StreamRef). +---- === Sending requests @@ -45,39 +48,43 @@ 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" - [source,erlang] +---- StreamRef = gun:get(ConnPid, "/organizations/ninenines"). +---- .GET "/organizations/ninenines" with custom headers - [source,erlang] +---- 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" - [source,erlang] +---- StreamRef = gun:head(ConnPid, "/organizations/ninenines"). +---- .HEAD "/organizations/ninenines" with custom headers - [source,erlang] +---- 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. @@ -87,7 +94,7 @@ request. 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. @@ -101,7 +108,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,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. @@ -112,12 +119,13 @@ can be replaced by `gun:put` or `gun:patch` for performing a PUT or PATCH request, respectively. .POST "/organizations/ninenines" - [source,erlang] +---- 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 @@ -133,14 +141,15 @@ is not set, HTTP/1.1 will use the chunked transfer-encoding, and HTTP/2 will continue normally as it is chunked by design. .POST "/organizations/ninenines" with delayed body - [source,erlang] +---- 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 be sent. You can call the `gun:data/4` function as many @@ -148,79 +157,82 @@ 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 - [source,erlang] ---- 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" - [source,erlang] +---- StreamRef = gun:delete(ConnPid, "/organizations/ninenines"). +---- .DELETE "/organizations/ninenines" with custom headers - [source,erlang] +---- 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" - [source,erlang] +---- StreamRef = gun:options(ConnPid, "/organizations/ninenines"). +---- .OPTIONS "/organizations/ninenines" with custom headers - [source,erlang] +---- 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. .OPTIONS "*" - [source,erlang] +---- StreamRef = gun:options(ConnPid, "*"). +---- ==== 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. .Example of a TRACE request - [source,erlang] +---- gun:request(ConnPid, "TRACE", "/", [ - {<<"max-forwards">>, "30"} + {<<"max-forwards">>, "30"} ]). +---- === Processing responses @@ -242,36 +254,35 @@ You can receive messages directly, or you can use the _await_ functions to let Gun receive them for you. .Receiving a response using receive - [source,erlang] ---- 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 @@ -283,29 +294,30 @@ 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. .Receiving a response using await - [source,erlang] +---- 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. +---- === Handling streams pushed by the server @@ -323,26 +335,28 @@ The `gun_push` message contains both the new stream reference and the stream reference of the original request. .Receiving a pushed response using receive - [source,erlang] +---- 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. .Receiving a pushed response using await - [source,erlang] -{push, PushedStreamRef, Method, Host, Path, Headers} - = gun:await(ConnPid, OriginalStreamRef). +---- +{push, PushedStreamRef, Method, URI, Headers} + = gun:await(ConnPid, OriginalStreamRef). +---- -The `PushedStreamRef` variable can then be used with `gun:await_body/{2,3,4}` -if needed. +The `PushedStreamRef` variable can then be used with `gun:await/2,3,4` +and `gun:await_body/2,3,4`. === Flushing unwanted messages @@ -352,14 +366,16 @@ can use it to get rid of all messages related to a connection, or just the messages related to a stream. .Flush all messages from a Gun connection - [source,erlang] +---- gun:flush(ConnPid). +---- .Flush all messages from a specific stream - [source,erlang] +---- gun:flush(StreamRef). +---- === Redirecting responses to a different process @@ -367,7 +383,8 @@ 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}). + #{reply_to => Pid}). +---- 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 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: HTTP</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -71,7 +69,7 @@ communicating with an HTTP/1.1 or HTTP/2 server.</p></div> <div class="sectionbody"> <div class="paragraph"><p>Every time a request is initiated, Gun creates a <em>stream</em>. A <em>stream reference</em> 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.</p></div> <div class="paragraph"><p>Stream references use the Erlang <em>reference</em> data type and are therefore unique.</p></div> @@ -107,7 +105,7 @@ header if it has not been provided in the request arguments.</p></div> handling of responses will be explained further on.</p></div> <div class="sect3"> <h4 id="_get_and_head">GET and HEAD</h4> -<div class="paragraph"><p>Use <code>gun:get/{2,3,4}</code> to request a resource.</p></div> +<div class="paragraph"><p>Use <code>gun:get/2,3,4</code> to request a resource.</p></div> <div class="listingblock"> <div class="title">GET "/organizations/ninenines"</div> <div class="content"><!-- Generator: GNU source-highlight @@ -122,13 +120,13 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}, - {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}, + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>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.</p></div> -<div class="paragraph"><p>Use <code>gun:head/{2,3,4}</code> if you don’t need the response body.</p></div> +<div class="paragraph"><p>Use <code>gun:head/2,3,4</code> if you don’t need the response body.</p></div> <div class="listingblock"> <div class="title">HEAD "/organizations/ninenines"</div> <div class="content"><!-- Generator: GNU source-highlight @@ -143,8 +141,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:head</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}, - {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}, + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>It is not possible to send a request body with a GET or HEAD request.</p></div> @@ -153,7 +151,7 @@ request.</p></div> <h4 id="_post_put_and_patch">POST, PUT and PATCH</h4> <div class="paragraph"><p>HTTP defines three methods to create or update a resource.</p></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>PUT creates or replaces a resource identified by the URI.</p></div> @@ -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.</p></div> -<div class="paragraph"><p>The <code>gun:post/{4,5}</code>, <code>gun:put/{4,5}</code> and <code>gun:patch/{4,5}</code> functions +<div class="paragraph"><p>The <code>gun:post/4,5</code>, <code>gun:put/4,5</code> and <code>gun:patch/4,5</code> 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 --> <pre><tt><span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"{\"msg\": \"Hello world!\"}"</span>, <span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:post</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>} ], <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>The <code>gun:post/3</code>, <code>gun:put/3</code> and <code>gun:patch/3</code> 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 --> <pre><tt><span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"{\"msg\": \"Hello world!\"}"</span>, <span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:post</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="font-weight: bold"><span style="color: #000080">length</span></span>(<span style="color: #009900">Body</span>))}, - {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="font-weight: bold"><span style="color: #000080">length</span></span>(<span style="color: #009900">Body</span>))}, + {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>} ]), <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>The atom <code>fin</code> indicates this is the last chunk of data to @@ -209,7 +207,6 @@ be sent. You can call the <code>gun:data/4</code> function as many times as needed until you have sent the entire body. The last call must use <code>fin</code> and all the previous calls must use <code>nofin</code>. The last chunk may be empty.</p></div> -<div class="paragraph"><p>@todo what to do about empty chunk, ignore?</p></div> <div class="listingblock"> <div class="title">Streaming the request body</div> <div class="content"><!-- Generator: GNU source-highlight @@ -217,22 +214,22 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Filepath</span>) <span style="color: #990000">-></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IoDevice</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filepath</span>, [<span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #FF6600">raw</span>]), - <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>)<span style="color: #990000">.</span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IoDevice</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filepath</span>, [<span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #FF6600">raw</span>]), + <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>)<span style="color: #990000">.</span> <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>) <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">file:read</span></span>(<span style="color: #009900">IoDevice</span>, <span style="color: #993399">8000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> - <span style="color: #FF6600">eof</span> <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #990000"><<>></span>), - <span style="font-weight: bold"><span style="color: #000000">file:close</span></span>(<span style="color: #009900">IoDevice</span>); - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Bin</span>), - <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>) - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">file:read</span></span>(<span style="color: #009900">IoDevice</span>, <span style="color: #993399">8000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #FF6600">eof</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #990000"><<>></span>), + <span style="font-weight: bold"><span style="color: #000000">file:close</span></span>(<span style="color: #009900">IoDevice</span>); + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Bin</span>), + <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> </div> <div class="sect3"> <h4 id="_delete">DELETE</h4> -<div class="paragraph"><p>Use <code>gun:delete/{2,3,4}</code> to delete a resource.</p></div> +<div class="paragraph"><p>Use <code>gun:delete/2,3,4</code> to delete a resource.</p></div> <div class="listingblock"> <div class="title">DELETE "/organizations/ninenines"</div> <div class="content"><!-- Generator: GNU source-highlight @@ -247,12 +244,12 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:delete</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> </div> <div class="sect3"> <h4 id="_options">OPTIONS</h4> -<div class="paragraph"><p>Use <code>gun:options/{2,3}</code> to request information about a resource.</p></div> +<div class="paragraph"><p>Use <code>gun:options/2,3</code> to request information about a resource.</p></div> <div class="listingblock"> <div class="title">OPTIONS "/organizations/ninenines"</div> <div class="content"><!-- Generator: GNU source-highlight @@ -267,7 +264,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>You can also use this function to request information about the server itself.</p></div> @@ -281,7 +278,7 @@ http://www.gnu.org/software/src-highlite --> </div> <div class="sect3"> <h4 id="_requests_with_an_arbitrary_method">Requests with an arbitrary method</h4> -<div class="paragraph"><p>The <code>gun:request/{4,5,6}</code> function can be used to send requests +<div class="paragraph"><p>The <code>gun:request/4,5,6</code> 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.</p></div> <div class="listingblock"> @@ -291,7 +288,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:request</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"TRACE"</span>, <span style="color: #FF0000">"/"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"max-forwards"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"30"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"max-forwards"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"30"</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> </div> </div> @@ -319,32 +316,32 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">print_body</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>) <span style="color: #990000">-></span> - <span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/"</span>), - <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="color: #FF6600">no_data</span>; - {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>); - {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>) - <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> + <span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/"</span>), + <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="color: #FF6600">no_data</span>; + {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>); + {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>) <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]), - <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>); - {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]); - {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>) - <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> + <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]), + <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>); + {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]); + {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>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.</p></div> <div class="paragraph"><p>You can also use Gun in a synchronous manner by using the <em>await</em> functions.</p></div> -<div class="paragraph"><p>The <code>gun:await/{2,3,4}</code> function will wait until it receives +<div class="paragraph"><p>The <code>gun:await/2,3,4</code> function will wait until it receives a response to, a pushed resource related to, or data from the given stream.</p></div> -<div class="paragraph"><p>When calling <code>gun:await/{2,3}</code> and not passing a monitor +<div class="paragraph"><p>When calling <code>gun:await/2,3</code> and not passing a monitor reference, one is automatically created for you for the duration of the call.</p></div> -<div class="paragraph"><p>The <code>gun:await_body/{2,3,4}</code> works similarly, but returns the +<div class="paragraph"><p>The <code>gun:await_body/2,3,4</code> works similarly, but returns the body received. Both functions can be combined to receive the response and its body sequentially.</p></div> <div class="listingblock"> @@ -369,11 +366,11 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/"</span>), <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">gun:await</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> - {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="color: #FF6600">no_data</span>; - {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_body</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>), - <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Body</span>]) + {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="color: #FF6600">no_data</span>; + {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_body</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>), + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Body</span>]) <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> </div> </div> @@ -397,11 +394,11 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_push</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>, <span style="color: #009900">PushedStreamRef</span>, - <span style="color: #009900">Method</span>, <span style="color: #009900">Host</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">enjoy</span></span>() + {<span style="color: #FF6600">gun_push</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>, <span style="color: #009900">PushedStreamRef</span>, + <span style="color: #009900">Method</span>, <span style="color: #009900">Host</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">enjoy</span></span>() <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>If you use the <code>gun:await/{2,3,4}</code> function, however, Gun +<div class="paragraph"><p>If you use the <code>gun:await/2,3,4</code> function, however, Gun will use the original reference to identify the message but will return a tuple that doesn’t contain it.</p></div> <div class="listingblock"> @@ -410,10 +407,10 @@ will return a tuple that doesn’t contain it.</p></div> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">push</span>, <span style="color: #009900">PushedStreamRef</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">Host</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>} - <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>The <code>PushedStreamRef</code> variable can then be used with <code>gun:await_body/{2,3,4}</code> -if needed.</p></div> +<pre><tt>{<span style="color: #FF6600">push</span>, <span style="color: #009900">PushedStreamRef</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">URI</span>, <span style="color: #009900">Headers</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>PushedStreamRef</code> variable can then be used with <code>gun:await/2,3,4</code> +and <code>gun:await_body/2,3,4</code>.</p></div> </div> </div> <div class="sect1"> @@ -451,7 +448,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [], - #{<span style="color: #0000FF">reply_to</span> <span style="color: #990000">=></span> <span style="color: #009900">Pid</span>})<span style="color: #990000">.</span></tt></pre></div></div> + #{<span style="color: #0000FF">reply_to</span> <span style="color: #990000">=></span> <span style="color: #009900">Pid</span>})<span style="color: #990000">.</span></tt></pre></div></div> </div> </div> diff --git a/docs/en/gun/1.0/guide/index.html b/docs/en/gun/1.0/guide/index.html index f7e4b26e..cb30dd5b 100644 --- a/docs/en/gun/1.0/guide/index.html +++ b/docs/en/gun/1.0/guide/index.html @@ -7,8 +7,6 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: Gun User Guide</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> diff --git a/docs/en/gun/1.0/guide/introduction.asciidoc b/docs/en/gun/1.0/guide/introduction.asciidoc index f437769a..f7cd9c10 100644 --- a/docs/en/gun/1.0/guide/introduction.asciidoc +++ b/docs/en/gun/1.0/guide/introduction.asciidoc @@ -1,6 +1,9 @@ +[[introduction]] == Introduction -Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket. +Gun is an HTTP client for Erlang/OTP. + +Gun supports the HTTP/2, HTTP/1.1 and Websocket protocols. === Prerequisites @@ -9,12 +12,33 @@ protocols is required in order to read this guide. === Supported platforms -Gun is tested and supported on Linux. +Gun is tested and supported on Linux, FreeBSD, Windows and OSX. + +Gun is developed for Erlang/OTP 19.0 and newer. + +=== License -Gun is developed for Erlang 19+. +Gun uses the ISC License. -Gun may be compiled on earlier Erlang versions with small source code -modifications but there is no guarantee that it will work as intended. +---- +Copyright (c) 2013-2018, Loïc Hoguin <[email protected]> + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +---- + +=== Versioning + +Gun uses http://semver.org/[Semantic Versioning 2.0.0]. === Conventions @@ -26,7 +50,3 @@ to lowercase, and expects your application to provide lowercase header names. The same applies to any other case insensitive value. - -=== Versioning - -Gun uses [Semantic Versioning 2.0.0](http://semver.org/). diff --git a/docs/en/gun/1.0/guide/introduction/index.html b/docs/en/gun/1.0/guide/introduction/index.html index 5a59d78a..6a3ed2e7 100644 --- a/docs/en/gun/1.0/guide/introduction/index.html +++ b/docs/en/gun/1.0/guide/introduction/index.html @@ -7,8 +7,6 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: Introduction</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -64,7 +62,8 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div> +<div class="paragraph"><p>Gun is an HTTP client for Erlang/OTP.</p></div> +<div class="paragraph"><p>Gun supports the HTTP/2, HTTP/1.1 and Websocket protocols.</p></div> <div class="sect1"> <h2 id="_prerequisites">Prerequisites</h2> <div class="sectionbody"> @@ -75,10 +74,36 @@ protocols is required in order to read this guide.</p></div> <div class="sect1"> <h2 id="_supported_platforms">Supported platforms</h2> <div class="sectionbody"> -<div class="paragraph"><p>Gun is tested and supported on Linux.</p></div> -<div class="paragraph"><p>Gun is developed for Erlang 19+.</p></div> -<div class="paragraph"><p>Gun may be compiled on earlier Erlang versions with small source code -modifications but there is no guarantee that it will work as intended.</p></div> +<div class="paragraph"><p>Gun is tested and supported on Linux, FreeBSD, Windows and OSX.</p></div> +<div class="paragraph"><p>Gun is developed for Erlang/OTP 19.0 and newer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_license">License</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun uses the ISC License.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>Copyright (c) 2013-2018, Loïc Hoguin <[email protected]> + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</code></pre> +</div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a>.</p></div> </div> </div> <div class="sect1"> @@ -92,12 +117,6 @@ names.</p></div> <div class="paragraph"><p>The same applies to any other case insensitive value.</p></div> </div> </div> -<div class="sect1"> -<h2 id="_versioning">Versioning</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Gun uses [Semantic Versioning 2.0.0](<a href="http://semver.org/">http://semver.org/</a>).</p></div> -</div> -</div> diff --git a/docs/en/gun/1.0/guide/protocols.asciidoc b/docs/en/gun/1.0/guide/protocols.asciidoc index ae7705ff..2c4fd10e 100644 --- a/docs/en/gun/1.0/guide/protocols.asciidoc +++ b/docs/en/gun/1.0/guide/protocols.asciidoc @@ -1,3 +1,4 @@ +[[protocols]] == Supported protocols This chapter describes the protocols supported and the @@ -10,31 +11,36 @@ 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,6}` for each respective +functions are aliases of `gun:request/4,5,6` for the respective methods. Gun also provides a `gun:data/4` function for streaming the request body. +Gun will send a `gun_inform` message for every intermediate +informational responses received. They will always be sent +before the `gun_response` message. + Gun will send a `gun_response` message for every response received, followed by zero or more `gun_data` messages for -the response body. If something goes wrong, a `gun_error` +the response body, which is optionally terminated by a +`gun_trailers` message. If something goes wrong, a `gun_error` will be sent instead. Gun provides convenience functions for dealing with messages. -The `gun:await/{2,3,4}` function waits for a response to the given -request, and the `gun:await_body/{2,3,4}` function for the -response's body. The `gun:flush/1` function can be used to clear all +The `gun:await/2,3,4` function waits for a response to the given +request, and the `gun:await_body/2,3,4` function for the +response body. The `gun:flush/1` function can be used to clear all messages related to a request or a connection from the mailbox -of the process. +of the calling process. The function `gun:cancel/2` can be used to silence the response to a request previously sent if it is no longer needed. When using HTTP/1.1 there is no multiplexing so Gun will have to receive the response fully before any -other response can be received. +other responses can be received. Finally, Gun can upgrade an HTTP/1.1 connection to Websocket. -It provides the `gun:ws_upgrade/{2,3,4}` function for that -purpose. A `gun_ws_upgrade` message will be sent on success; +It provides the `gun:ws_upgrade/2,3,4` function for that +purpose. A `gun_upgrade` message will be sent on success; a `gun_response` message otherwise. === HTTP/2 @@ -42,25 +48,26 @@ a `gun_response` message otherwise. HTTP/2 is a binary protocol based on HTTP, compatible with the HTTP semantics, that reduces the complexity of parsing requests and responses, compresses the HTTP headers and -allows the server to push multiple responses to a single -request. +allows the server to push additional resources along with +the normal response to the original request. The HTTP/2 interface is very similar to HTTP/1.1, so this section instead focuses on the differences in the interface for the two protocols. -Because a HTTP/2 server can push multiple responses to a -single request, Gun might send `gun_push` messages for -every push received. They can be ignored safely if they -are not needed. +Gun will send `gun_push` messages for every push received. +They will always be sent before the `gun_response` message. +They can be ignored safely if they are not needed, or they +can be canceled. The `gun:cancel/2` function will use the HTTP/2 stream cancellation mechanism which allows Gun to inform the server to stop sending a response for this particular request, saving resources. -It is not possible to upgrade an HTTP/2 connection to Websocket -due to protocol limitations. +It is not currently possible to upgrade an HTTP/2 connection +to Websocket. Support for this will be added in a future +release. === Websocket @@ -110,10 +117,11 @@ current protocol. |=== | Message | HTTP/1.1 | HTTP/2 | Websocket | gun_push | no | yes | no +| gun_inform | yes | yes | no | gun_response | yes | yes | no | gun_data | yes | yes | no -| gun_error (StreamRef) | yes | yes | no +| gun_trailers | yes | yes | no | gun_error | yes | yes | yes -| gun_ws_upgrade | yes | no | no +| gun_upgrade | yes | no | no | gun_ws | no | no | yes |=== diff --git a/docs/en/gun/1.0/guide/protocols/index.html b/docs/en/gun/1.0/guide/protocols/index.html index b94891f0..00d70ad6 100644 --- a/docs/en/gun/1.0/guide/protocols/index.html +++ b/docs/en/gun/1.0/guide/protocols/index.html @@ -7,8 +7,6 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: Supported protocols</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -73,27 +71,31 @@ operations available to them.</p></div> sends a request, the server sends back a response.</p></div> <div class="paragraph"><p>Gun provides convenience functions for performing GET, HEAD, OPTIONS, POST, PATCH, PUT, and DELETE requests. All these -functions are aliases of <code>gun:request/{4,5,6}</code> for each respective +functions are aliases of <code>gun:request/4,5,6</code> for the respective methods. Gun also provides a <code>gun:data/4</code> function for streaming the request body.</p></div> +<div class="paragraph"><p>Gun will send a <code>gun_inform</code> message for every intermediate +informational responses received. They will always be sent +before the <code>gun_response</code> message.</p></div> <div class="paragraph"><p>Gun will send a <code>gun_response</code> message for every response received, followed by zero or more <code>gun_data</code> messages for -the response body. If something goes wrong, a <code>gun_error</code> +the response body, which is optionally terminated by a +<code>gun_trailers</code> message. If something goes wrong, a <code>gun_error</code> will be sent instead.</p></div> <div class="paragraph"><p>Gun provides convenience functions for dealing with messages. -The <code>gun:await/{2,3,4}</code> function waits for a response to the given -request, and the <code>gun:await_body/{2,3,4}</code> function for the -response’s body. The <code>gun:flush/1</code> function can be used to clear all +The <code>gun:await/2,3,4</code> function waits for a response to the given +request, and the <code>gun:await_body/2,3,4</code> function for the +response body. The <code>gun:flush/1</code> function can be used to clear all messages related to a request or a connection from the mailbox -of the process.</p></div> +of the calling process.</p></div> <div class="paragraph"><p>The function <code>gun:cancel/2</code> can be used to silence the response to a request previously sent if it is no longer needed. When using HTTP/1.1 there is no multiplexing so Gun will have to receive the response fully before any -other response can be received.</p></div> +other responses can be received.</p></div> <div class="paragraph"><p>Finally, Gun can upgrade an HTTP/1.1 connection to Websocket. -It provides the <code>gun:ws_upgrade/{2,3,4}</code> function for that -purpose. A <code>gun_ws_upgrade</code> message will be sent on success; +It provides the <code>gun:ws_upgrade/2,3,4</code> function for that +purpose. A <code>gun_upgrade</code> message will be sent on success; a <code>gun_response</code> message otherwise.</p></div> </div> </div> @@ -103,21 +105,22 @@ a <code>gun_response</code> message otherwise.</p></div> <div class="paragraph"><p>HTTP/2 is a binary protocol based on HTTP, compatible with the HTTP semantics, that reduces the complexity of parsing requests and responses, compresses the HTTP headers and -allows the server to push multiple responses to a single -request.</p></div> +allows the server to push additional resources along with +the normal response to the original request.</p></div> <div class="paragraph"><p>The HTTP/2 interface is very similar to HTTP/1.1, so this section instead focuses on the differences in the interface for the two protocols.</p></div> -<div class="paragraph"><p>Because a HTTP/2 server can push multiple responses to a -single request, Gun might send <code>gun_push</code> messages for -every push received. They can be ignored safely if they -are not needed.</p></div> +<div class="paragraph"><p>Gun will send <code>gun_push</code> messages for every push received. +They will always be sent before the <code>gun_response</code> message. +They can be ignored safely if they are not needed, or they +can be canceled.</p></div> <div class="paragraph"><p>The <code>gun:cancel/2</code> function will use the HTTP/2 stream cancellation mechanism which allows Gun to inform the server to stop sending a response for this particular request, saving resources.</p></div> -<div class="paragraph"><p>It is not possible to upgrade an HTTP/2 connection to Websocket -due to protocol limitations.</p></div> +<div class="paragraph"><p>It is not currently possible to upgrade an HTTP/2 connection +to Websocket. Support for this will be added in a future +release.</p></div> </div> </div> <div class="sect1"> @@ -277,6 +280,12 @@ cellspacing="0" cellpadding="4"> <td align="center" valign="top"><p class="table">no</p></td> </tr> <tr> +<td align="left" valign="top"><p class="table">gun_inform</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> <td align="left" valign="top"><p class="table">gun_response</p></td> <td align="center" valign="top"><p class="table">yes</p></td> <td align="center" valign="top"><p class="table">yes</p></td> @@ -289,7 +298,7 @@ cellspacing="0" cellpadding="4"> <td align="center" valign="top"><p class="table">no</p></td> </tr> <tr> -<td align="left" valign="top"><p class="table">gun_error (StreamRef)</p></td> +<td align="left" valign="top"><p class="table">gun_trailers</p></td> <td align="center" valign="top"><p class="table">yes</p></td> <td align="center" valign="top"><p class="table">yes</p></td> <td align="center" valign="top"><p class="table">no</p></td> @@ -301,7 +310,7 @@ cellspacing="0" cellpadding="4"> <td align="center" valign="top"><p class="table">yes</p></td> </tr> <tr> -<td align="left" valign="top"><p class="table">gun_ws_upgrade</p></td> +<td align="left" valign="top"><p class="table">gun_upgrade</p></td> <td align="center" valign="top"><p class="table">yes</p></td> <td align="center" valign="top"><p class="table">no</p></td> <td align="center" valign="top"><p class="table">no</p></td> diff --git a/docs/en/gun/1.0/guide/start.asciidoc b/docs/en/gun/1.0/guide/start.asciidoc index 6d93e2e8..09720dca 100644 --- a/docs/en/gun/1.0/guide/start.asciidoc +++ b/docs/en/gun/1.0/guide/start.asciidoc @@ -1,21 +1,21 @@ +[[start]] == Starting and stopping This chapter describes how to start and stop the Gun application. === Setting up -Before Gun can be used it needs to be in Erlang's `ERL_LIBS` path variable. -If you use `erlang.mk` or a similar build tool, you only need to specify -Gun as a dependency to your application and the tool will take care -of downloading Gun and setting up paths. +Specify Gun as a dependency to your application in your favorite +build tool. -With `erlang.mk` this is done by adding `gun` to the `DEPS` variable +With Erlang.mk this is done by adding `gun` to the `DEPS` variable in your Makefile. -.Adding Gun as an erlang.mk dependency - +.Adding Gun as an Erlang.mk dependency [source,make] +---- DEPS = gun +---- === Starting @@ -23,45 +23,21 @@ Gun is an _OTP application_. It needs to be started before you can use it. .Starting Gun in an Erlang shell - [source,erlang] ---- 1> application:ensure_all_started(gun). -{ok,[ranch,crypto,cowlib,asn1,public_key,ssl,gun]} +{ok,[crypto,cowlib,asn1,public_key,ssl,gun]} ---- === Stopping You can stop Gun using the `application:stop/1` function, however -only Gun will be stopped. This is the equivalent of `application:start/1`. +only Gun will be stopped. This is the reverse of `application:start/1`. The `application_ensure_all_started/1` function has no equivalent for stopping all applications. .Stopping Gun - [source,erlang] +---- application:stop(gun). - -=== Using Gun with releases - -An _OTP release_ starts applications automatically. All you need -to do is to set up your application resource file so that Gun can -be included in the release. The application resource file can be -found in `ebin/your_application.app`, or in `src/your_application.app.src` -if you are using a build tool like `erlang.mk`. - -The key you need to change is the `applications` key. By default -it only includes `kernel` and `stdlib`. You need to add `gun` to -that list. - -.Adding Gun to the application resource file - -[source,erlang] -{applications, [ - kernel, - stdlib, - gun -]} - -Do not put an extra comma at the end, the comma is a separator -between the elements of the list. +---- diff --git a/docs/en/gun/1.0/guide/start/index.html b/docs/en/gun/1.0/guide/start/index.html index d2e8f0aa..6611c3ea 100644 --- a/docs/en/gun/1.0/guide/start/index.html +++ b/docs/en/gun/1.0/guide/start/index.html @@ -7,8 +7,6 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: Starting and stopping</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -68,14 +66,12 @@ <div class="sect1"> <h2 id="_setting_up">Setting up</h2> <div class="sectionbody"> -<div class="paragraph"><p>Before Gun can be used it needs to be in Erlang’s <code>ERL_LIBS</code> path variable. -If you use <code>erlang.mk</code> or a similar build tool, you only need to specify -Gun as a dependency to your application and the tool will take care -of downloading Gun and setting up paths.</p></div> -<div class="paragraph"><p>With <code>erlang.mk</code> this is done by adding <code>gun</code> to the <code>DEPS</code> variable +<div class="paragraph"><p>Specify Gun as a dependency to your application in your favorite +build tool.</p></div> +<div class="paragraph"><p>With Erlang.mk this is done by adding <code>gun</code> to the <code>DEPS</code> variable in your Makefile.</p></div> <div class="listingblock"> -<div class="title">Adding Gun as an erlang.mk dependency</div> +<div class="title">Adding Gun as an Erlang.mk dependency</div> <div class="content"><!-- Generator: GNU source-highlight by Lorenzo Bettini http://www.lorenzobettini.it @@ -95,14 +91,14 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">gun</span>)<span style="color: #990000">.</span> -{<span style="color: #FF6600">ok</span>,[<span style="color: #FF6600">ranch</span>,<span style="color: #FF6600">crypto</span>,<span style="color: #FF6600">cowlib</span>,<span style="color: #FF6600">asn1</span>,<span style="color: #FF6600">public_key</span>,<span style="color: #FF6600">ssl</span>,<span style="color: #FF6600">gun</span>]}</tt></pre></div></div> +{<span style="color: #FF6600">ok</span>,[<span style="color: #FF6600">crypto</span>,<span style="color: #FF6600">cowlib</span>,<span style="color: #FF6600">asn1</span>,<span style="color: #FF6600">public_key</span>,<span style="color: #FF6600">ssl</span>,<span style="color: #FF6600">gun</span>]}</tt></pre></div></div> </div> </div> <div class="sect1"> <h2 id="_stopping">Stopping</h2> <div class="sectionbody"> <div class="paragraph"><p>You can stop Gun using the <code>application:stop/1</code> function, however -only Gun will be stopped. This is the equivalent of <code>application:start/1</code>. +only Gun will be stopped. This is the reverse of <code>application:start/1</code>. The <code>application_ensure_all_started/1</code> function has no equivalent for stopping all applications.</p></div> <div class="listingblock"> @@ -114,32 +110,6 @@ http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">application:stop</span></span>(<span style="color: #FF6600">gun</span>)<span style="color: #990000">.</span></tt></pre></div></div> </div> </div> -<div class="sect1"> -<h2 id="_using_gun_with_releases">Using Gun with releases</h2> -<div class="sectionbody"> -<div class="paragraph"><p>An <em>OTP release</em> starts applications automatically. All you need -to do is to set up your application resource file so that Gun can -be included in the release. The application resource file can be -found in <code>ebin/your_application.app</code>, or in <code>src/your_application.app.src</code> -if you are using a build tool like <code>erlang.mk</code>.</p></div> -<div class="paragraph"><p>The key you need to change is the <code>applications</code> key. By default -it only includes <code>kernel</code> and <code>stdlib</code>. You need to add <code>gun</code> to -that list.</p></div> -<div class="listingblock"> -<div class="title">Adding Gun to the application resource file</div> -<div class="content"><!-- Generator: GNU source-highlight -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">applications</span>, [ - <span style="color: #FF6600">kernel</span>, - <span style="color: #FF6600">stdlib</span>, - <span style="color: #FF6600">gun</span> -]}</tt></pre></div></div> -<div class="paragraph"><p>Do not put an extra comma at the end, the comma is a separator -between the elements of the list.</p></div> -</div> -</div> diff --git a/docs/en/gun/1.0/guide/websocket.asciidoc b/docs/en/gun/1.0/guide/websocket.asciidoc index f99dea70..cf32291f 100644 --- a/docs/en/gun/1.0/guide/websocket.asciidoc +++ b/docs/en/gun/1.0/guide/websocket.asciidoc @@ -1,10 +1,10 @@ +[[websocket]] == Websocket This chapter describes how to use the Gun client for communicating with a Websocket server. -@todo recovering from connection failure -reconnecting to Websocket etc. +// @todo recovering from connection failure, reconnecting to Websocket etc. === HTTP upgrade @@ -14,33 +14,33 @@ HTTP/1.1 connections can be upgraded to Websocket, so you might need to restrict the protocol to HTTP/1.1 if you are planning to use Websocket over TLS. -You must use the `gun_ws:upgrade/{2,3,4}` function to upgrade +You must use the `gun:ws_upgrade/2,3,4` function to upgrade to Websocket. This function can be called anytime after connection, so you can send HTTP requests before upgrading to Websocket. .Upgrade to Websocket - [source,erlang] +---- gun:ws_upgrade(ConnPid, "/websocket"). +---- Gun will set all the necessary headers for performing the Websocket upgrade, but you can specify additional headers if needed. For example you can request a custom sub-protocol. .Upgrade to Websocket and request a protocol - [source,erlang] +---- gun:ws_upgrade(ConnPid, "/websocket", [ - {<<"sec-websocket-protocol">>, "mychat"} + {<<"sec-websocket-protocol">>, "mychat"} ]). +---- -You can pass the Websocket options as part of the `gun:open/{2,3}` +You can pass the Websocket options as part of the `gun:open/2,3` call when opening the connection, or using the `gun:ws_upgrade/4`. -The fourth argument is those same options. This function call -will crash if the options are incorrect, unlike when passing -them through `gun:open/{2,3}`. +The fourth argument is those same options. -When the upgrade succeeds, a `gun_ws_upgrade` message is sent. +When the upgrade succeeds, a `gun_upgrade` message is sent. If the server does not understand Websocket or refused the upgrade, a `gun_response` message is sent. If Gun couldn't perform the upgrade due to an error (for example attempting @@ -52,21 +52,19 @@ a meaningful response which should be processed. In the following example we however ignore it: [source,erlang] +---- receive - {gun_ws_upgrade, ConnPid, ok, Headers} -> - upgrade_success(ConnPid); - {gun_response, ConnPid, _, _, Status, Headers} -> - exit({ws_upgrade_failed, Status, Headers}); - {gun_error, ConnPid, StreamRef, Reason} -> - exit({ws_upgrade_failed, Reason}) - %% More clauses here as needed. + {gun_upgrade, ConnPid, StreamRef, [<<"websocket">>], Headers} -> + upgrade_success(ConnPid, StreamRef); + {gun_response, ConnPid, _, _, Status, Headers} -> + exit({ws_upgrade_failed, Status, Headers}); + {gun_error, ConnPid, StreamRef, Reason} -> + exit({ws_upgrade_failed, Reason}) + %% More clauses here as needed. after 1000 -> - exit(timeout) + 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 @@ -74,27 +72,28 @@ Once the Websocket upgrade has completed successfully, you no longer have access to functions for performing requests. You can only send and receive Websocket messages. -Use `gun:ws_send/2` to send one or more messages to the server. - -@todo Implement sending of N frames +Use `gun:ws_send/2` to send messages to the server. .Send a text frame - [source,erlang] +---- gun:ws_send(ConnPid, {text, "Hello!"}). - -.Send a text frame, a binary frame and then close the connection - -[source,erlang] -gun:ws_send(ConnPid, [ - {text, "Hello!"}, - {binary, BinaryValue}, - close -]). +---- + +// @todo Implement sending of N frames +// +//.Send a text frame, a binary frame and then close the connection +//[source,erlang] +//---- +//gun:ws_send(ConnPid, [ +// {text, "Hello!"}, +// {binary, BinaryValue}, +// close +//]). +//---- Note that if you send a close frame, Gun will close the connection -cleanly and will not attempt to reconnect afterwards, similar to -calling `gun:shutdown/1`. +cleanly and will not attempt to reconnect afterwards. === Receiving data @@ -102,15 +101,17 @@ Gun sends an Erlang message to the owner process for every Websocket message it receives. [source,erlang] +---- receive - {gun_ws, ConnPid, Frame} -> - handle_frame(ConnPid, Frame) + {gun_ws, ConnPid, StreamRef, Frame} -> + handle_frame(ConnPid, StreamRef, Frame) end. - -@todo auto ping has not been implemented yet - -Gun will automatically send ping messages to the server to keep -the connection alive, however if the connection dies and Gun has -to reconnect it will not upgrade to Websocket automatically, you -need to perform the operation when you receive the `gun_error` -message. +---- + +// @todo auto ping has not been implemented yet +// +//Gun will automatically send ping messages to the server to keep +//the connection alive, however if the connection dies and Gun has +//to reconnect it will not upgrade to Websocket automatically, you +//need to perform the operation when you receive the `gun_error` +//message. diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html index b34a290d..a77f1319 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -7,8 +7,6 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: Websocket</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -66,8 +64,6 @@ <div class="paragraph"><p>This chapter describes how to use the Gun client for communicating with a Websocket server.</p></div> -<div class="paragraph"><p>@todo recovering from connection failure -reconnecting to Websocket etc.</p></div> <div class="sect1"> <h2 id="_http_upgrade">HTTP upgrade</h2> <div class="sectionbody"> @@ -76,7 +72,7 @@ you must first request for the connection to be upgraded. Only HTTP/1.1 connections can be upgraded to Websocket, so you might need to restrict the protocol to HTTP/1.1 if you are planning to use Websocket over TLS.</p></div> -<div class="paragraph"><p>You must use the <code>gun_ws:upgrade/{2,3,4}</code> function to upgrade +<div class="paragraph"><p>You must use the <code>gun:ws_upgrade/2,3,4</code> function to upgrade to Websocket. This function can be called anytime after connection, so you can send HTTP requests before upgrading to Websocket.</p></div> <div class="listingblock"> @@ -96,14 +92,12 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"mychat"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"mychat"</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>You can pass the Websocket options as part of the <code>gun:open/{2,3}</code> +<div class="paragraph"><p>You can pass the Websocket options as part of the <code>gun:open/2,3</code> call when opening the connection, or using the <code>gun:ws_upgrade/4</code>. -The fourth argument is those same options. This function call -will crash if the options are incorrect, unlike when passing -them through <code>gun:open/{2,3}</code>.</p></div> -<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_ws_upgrade</code> message is sent. +The fourth argument is those same options.</p></div> +<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_upgrade</code> message is sent. If the server does not understand Websocket or refused the upgrade, a <code>gun_response</code> message is sent. If Gun couldn’t perform the upgrade due to an error (for example attempting @@ -118,19 +112,16 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_ws_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">upgrade_success</span></span>(<span style="color: #009900">ConnPid</span>); - {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>}); - {<span style="color: #FF6600">gun_error</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Reason</span>}) - <span style="font-style: italic"><span style="color: #9A1900">%% More clauses here as needed.</span></span> + {<span style="color: #FF6600">gun_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"websocket"</span><span style="color: #990000">>></span>], <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">upgrade_success</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>); + {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>}); + {<span style="color: #FF6600">gun_error</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Reason</span>}) + <span style="font-style: italic"><span style="color: #9A1900">%% More clauses here as needed.</span></span> <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Note that you shouldn’t use the <code>reply_to</code> request option -for connections you plan to upgrade, because only the -owner of the connection will receive messages about it.</p></div> </div> </div> <div class="sect1"> @@ -139,8 +130,7 @@ owner of the connection will receive messages about it.</p></div> <div class="paragraph"><p>Once the Websocket upgrade has completed successfully, you no longer have access to functions for performing requests. You can only send and receive Websocket messages.</p></div> -<div class="paragraph"><p>Use <code>gun:ws_send/2</code> to send one or more messages to the server.</p></div> -<div class="paragraph"><p>@todo Implement sending of N frames</p></div> +<div class="paragraph"><p>Use <code>gun:ws_send/2</code> to send messages to the server.</p></div> <div class="listingblock"> <div class="title">Send a text frame</div> <div class="content"><!-- Generator: GNU source-highlight @@ -148,20 +138,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>})<span style="color: #990000">.</span></tt></pre></div></div> -<div class="listingblock"> -<div class="title">Send a text frame, a binary frame and then close the connection</div> -<div class="content"><!-- Generator: GNU source-highlight -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, [ - {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>}, - {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">BinaryValue</span>}, - <span style="color: #FF6600">close</span> -])<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>Note that if you send a close frame, Gun will close the connection -cleanly and will not attempt to reconnect afterwards, similar to -calling <code>gun:shutdown/1</code>.</p></div> +cleanly and will not attempt to reconnect afterwards.</p></div> </div> </div> <div class="sect1"> @@ -175,15 +153,9 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_ws</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</span>) + {<span style="color: #FF6600">gun_ws</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Frame</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Frame</span>) <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>@todo auto ping has not been implemented yet</p></div> -<div class="paragraph"><p>Gun will automatically send ping messages to the server to keep -the connection alive, however if the connection dies and Gun has -to reconnect it will not upgrade to Websocket automatically, you -need to perform the operation when you receive the <code>gun_error</code> -message.</p></div> </div> </div> |