diff options
author | Loïc Hoguin <[email protected]> | 2016-03-28 15:36:42 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2016-03-28 15:36:42 +0200 |
commit | fe3492a98de29942477b061cd02c92246f4bf85a (patch) | |
tree | 2255b796a657e6e4dfb72beec1141258d17f1220 /docs/en/gun/1.0/guide | |
download | ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.tar.gz ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.tar.bz2 ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.zip |
Initial commit, new website system
Diffstat (limited to 'docs/en/gun/1.0/guide')
-rw-r--r-- | docs/en/gun/1.0/guide/connect.asciidoc | 154 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/connect/index.html | 302 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/http.asciidoc | 362 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/http/index.html | 515 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/index.html | 172 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/introduction.asciidoc | 28 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/introduction/index.html | 168 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/protocols.asciidoc | 119 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/protocols/index.html | 395 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/start.asciidoc | 67 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/start/index.html | 216 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/websocket.asciidoc | 112 | ||||
-rw-r--r-- | docs/en/gun/1.0/guide/websocket/index.html | 259 |
13 files changed, 2869 insertions, 0 deletions
diff --git a/docs/en/gun/1.0/guide/connect.asciidoc b/docs/en/gun/1.0/guide/connect.asciidoc new file mode 100644 index 00000000..c2e887c1 --- /dev/null +++ b/docs/en/gun/1.0/guide/connect.asciidoc @@ -0,0 +1,154 @@ +== Connection + +This chapter describes how to open, monitor and close +a connection using the Gun client. + +=== Gun connections + +Gun is designed with the SPDY and Websocket protocols in mind. +They are built for long-running connections that allow concurrent +exchange of data, either in the form of request/responses for +SPDY or in the form of messages for Websocket. + +A Gun connection is an Erlang process that manages a socket to +a remote endpoint. This Gun connection is owned by a user +process that is called the _owner_ of the connection, and is +managed by the supervision tree of the `gun` application. + +The owner process communicates with the Gun connection +by calling functions from the module `gun`. All functions +perform their respective operations asynchronously. The Gun +connection will send Erlang messages to the owner process +whenever needed. + +When the remote endpoint closes the connection, Gun attempts +to reconnect automatically. + +=== Opening a new 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 +NPN extension for TLS. By default Gun supports SPDY/3.1, +SPDY/3 and HTTP/1.1 when connecting using SSL. + +For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol. + +The transport and protocol used can be overriden using +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 + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}). + +=== Waiting for the connection to be established + +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 +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. + +The first list indicates open streams that _may_ have been +processed by the server. The second list indicates open +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}` +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}` +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); +end. + +What to do when you receive a `DOWN` message is entirely up to you. + +=== Closing the connection abruptly + +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. diff --git a/docs/en/gun/1.0/guide/connect/index.html b/docs/en/gun/1.0/guide/connect/index.html new file mode 100644 index 00000000..ba463db5 --- /dev/null +++ b/docs/en/gun/1.0/guide/connect/index.html @@ -0,0 +1,302 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.15" /> + + <title>Nine Nines: Connection</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Connection</span></h1> + +<div class="paragraph"><p>This chapter describes how to open, monitor and close
+a connection using the Gun client.</p></div>
+<div class="sect1">
+<h2 id="_gun_connections">Gun connections</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Gun is designed with the SPDY and Websocket protocols in mind.
+They are built for long-running connections that allow concurrent
+exchange of data, either in the form of request/responses for
+SPDY or in the form of messages for Websocket.</p></div>
+<div class="paragraph"><p>A Gun connection is an Erlang process that manages a socket to
+a remote endpoint. This Gun connection is owned by a user
+process that is called the <em>owner</em> of the connection, and is
+managed by the supervision tree of the <code>gun</code> application.</p></div>
+<div class="paragraph"><p>The owner process communicates with the Gun connection
+by calling functions from the module <code>gun</code>. All functions
+perform their respective operations asynchronously. The Gun
+connection will send Erlang messages to the owner process
+whenever needed.</p></div>
+<div class="paragraph"><p>When the remote endpoint closes the connection, Gun attempts
+to reconnect automatically.</p></div>
+</div>
+</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="listingblock">
+<div class="title">Opening a connection to example.org on port 443</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+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">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
+NPN extension for TLS. By default Gun supports SPDY/3.1,
+SPDY/3 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
+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="content"><!-- Generator: GNU source-highlight 3.1.8
+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>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_waiting_for_the_connection_to_be_established">Waiting for the connection to be established</h2>
+<div class="sectionbody">
+<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
+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>
+<div class="listingblock">
+<div class="title">Synchronous opening of a connection</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+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">443</span>),
+{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Protocol</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_up</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_handling_connection_loss">Handling connection loss</h2>
+<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>
+<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>
+</div>
+</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>
+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>
+functions both accept a monitor argument if you have one already.</p></div>
+<div class="listingblock">
+<div class="title">Monitoring the connection process</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+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">443</span>)<span style="color: #990000">.</span>
+<span style="color: #009900">MRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">monitor</span></span>(<span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>This monitor reference can be kept and used until the connection
+process exits.</p></div>
+<div class="listingblock">
+<div class="title">Handling <code>DOWN</code> messages</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: #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-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>
+</div>
+<div class="sect1">
+<h2 id="_closing_the_connection_abruptly">Closing the connection abruptly</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The connection can be stopped abruptly at any time by calling
+the <code>gun:close/1</code> function.</p></div>
+<div class="listingblock">
+<div class="title">Immediate closing of the connection</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:close</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The process is stopped immediately without having a chance to
+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 3.1.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: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>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 1.0 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/1.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/gun/1.0/guide/http.asciidoc b/docs/en/gun/1.0/guide/http.asciidoc new file mode 100644 index 00000000..465a4c53 --- /dev/null +++ b/docs/en/gun/1.0/guide/http.asciidoc @@ -0,0 +1,362 @@ +== HTTP + +This chapter describes how to use the Gun client for +communicating with an HTTP/1.1 or SPDY server. + +=== Streams + +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 +with a stream or to identify its messages. + +Stream references use the Erlang _reference_ data type and +are therefore unique. + +Streams can be canceled at any time. This will stop any further +messages from being sent to the owner process. Depending on +its capabilities, the server will also be instructed to cancel +the request. + +Canceling a stream may result in Gun dropping the connection +temporarily, to avoid uploading or downloading data that will +not be used. + +.Cancelling a stream +[source,erlang] +gun:cancel(ConnPid, StreamRef). + +=== Sending requests + +Gun provides many convenient functions for performing common +operations, like GET, POST or DELETE. It also provides a +general purpose function in case you need other methods. + +The availability of these methods on the server can vary +depending on the software used but also on a per-resource +basis. + +Gun will automatically set a few headers depending on the +method used. For all methods however it will set the host +header if it has not been provided in the request arguments. + +This section focuses on the act of sending a request. The +handling of responses will be explained further on. + +==== GET and HEAD + +Use `gun:get/{2,3}` 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"} +]). + +Note that the list of headers has the field name as a binary. +The field value is iodata, which is either a binary or an +iolist. + +Use `gun:head/{2,3}` if you don't need the response body. + +.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"} +]). + +It is not possible to send a request body with a GET or HEAD +request. + +==== POST, PUT and PATCH + +HTTP defines three methods to create or update a resource. + +POST is generally used when the resource identifier (URI) isn't known +in advance when creating the resource. POST can also be used to +replace an existing resource, although PUT is more appropriate +in that situation. + +PUT creates or replaces a resource identified by the URI. + +PATCH provides instructions on how to modify the resource. + +Both POST and PUT send the entire resource representation in their +request body. The PATCH method can be used when this is not +desirable. The request body of a PATCH method may be a partial +representation or a list of instructions on how to update the +resource. + +The `gun:post/4`, `gun:put/4` and `gun:patch/4` 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. +Gun will set the other headers automatically. + +In this and the following examples in this section, `gun:post` +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"} +], 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 +provided later on, using the `gun:data/4` function, then +the request headers must indicate this. This can be done +by setting the content-length or content-type request +headers. If these headers are not set then Gun will assume +the request has no body. + +It is recommended to send the content-length header if you +know it in advance, although this is not required. If it +is not set, HTTP/1.1 will use the chunked transfer-encoding, +and SPDY 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"} +]), +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 +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). + +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. +---- + +==== DELETE + +Use `gun:delete/{2,3}` 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"} +]). + +==== OPTIONS + +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"} +]). + +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}` 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"} +]). + +=== Processing responses + +All data received from the server is sent to the owner +process as a message. First a `gun_response` message is sent, +followed by zero or more `gun_data` messages. If something goes wrong, +a `gun_error` message is sent instead. + +The response message will inform you whether there will be +data messages following. If it contains `fin` there will be +no data messages. If it contains `nofin` then one or more data +messages will follow. + +When using SPDY this value is sent with the frame and simply +passed on in the message. When using HTTP/1.1 however Gun must +guess whether data will follow by looking at the response headers. + +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. + +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. +---- + +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 +one connection and concurrently perform queries on all of them +at the same time. + +You can also use Gun in a synchronous manner by using the _await_ +functions. + +The `gun:await/{2,3,4}` function will wait until it receives +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 +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 +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]) +end. + +=== Handling streams pushed by the server + +The SPDY protocol allows the server to push more than one +resource for every request. It will start sending those +extra resources before it starts sending the response itself, +so Gun will send you `gun_push` messages before `gun_response` +when that happens. + +You can safely choose to ignore `gun_push` messages, or +you can handle them. If you do, you can either receive the +messages directly or use _await_ functions. + +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() +end. + +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). + +The `PushedStreamRef` variable can then be used with `gun:await_body/{2,3,4}` +if needed. + +=== Flushing unwanted messages + +Gun provides the function `gun:flush/1` to quickly get rid +of unwanted messages sitting in the process mailbox. You +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). diff --git a/docs/en/gun/1.0/guide/http/index.html b/docs/en/gun/1.0/guide/http/index.html new file mode 100644 index 00000000..6934835d --- /dev/null +++ b/docs/en/gun/1.0/guide/http/index.html @@ -0,0 +1,515 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.15" /> + + <title>Nine Nines: HTTP</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>HTTP</span></h1> + +<div class="paragraph"><p>This chapter describes how to use the Gun client for
+communicating with an HTTP/1.1 or SPDY server.</p></div>
+<div class="sect1">
+<h2 id="_streams">Streams</h2>
+<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
+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>
+<div class="paragraph"><p>Streams can be canceled at any time. This will stop any further
+messages from being sent to the owner process. Depending on
+its capabilities, the server will also be instructed to cancel
+the request.</p></div>
+<div class="paragraph"><p>Canceling a stream may result in Gun dropping the connection
+temporarily, to avoid uploading or downloading data that will
+not be used.</p></div>
+<div class="listingblock">
+<div class="title">Cancelling a stream</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:cancel</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_sending_requests">Sending requests</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Gun provides many convenient functions for performing common
+operations, like GET, POST or DELETE. It also provides a
+general purpose function in case you need other methods.</p></div>
+<div class="paragraph"><p>The availability of these methods on the server can vary
+depending on the software used but also on a per-resource
+basis.</p></div>
+<div class="paragraph"><p>Gun will automatically set a few headers depending on the
+method used. For all methods however it will set the host
+header if it has not been provided in the request arguments.</p></div>
+<div class="paragraph"><p>This section focuses on the act of sending a request. The
+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}</code> to request a resource.</p></div>
+<div class="listingblock">
+<div class="title">GET "/organizations/ninenines"</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="listingblock">
+<div class="title">GET "/organizations/ninenines" with custom headers</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: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></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}</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 3.1.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></tt></pre></div></div>
+<div class="listingblock">
+<div class="title">HEAD "/organizations/ninenines" with custom headers</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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></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>
+</div>
+<div class="sect3">
+<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
+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>
+<div class="paragraph"><p>PATCH provides instructions on how to modify the resource.</p></div>
+<div class="paragraph"><p>Both POST and PUT send the entire resource representation in their
+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</code>, <code>gun:put/4</code> and <code>gun:patch/4</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.
+Gun will set the other headers automatically.</p></div>
+<div class="paragraph"><p>In this and the following examples in this section, <code>gun:post</code>
+can be replaced by <code>gun:put</code> or <code>gun:patch</code> for performing
+a PUT or PATCH request, respectively.</p></div>
+<div class="listingblock">
+<div class="title">POST "/organizations/ninenines"</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+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: #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
+provided later on, using the <code>gun:data/4</code> function, then
+the request headers must indicate this. This can be done
+by setting the content-length or content-type request
+headers. If these headers are not set then Gun will assume
+the request has no body.</p></div>
+<div class="paragraph"><p>It is recommended to send the content-length header if you
+know it in advance, although this is not required. If it
+is not set, HTTP/1.1 will use the chunked transfer-encoding,
+and SPDY will continue normally as it is chunked by design.</p></div>
+<div class="listingblock">
+<div class="title">POST "/organizations/ninenines" with delayed body</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+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="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
+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 3.1.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">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="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>
+</div>
+<div class="sect3">
+<h4 id="_delete">DELETE</h4>
+<div class="paragraph"><p>Use <code>gun:delete/{2,3}</code> to delete a resource.</p></div>
+<div class="listingblock">
+<div class="title">DELETE "/organizations/ninenines"</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:delete</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="listingblock">
+<div class="title">DELETE "/organizations/ninenines" with custom headers</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: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></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="listingblock">
+<div class="title">OPTIONS "/organizations/ninenines"</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="listingblock">
+<div class="title">OPTIONS "/organizations/ninenines" with custom headers</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: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></tt></pre></div></div>
+<div class="paragraph"><p>You can also use this function to request information about
+the server itself.</p></div>
+<div class="listingblock">
+<div class="title">OPTIONS "*"</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"*"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</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}</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">
+<div class="title">Example of a TRACE request</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: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></tt></pre></div></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_processing_responses">Processing responses</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>All data received from the server is sent to the owner
+process as a message. First a <code>gun_response</code> message is sent,
+followed by zero or more <code>gun_data</code> messages. If something goes wrong,
+a <code>gun_error</code> message is sent instead.</p></div>
+<div class="paragraph"><p>The response message will inform you whether there will be
+data messages following. If it contains <code>fin</code> there will be
+no data messages. If it contains <code>nofin</code> then one or more data
+messages will follow.</p></div>
+<div class="paragraph"><p>When using SPDY this value is sent with the frame and simply
+passed on in the message. When using HTTP/1.1 however Gun must
+guess whether data will follow by looking at the response headers.</p></div>
+<div class="paragraph"><p>You can receive messages directly, or you can use the <em>await</em>
+functions to let Gun receive them for you.</p></div>
+<div class="listingblock">
+<div class="title">Receiving a response using receive</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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">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="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>
+<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
+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
+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
+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
+body received. Both functions can be combined to receive the
+response and its body sequentially.</p></div>
+<div class="listingblock">
+<div class="title">Receiving a response using await</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: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="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_handling_streams_pushed_by_the_server">Handling streams pushed by the server</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The SPDY protocol allows the server to push more than one
+resource for every request. It will start sending those
+extra resources before it starts sending the response itself,
+so Gun will send you <code>gun_push</code> messages before <code>gun_response</code>
+when that happens.</p></div>
+<div class="paragraph"><p>You can safely choose to ignore <code>gun_push</code> messages, or
+you can handle them. If you do, you can either receive the
+messages directly or use <em>await</em> functions.</p></div>
+<div class="paragraph"><p>The <code>gun_push</code> message contains both the new stream reference
+and the stream reference of the original request.</p></div>
+<div class="listingblock">
+<div class="title">Receiving a pushed response using receive</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: #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="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
+will use the original reference to identify the message but
+will return a tuple that doesn’t contain it.</p></div>
+<div class="listingblock">
+<div class="title">Receiving a pushed response using await</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+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>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_flushing_unwanted_messages">Flushing unwanted messages</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Gun provides the function <code>gun:flush/1</code> to quickly get rid
+of unwanted messages sitting in the process mailbox. You
+can use it to get rid of all messages related to a connection,
+or just the messages related to a stream.</p></div>
+<div class="listingblock">
+<div class="title">Flush all messages from a Gun connection</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:flush</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="listingblock">
+<div class="title">Flush all messages from a specific stream</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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:flush</span></span>(<span style="color: #009900">StreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 1.0 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/1.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/gun/1.0/guide/index.html b/docs/en/gun/1.0/guide/index.html new file mode 100644 index 00000000..bc2b9831 --- /dev/null +++ b/docs/en/gun/1.0/guide/index.html @@ -0,0 +1,172 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.15" /> + + <title>Nine Nines: Gun User Guide</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Gun User Guide</span></h1> + +<div class="ulist"><ul>
+<li>
+<p>
+<a href="introduction/">Introduction</a>
+</p>
+</li>
+<li>
+<p>
+<a href="start/">Starting and stopping</a>
+</p>
+</li>
+<li>
+<p>
+<a href="protocols/">Supported protocols</a>
+</p>
+</li>
+<li>
+<p>
+<a href="connect/">Connection</a>
+</p>
+</li>
+<li>
+<p>
+<a href="http/">Using HTTP</a>
+</p>
+</li>
+<li>
+<p>
+<a href="websocket/">Using Websocket</a>
+</p>
+</li>
+</ul></div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 1.0 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/1.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/gun/1.0/guide/introduction.asciidoc b/docs/en/gun/1.0/guide/introduction.asciidoc new file mode 100644 index 00000000..81a7c7f4 --- /dev/null +++ b/docs/en/gun/1.0/guide/introduction.asciidoc @@ -0,0 +1,28 @@ +== Introduction + +Gun is an Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket. + +=== Prerequisites + +Knowledge of Erlang, but also of the HTTP/1.1, SPDY and Websocket +protocols is required in order to read this guide. + +=== Supported platforms + +Gun is tested and supported on Linux. + +Gun is developed for Erlang 18+. + +Gun may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as intended. + +=== Conventions + +In the HTTP protocol, the method name is case sensitive. All standard +method names are uppercase. + +Header names are case insensitive. Gun converts all the header names +to lowercase, and expects your application to provide lowercase header +names. + +The same applies to any other case insensitive value. diff --git a/docs/en/gun/1.0/guide/introduction/index.html b/docs/en/gun/1.0/guide/introduction/index.html new file mode 100644 index 00000000..c8f85e5b --- /dev/null +++ b/docs/en/gun/1.0/guide/introduction/index.html @@ -0,0 +1,168 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.15" /> + + <title>Nine Nines: Introduction</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Introduction</span></h1> + +<div class="paragraph"><p>Gun is an Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket.</p></div>
+<div class="sect1">
+<h2 id="_prerequisites">Prerequisites</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Knowledge of Erlang, but also of the HTTP/1.1, SPDY and Websocket
+protocols is required in order to read this guide.</p></div>
+</div>
+</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 18+.</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>
+</div>
+<div class="sect1">
+<h2 id="_conventions">Conventions</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>In the HTTP protocol, the method name is case sensitive. All standard
+method names are uppercase.</p></div>
+<div class="paragraph"><p>Header names are case insensitive. Gun converts all the header names
+to lowercase, and expects your application to provide lowercase header
+names.</p></div>
+<div class="paragraph"><p>The same applies to any other case insensitive value.</p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 1.0 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/1.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/gun/1.0/guide/protocols.asciidoc b/docs/en/gun/1.0/guide/protocols.asciidoc new file mode 100644 index 00000000..2180c5b4 --- /dev/null +++ b/docs/en/gun/1.0/guide/protocols.asciidoc @@ -0,0 +1,119 @@ +== Supported protocols + +This chapter describes the protocols supported and the +operations available to them. + +=== HTTP/1.1 + +HTTP/1.1 is a text request-response protocol. The client +sends a request, the server sends back a response. + +Gun provides convenience functions for performing GET, HEAD, +OPTIONS, POST, PATCH, PUT, and DELETE requests. All these +functions are aliases of `gun:request/{4,5}` for each respective +methods. Gun also provides a `gun:data/4` function for streaming +the request body. + +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` +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 +messages related to a request or a connection from the mailbox +of the 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. + +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; +a `gun_response` message otherwise. + +=== SPDY + +SPDY 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. + +The SPDY 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 SPDY 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. + +The `gun:cancel/2` function will use the SPDY 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 a SPDY connection to Websocket +due to protocol limitations. + +=== Websocket + +Websocket is a binary protocol built on top of HTTP that +allows asynchronous concurrent communication between the +client and the server. A Websocket server can push data to +the client at any time. + +Websocket is only available as a connection upgrade over +an HTTP/1.1 connection. + +Once the Websocket connection is established, the only +operation available on this connection is sending Websocket +frames using `gun:ws_send/2`. + +Gun will send a `gun_ws` message for every frame received. + +=== Summary + +The two following tables summarize the supported operations +and the messages Gun sends depending on the connection's +current protocol. + +.Supported operations per protocol +[cols="<,3*^",options="header"] +|=== +| Operation | HTTP/1.1 | SPDY | Websocket +| delete | yes | yes | no +| get | yes | yes | no +| head | yes | yes | no +| options | yes | yes | no +| patch | yes | yes | no +| post | yes | yes | no +| put | yes | yes | no +| request | yes | yes | no +| data | yes | yes | no +| await | yes | yes | no +| await_body | yes | yes | no +| flush | yes | yes | no +| cancel | yes | yes | no +| ws_upgrade | yes | no | no +| ws_send | no | no | yes +|=== + +.Messages sent per protocol +[cols="<,3*^",options="header"] +|=== +| Message | HTTP/1.1 | SPDY | Websocket +| gun_push | no | yes | no +| gun_response | yes | yes | no +| gun_data | yes | yes | no +| gun_error (StreamRef) | yes | yes | no +| gun_error | yes | yes | yes +| gun_ws_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 new file mode 100644 index 00000000..ed694fce --- /dev/null +++ b/docs/en/gun/1.0/guide/protocols/index.html @@ -0,0 +1,395 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.15" /> + + <title>Nine Nines: Supported protocols</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Supported protocols</span></h1> + +<div class="paragraph"><p>This chapter describes the protocols supported and the
+operations available to them.</p></div>
+<div class="sect1">
+<h2 id="_http_1_1">HTTP/1.1</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>HTTP/1.1 is a text request-response protocol. The client
+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}</code> for each 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_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>
+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
+messages related to a request or a connection from the mailbox
+of the 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>
+<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;
+a <code>gun_response</code> message otherwise.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_spdy">SPDY</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>SPDY 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>
+<div class="paragraph"><p>The SPDY 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 SPDY 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>The <code>gun:cancel/2</code> function will use the SPDY 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 a SPDY connection to Websocket
+due to protocol limitations.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_websocket">Websocket</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Websocket is a binary protocol built on top of HTTP that
+allows asynchronous concurrent communication between the
+client and the server. A Websocket server can push data to
+the client at any time.</p></div>
+<div class="paragraph"><p>Websocket is only available as a connection upgrade over
+an HTTP/1.1 connection.</p></div>
+<div class="paragraph"><p>Once the Websocket connection is established, the only
+operation available on this connection is sending Websocket
+frames using <code>gun:ws_send/2</code>.</p></div>
+<div class="paragraph"><p>Gun will send a <code>gun_ws</code> message for every frame received.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_summary">Summary</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The two following tables summarize the supported operations
+and the messages Gun sends depending on the connection’s
+current protocol.</p></div>
+<div class="tableblock">
+<table rules="all"
+width="100%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<caption class="title">Table 1. Supported operations per protocol</caption>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<thead>
+<tr>
+<th align="left" valign="top"> Operation </th>
+<th align="center" valign="top"> HTTP/1.1 </th>
+<th align="center" valign="top"> SPDY </th>
+<th align="center" valign="top"> Websocket</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table">delete</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">get</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">head</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">options</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">patch</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">post</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">put</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">request</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">data</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">await</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">await_body</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">flush</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">cancel</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">ws_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>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">ws_send</p></td>
+<td align="center" valign="top"><p class="table">no</p></td>
+<td align="center" valign="top"><p class="table">no</p></td>
+<td align="center" valign="top"><p class="table">yes</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="tableblock">
+<table rules="all"
+width="100%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<caption class="title">Table 2. Messages sent per protocol</caption>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<thead>
+<tr>
+<th align="left" valign="top"> Message </th>
+<th align="center" valign="top"> HTTP/1.1 </th>
+<th align="center" valign="top"> SPDY </th>
+<th align="center" valign="top"> Websocket</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table">gun_push</p></td>
+<td align="center" valign="top"><p class="table">no</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>
+<td align="center" valign="top"><p class="table">no</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">gun_data</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_error (StreamRef)</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_error</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">yes</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">gun_ws_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>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">gun_ws</p></td>
+<td align="center" valign="top"><p class="table">no</p></td>
+<td align="center" valign="top"><p class="table">no</p></td>
+<td align="center" valign="top"><p class="table">yes</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 1.0 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/1.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/gun/1.0/guide/start.asciidoc b/docs/en/gun/1.0/guide/start.asciidoc new file mode 100644 index 00000000..6d93e2e8 --- /dev/null +++ b/docs/en/gun/1.0/guide/start.asciidoc @@ -0,0 +1,67 @@ +== 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. + +With `erlang.mk` this is done by adding `gun` to the `DEPS` variable +in your Makefile. + +.Adding Gun as an erlang.mk dependency + +[source,make] +DEPS = gun + +=== Starting + +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]} +---- + +=== 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`. +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 new file mode 100644 index 00000000..d8b8cc96 --- /dev/null +++ b/docs/en/gun/1.0/guide/start/index.html @@ -0,0 +1,216 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.15" /> + + <title>Nine Nines: Starting and stopping</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Starting and stopping</span></h1> + +<div class="paragraph"><p>This chapter describes how to start and stop the Gun application.</p></div>
+<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
+in your Makefile.</p></div>
+<div class="listingblock">
+<div class="title">Adding Gun as an erlang.mk dependency</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">DEPS =</span> gun</tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_starting">Starting</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Gun is an <em>OTP application</em>. It needs to be started before you can
+use it.</p></div>
+<div class="listingblock">
+<div class="title">Starting Gun in an Erlang shell</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+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>
+</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>.
+The <code>application_ensure_all_started/1</code> function has no equivalent for
+stopping all applications.</p></div>
+<div class="listingblock">
+<div class="title">Stopping Gun</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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">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 3.1.8
+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>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 1.0 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/1.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/gun/1.0/guide/websocket.asciidoc b/docs/en/gun/1.0/guide/websocket.asciidoc new file mode 100644 index 00000000..4869a2e4 --- /dev/null +++ b/docs/en/gun/1.0/guide/websocket.asciidoc @@ -0,0 +1,112 @@ +== 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. + +=== HTTP upgrade + +Websocket is a protocol built on top of HTTP. To use Websocket, +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. + +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"} +]). + +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}`. + +When the upgrade succeeds, a `gun_ws_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 +to upgrade to Websocket on an HTTP/1.0 connection) then a +`gun_error` message is sent. + +When the server does not understand Websocket, it may send +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. +after 1000 -> + exit(timeout) +end. + +=== Sending data + +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 + +.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 +]). + +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`. + +=== Receiving data + +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) +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. diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html new file mode 100644 index 00000000..78a34d42 --- /dev/null +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -0,0 +1,259 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.15" /> + + <title>Nine Nines: Websocket</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Websocket</span></h1> + +<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">
+<div class="paragraph"><p>Websocket is a protocol built on top of HTTP. To use Websocket,
+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
+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">
+<div class="title">Upgrade to Websocket</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="listingblock">
+<div class="title">Upgrade to Websocket and request a protocol</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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_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></tt></pre></div></div>
+<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.
+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
+to upgrade to Websocket on an HTTP/1.0 connection) then a
+<code>gun_error</code> message is sent.</p></div>
+<div class="paragraph"><p>When the server does not understand Websocket, it may send
+a meaningful response which should be processed. In the
+following example we however ignore it:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: #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="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>
+</div>
+<div class="sect1">
+<h2 id="_sending_data">Sending data</h2>
+<div class="sectionbody">
+<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="listingblock">
+<div class="title">Send a text frame</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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 3.1.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="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>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_receiving_data">Receiving data</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Gun sends an Erlang message to the owner process for every
+Websocket message it receives.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.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: #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="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>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Gun + 1.0 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/gun/1.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/gun/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + |