diff options
Diffstat (limited to 'docs/en')
185 files changed, 27976 insertions, 26232 deletions
diff --git a/docs/en/cowboy/1.0/index.html b/docs/en/cowboy/1.0/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/1.0/index.html +++ b/docs/en/cowboy/1.0/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/2.0/guide/constraints/index.html b/docs/en/cowboy/2.0/guide/constraints/index.html index 110adf07..570f49fe 100644 --- a/docs/en/cowboy/2.0/guide/constraints/index.html +++ b/docs/en/cowboy/2.0/guide/constraints/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Constraints</title> @@ -67,147 +67,150 @@ <h1 class="lined-header"><span>Constraints</span></h1> -<div class="paragraph"><p>Constraints are validation and conversion functions applied
-to user input.</p></div>
-<div class="paragraph"><p>They are used in various places in Cowboy, including the
-router and the <code>cowboy_req</code> match functions.</p></div>
-<div class="sect1">
-<h2 id="_syntax">Syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Constraints are provided as a list of fields. For each field
-in the list, specific constraints can be applied, as well as
-a default value if the field is missing.</p></div>
-<div class="paragraph"><p>A field can take the form of an atom <code>field</code>, a tuple with
-constraints <code>{field, Constraints}</code> or a tuple with constraints
-and a default value <code>{field, Constraints, Default}</code>.
-The <code>field</code> form indicates the field is mandatory.</p></div>
-<div class="paragraph"><p>Note that when used with the router, only the second form
-makes sense, as it does not use the default and the field
-is always defined.</p></div>
-<div class="paragraph"><p>Constraints for each field are provided as an ordered list
-of atoms or funs to apply. Built-in constraints are provided
-as atoms, while custom constraints are provided as funs.</p></div>
-<div class="paragraph"><p>When multiple constraints are provided, they are applied in
-the order given. If the value has been modified by a constraint
-then the next one receives the new value.</p></div>
-<div class="paragraph"><p>For example, the following constraints will first validate
-and convert the field <code>my_value</code> to an integer, and then
-check that the integer is positive:</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="color: #009900">PositiveFun</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>
- (<span style="color: #990000">_</span>, <span style="color: #009900">V</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">V</span> <span style="color: #990000">></span> <span style="color: #993399">0</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">V</span>};
- (<span style="color: #990000">_</span>, <span style="color: #990000">_</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_positive</span>}
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,
-{<span style="color: #FF6600">my_value</span>, [<span style="color: #FF6600">int</span>, <span style="color: #009900">PositiveFun</span>]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>We ignore the first fun argument in this snippet. We shouldn’t.
-We will simply learn what it is later in this chapter.</p></div>
-<div class="paragraph"><p>When there’s only one constraint, it can be provided directly
-without wrapping it into a list:</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="color: #FF6600">my_value</span>, <span style="color: #FF6600">int</span>}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_built_in_constraints">Built-in constraints</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Built-in constraints are specified as an atom:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Constraint </th>
-<th align="left" valign="top"> Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">int</p></td>
-<td align="left" valign="top"><p class="table">Converts binary value to integer.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">nonempty</p></td>
-<td align="left" valign="top"><p class="table">Ensures the binary value is non-empty.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_custom_constraints">Custom constraints</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Custom constraints are specified as a fun. This fun takes
-two arguments. The first argument indicates the operation
-to be performed, and the second is the value. What the
-value is and what must be returned depends on the operation.</p></div>
-<div class="paragraph"><p>Cowboy currently defines three operations. The operation
-used for validating and converting user input is the <code>forward</code>
-operation.</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: #000000">int</span></span>(<span style="color: #FF6600">forward</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">try</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">binary_to_integer</span></span>(<span style="color: #009900">Value</span>)}
- <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div>
-<div class="paragraph"><p>The value must be returned even if it is not converted
-by the constraint.</p></div>
-<div class="paragraph"><p>The <code>reverse</code> operation does the opposite: it
-takes a converted value and changes it back to what the
-user input would have been.</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: #000000">int</span></span>(<span style="color: #FF6600">reverse</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">try</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="color: #009900">Value</span>)}
- <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div>
-<div class="paragraph"><p>Finally, the <code>format_error</code> operation takes an error
-returned by any other operation and returns a formatted
-human-readable error message.</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: #000000">int</span></span>(<span style="color: #FF6600">format_error</span>, {<span style="color: #FF6600">not_an_integer</span>, <span style="color: #009900">Value</span>}) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"The value ~p is not an integer."</span>, [<span style="color: #009900">Value</span>])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Notice that for this case you get both the error and
-the value that was given to the constraint that produced
-this error.</p></div>
-<div class="paragraph"><p>Cowboy will not catch exceptions coming from constraint
-functions. They should be written to not emit any exceptions.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Constraints are validation and conversion functions applied +to user input.</p></div> +<div class="paragraph"><p>They are used in various places in Cowboy, including the +router and the <code>cowboy_req</code> match functions.</p></div> +<div class="sect1"> +<h2 id="_syntax">Syntax</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Constraints are provided as a list of fields. For each field +in the list, specific constraints can be applied, as well as +a default value if the field is missing.</p></div> +<div class="paragraph"><p>A field can take the form of an atom <code>field</code>, a tuple with +constraints <code>{field, Constraints}</code> or a tuple with constraints +and a default value <code>{field, Constraints, Default}</code>. +The <code>field</code> form indicates the field is mandatory.</p></div> +<div class="paragraph"><p>Note that when used with the router, only the second form +makes sense, as it does not use the default and the field +is always defined.</p></div> +<div class="paragraph"><p>Constraints for each field are provided as an ordered list +of atoms or funs to apply. Built-in constraints are provided +as atoms, while custom constraints are provided as funs.</p></div> +<div class="paragraph"><p>When multiple constraints are provided, they are applied in +the order given. If the value has been modified by a constraint +then the next one receives the new value.</p></div> +<div class="paragraph"><p>For example, the following constraints will first validate +and convert the field <code>my_value</code> to an integer, and then +check that the integer is positive:</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="color: #009900">PositiveFun</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> + (<span style="color: #990000">_</span>, <span style="color: #009900">V</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">V</span> <span style="color: #990000">></span> <span style="color: #993399">0</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">V</span>}; + (<span style="color: #990000">_</span>, <span style="color: #990000">_</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_positive</span>} +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>, +{<span style="color: #FF6600">my_value</span>, [<span style="color: #FF6600">int</span>, <span style="color: #009900">PositiveFun</span>]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>We ignore the first fun argument in this snippet. We shouldn’t. +We will simply learn what it is later in this chapter.</p></div> +<div class="paragraph"><p>When there’s only one constraint, it can be provided directly +without wrapping it into a list:</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="color: #FF6600">my_value</span>, <span style="color: #FF6600">int</span>}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_built_in_constraints">Built-in constraints</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Built-in constraints are specified as an atom:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Constraint </th> +<th align="left" valign="top"> Description</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">int</p></td> +<td align="left" valign="top"><p class="table">Converts binary value to integer.</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">nonempty</p></td> +<td align="left" valign="top"><p class="table">Ensures the binary value is non-empty.</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_custom_constraints">Custom constraints</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Custom constraints are specified as a fun. This fun takes +two arguments. The first argument indicates the operation +to be performed, and the second is the value. What the +value is and what must be returned depends on the operation.</p></div> +<div class="paragraph"><p>Cowboy currently defines three operations. The operation +used for validating and converting user input is the <code>forward</code> +operation.</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: #000000">int</span></span>(<span style="color: #FF6600">forward</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">try</span></span> + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">binary_to_integer</span></span>(<span style="color: #009900">Value</span>)} + <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div> +<div class="paragraph"><p>The value must be returned even if it is not converted +by the constraint.</p></div> +<div class="paragraph"><p>The <code>reverse</code> operation does the opposite: it +takes a converted value and changes it back to what the +user input would have been.</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: #000000">int</span></span>(<span style="color: #FF6600">reverse</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">try</span></span> + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="color: #009900">Value</span>)} + <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div> +<div class="paragraph"><p>Finally, the <code>format_error</code> operation takes an error +returned by any other operation and returns a formatted +human-readable error message.</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: #000000">int</span></span>(<span style="color: #FF6600">format_error</span>, {<span style="color: #FF6600">not_an_integer</span>, <span style="color: #009900">Value</span>}) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"The value ~p is not an integer."</span>, [<span style="color: #009900">Value</span>])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Notice that for this case you get both the error and +the value that was given to the constraint that produced +this error.</p></div> +<div class="paragraph"><p>Cowboy will not catch exceptions coming from constraint +functions. They should be written to not emit any exceptions.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/cookies/index.html b/docs/en/cowboy/2.0/guide/cookies/index.html index c81cc17c..fe40ca87 100644 --- a/docs/en/cowboy/2.0/guide/cookies/index.html +++ b/docs/en/cowboy/2.0/guide/cookies/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Using cookies</title> @@ -67,150 +67,153 @@ <h1 class="lined-header"><span>Using cookies</span></h1> -<div class="paragraph"><p>Cookies are a mechanism allowing applications to maintain
-state on top of the stateless HTTP protocol.</p></div>
-<div class="paragraph"><p>Cookies are a name/value store where the names and values are
-stored in plain text. They expire either after a delay
-or when the browser closes. They can be configured on a
-specific domain name or path, and restricted to secure
-resources (sent or downloaded over HTTPS), or restricted
-to the server (disallowing access from client-side scripts).</p></div>
-<div class="paragraph"><p>Cookie names are de facto case sensitive.</p></div>
-<div class="paragraph"><p>Cookies are stored client-side and sent with every subsequent
-request that matches the domain and path for which they were
-stored, until they expire. This can create a non-negligible
-cost.</p></div>
-<div class="paragraph"><p>Cookies should not be considered secure. They are stored on
-the user’s computer in plain text, and can be read by any
-program. They can also be read by proxies when using clear
-connections. Always validate the value before using it,
-and never store any sensitive information inside it.</p></div>
-<div class="paragraph"><p>Cookies set by the server are only available in requests
-following the client reception of the response containing
-them.</p></div>
-<div class="paragraph"><p>Cookies may be sent repeatedly. This is often useful to
-update the expiration time and avoid losing a cookie.</p></div>
-<div class="sect1">
-<h2 id="_setting_cookies">Setting cookies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default cookies are defined for the duration of the session:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>They can also be set for a duration in seconds:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To delete cookies, set <code>max_age</code> to 0:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To restrict cookies to a specific domain and path, the options
-of the same name can be used:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cookies will be sent with requests to this domain and all
-its subdomains, and to resources on this path or deeper
-in the path hierarchy.</p></div>
-<div class="paragraph"><p>To restrict cookies to secure channels (typically resources
-available over HTTPS):</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To prevent client-side scripts from accessing a cookie:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cookies may also be set client-side, for example using
-Javascript.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reading_cookies">Reading cookies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The client only ever sends back the cookie name and value.
-All other options that can be set are never sent back.</p></div>
-<div class="paragraph"><p>Cowboy provides two functions for reading cookies. Both
-involve parsing the cookie header(s) and so should not
-be called repeatedly.</p></div>
-<div class="paragraph"><p>You can get all cookies as a key/value list:</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="color: #009900">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>),
-{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or you can perform a match against cookies and retrieve
-only the ones you need, while at the same time doing
-any required post processing using <a href="../constraints">constraints</a>.
-This function returns a map:</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="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can use constraints to validate the values while matching
-them. The following snippet will crash if the <code>id</code> cookie is
-not an integer number or if the <code>lang</code> cookie is empty. Additionally
-the <code>id</code> cookie value will be converted to an integer term:</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="color: #009900">CookiesMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that if two cookies share the same name, then the map value
-will be a list of the two cookie values.</p></div>
-<div class="paragraph"><p>A default value can be provided. The default will be used
-if the <code>lang</code> cookie is not found. It will not be used if
-the cookie is found but has an empty value:</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="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If no default is provided and the value is missing, an
-exception is thrown.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cookies are a mechanism allowing applications to maintain +state on top of the stateless HTTP protocol.</p></div> +<div class="paragraph"><p>Cookies are a name/value store where the names and values are +stored in plain text. They expire either after a delay +or when the browser closes. They can be configured on a +specific domain name or path, and restricted to secure +resources (sent or downloaded over HTTPS), or restricted +to the server (disallowing access from client-side scripts).</p></div> +<div class="paragraph"><p>Cookie names are de facto case sensitive.</p></div> +<div class="paragraph"><p>Cookies are stored client-side and sent with every subsequent +request that matches the domain and path for which they were +stored, until they expire. This can create a non-negligible +cost.</p></div> +<div class="paragraph"><p>Cookies should not be considered secure. They are stored on +the user’s computer in plain text, and can be read by any +program. They can also be read by proxies when using clear +connections. Always validate the value before using it, +and never store any sensitive information inside it.</p></div> +<div class="paragraph"><p>Cookies set by the server are only available in requests +following the client reception of the response containing +them.</p></div> +<div class="paragraph"><p>Cookies may be sent repeatedly. This is often useful to +update the expiration time and avoid losing a cookie.</p></div> +<div class="sect1"> +<h2 id="_setting_cookies">Setting cookies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default cookies are defined for the duration of the session:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>They can also be set for a duration in seconds:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To delete cookies, set <code>max_age</code> to 0:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To restrict cookies to a specific domain and path, the options +of the same name can be used:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cookies will be sent with requests to this domain and all +its subdomains, and to resources on this path or deeper +in the path hierarchy.</p></div> +<div class="paragraph"><p>To restrict cookies to secure channels (typically resources +available over HTTPS):</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To prevent client-side scripts from accessing a cookie:</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="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cookies may also be set client-side, for example using +Javascript.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reading_cookies">Reading cookies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The client only ever sends back the cookie name and value. +All other options that can be set are never sent back.</p></div> +<div class="paragraph"><p>Cowboy provides two functions for reading cookies. Both +involve parsing the cookie header(s) and so should not +be called repeatedly.</p></div> +<div class="paragraph"><p>You can get all cookies as a key/value list:</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="color: #009900">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>), +{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or you can perform a match against cookies and retrieve +only the ones you need, while at the same time doing +any required post processing using <a href="../constraints">constraints</a>. +This function returns a map:</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="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can use constraints to validate the values while matching +them. The following snippet will crash if the <code>id</code> cookie is +not an integer number or if the <code>lang</code> cookie is empty. Additionally +the <code>id</code> cookie value will be converted to an integer term:</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="color: #009900">CookiesMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that if two cookies share the same name, then the map value +will be a list of the two cookie values.</p></div> +<div class="paragraph"><p>A default value can be provided. The default will be used +if the <code>lang</code> cookie is not found. It will not be used if +the cookie is found but has an empty value:</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="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If no default is provided and the value is missing, an +exception is thrown.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/erlang_web/index.html b/docs/en/cowboy/2.0/guide/erlang_web/index.html index c7e88684..accea26d 100644 --- a/docs/en/cowboy/2.0/guide/erlang_web/index.html +++ b/docs/en/cowboy/2.0/guide/erlang_web/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang and the Web</title> @@ -67,200 +67,203 @@ <h1 class="lined-header"><span>Erlang and the Web</span></h1> -<div class="paragraph"><p>Erlang is the ideal platform for writing Web applications.
-Its features are a perfect match for the requirements of
-modern Web applications.</p></div>
-<div class="sect1">
-<h2 id="_the_web_is_concurrent">The Web is concurrent</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When you access a website there is little concurrency
-involved. A few connections are opened and requests
-are sent through these connections. Then the web page
-is displayed on your screen. Your browser will only
-open up to 4 or 8 connections to the server, depending
-on your settings. This isn’t much.</p></div>
-<div class="paragraph"><p>But think about it. You are not the only one accessing
-the server at the same time. There can be hundreds, if
-not thousands, if not millions of connections to the
-same server at the same time.</p></div>
-<div class="paragraph"><p>Even today a lot of systems used in production haven’t
-solved the C10K problem (ten thousand concurrent connections).
-And the ones who did are trying hard to get to the next
-step, C100K, and are pretty far from it.</p></div>
-<div class="paragraph"><p>Erlang meanwhile has no problem handling millions of
-connections. At the time of writing there are application
-servers written in Erlang that can handle more than two
-million connections on a single server in a real production
-application, with spare memory and CPU!</p></div>
-<div class="paragraph"><p>The Web is concurrent, and Erlang is a language designed
-for concurrency, so it is a perfect match.</p></div>
-<div class="paragraph"><p>Of course, various platforms need to scale beyond a few
-million connections. This is where Erlang’s built-in
-distribution mechanisms come in. If one server isn’t
-enough, add more! Erlang allows you to use the same code
-for talking to local processes or to processes in other
-parts of your cluster, which means you can scale very
-quickly if the need arises.</p></div>
-<div class="paragraph"><p>The Web has large userbases, and the Erlang platform was
-designed to work in a distributed setting, so it is a
-perfect match.</p></div>
-<div class="paragraph"><p>Or is it? Surely you can find solutions to handle that many
-concurrent connections with your favorite language… But all
-these solutions will break down in the next few years. Why?
-Firstly because servers don’t get any more powerful, they
-instead get a lot more cores and memory. This is only useful
-if your application can use them properly, and Erlang is
-light-years away from anything else in that area. Secondly,
-today your computer and your phone are online, tomorrow your
-watch, goggles, bike, car, fridge and tons of other devices
-will also connect to various applications on the Internet.</p></div>
-<div class="paragraph"><p>Only Erlang is prepared to deal with what’s coming.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_web_is_soft_real_time">The Web is soft real time</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>What does soft real time mean, you ask? It means we want the
-operations done as quickly as possible, and in the case of
-web applications, it means we want the data propagated fast.</p></div>
-<div class="paragraph"><p>In comparison, hard real time has a similar meaning, but also
-has a hard time constraint, for example an operation needs to
-be done in under N milliseconds otherwise the system fails
-entirely.</p></div>
-<div class="paragraph"><p>Users aren’t that needy yet, they just want to get access
-to their content in a reasonable delay, and they want the
-actions they make to register at most a few seconds after
-they submitted them, otherwise they’ll start worrying about
-whether it successfully went through.</p></div>
-<div class="paragraph"><p>The Web is soft real time because taking longer to perform an
-operation would be seen as bad quality of service.</p></div>
-<div class="paragraph"><p>Erlang is a soft real time system. It will always run
-processes fairly, a little at a time, switching to another
-process after a while and preventing a single process to
-steal resources from all others. This means that Erlang
-can guarantee stable low latency of operations.</p></div>
-<div class="paragraph"><p>Erlang provides the guarantees that the soft real time Web
-requires.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_web_is_asynchronous">The Web is asynchronous</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Long ago, the Web was synchronous because HTTP was synchronous.
-You fired a request, and then waited for a response. Not anymore.
-It all began when XmlHttpRequest started being used. It allowed
-the client to perform asynchronous calls to the server.</p></div>
-<div class="paragraph"><p>Then Websocket appeared and allowed both the server and the client
-to send data to the other endpoint completely asynchronously. The
-data is contained within frames and no response is necessary.</p></div>
-<div class="paragraph"><p>Erlang processes work the same. They send each other data contained
-within messages and then continue running without needing a response.
-They tend to spend most of their time inactive, waiting for a new
-message, and the Erlang VM happily activate them when one is received.</p></div>
-<div class="paragraph"><p>It is therefore quite easy to imagine Erlang being good at receiving
-Websocket frames, which may come in at unpredictable times, pass the
-data to the responsible processes which are always ready waiting for
-new messages, and perform the operations required by only activating
-the required parts of the system.</p></div>
-<div class="paragraph"><p>The more recent Web technologies, like Websocket of course, but also
-HTTP/2.0, are all fully asynchronous protocols. The concept
-of requests and responses is retained of course, but anything could
-be sent in between, by both the client or the browser, and the
-responses could also be received in a completely different order.</p></div>
-<div class="paragraph"><p>Erlang is by nature asynchronous and really good at it thanks to the
-great engineering that has been done in the VM over the years. It’s
-only natural that it’s so good at dealing with the asynchronous Web.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_web_is_omnipresent">The Web is omnipresent</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The Web has taken a very important part of our lives. We’re
-connected at all times, when we’re on our phone, using our computer,
-passing time using a tablet while in the bathroom… And this
-isn’t going to slow down, every single device at home or on us
-will be connected.</p></div>
-<div class="paragraph"><p>All these devices are always connected. And with the number of
-alternatives to give you access to the content you seek, users
-tend to not stick around when problems arise. Users today want
-their applications to be always available and if it’s having
-too many issues they just move on.</p></div>
-<div class="paragraph"><p>Despite this, when developers choose a product to use for building
-web applications, their only concern seems to be "Is it fast?",
-and they look around for synthetic benchmarks showing which one
-is the fastest at sending "Hello world" with only a handful
-concurrent connections. Web benchmarks haven’t been representative
-of reality in a long time, and are drifting further away as
-time goes on.</p></div>
-<div class="paragraph"><p>What developers should really ask themselves is "Can I service
-all my users with no interruption?" and they’d find that they have
-two choices. They can either hope for the best, or they can use
-Erlang.</p></div>
-<div class="paragraph"><p>Erlang is built for fault tolerance. When writing code in any other
-language, you have to check all the return values and act accordingly
-to avoid any unforeseen issues. If you’re lucky, you won’t miss
-anything important. When writing Erlang code, you can just check
-the success condition and ignore all errors. If an error happens,
-the Erlang process crashes and is then restarted by a special
-process called a supervisor.</p></div>
-<div class="paragraph"><p>Erlang developers thus have no need to fear unhandled
-errors, and can focus on handling only the errors that should
-give some feedback to the user and let the system take care of
-the rest. This also has the advantage of allowing them to write
-a lot less code, and let them sleep at night.</p></div>
-<div class="paragraph"><p>Erlang’s fault tolerance oriented design is the first piece of
-what makes it the best choice for the omnipresent, always available
-Web.</p></div>
-<div class="paragraph"><p>The second piece is Erlang’s built-in distribution. Distribution
-is a key part of building a fault tolerant system, because it
-allows you to handle bigger failures, like a whole server going
-down, or even a data center entirely.</p></div>
-<div class="paragraph"><p>Fault tolerance and distribution are important today, and will be
-vital in the future of the Web. Erlang is ready.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_learn_erlang">Learn Erlang</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you are new to Erlang, you may want to grab a book or
-two to get started. Those are my recommendations as the
-author of Cowboy.</p></div>
-<div class="sect3">
-<h4 id="_the_erlanger_playbook">The Erlanger Playbook</h4>
-<div class="paragraph"><p>The Erlanger Playbook is an ebook I am currently writing,
-which covers a number of different topics from code to
-documentation to testing Erlang applications. It also has
-an Erlang section where it covers directly the building
-blocks and patterns, rather than details like the syntax.</p></div>
-<div class="paragraph"><p>You can most likely read it as a complete beginner, but
-you will need a companion book to make the most of it.
-Buy it from the <a href="http://ninenines.eu">Nine Nines website</a>.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_programming_erlang">Programming Erlang</h4>
-<div class="paragraph"><p>This book is from one of the creator of Erlang, Joe
-Armstrong. It provides a very good explanation of what
-Erlang is and why it is so. It serves as a very good
-introduction to the language and platform.</p></div>
-<div class="paragraph"><p>The book is <a href="http://pragprog.com/book/jaerlang2/programming-erlang">Programming Erlang</a>,
-and it also features a chapter on Cowboy.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_learn_you_some_erlang_for_great_good">Learn You Some Erlang for Great Good!</h4>
-<div class="paragraph"><p><a href="http://learnyousomeerlang.com">LYSE</a> is a much more complete
-book covering many aspects of Erlang, while also providing
-stories and humor. Be warned: it’s pretty verbose. It comes
-with a free online version and a more refined paper and
-ebook version.</p></div>
-</div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang is the ideal platform for writing Web applications. +Its features are a perfect match for the requirements of +modern Web applications.</p></div> +<div class="sect1"> +<h2 id="_the_web_is_concurrent">The Web is concurrent</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When you access a website there is little concurrency +involved. A few connections are opened and requests +are sent through these connections. Then the web page +is displayed on your screen. Your browser will only +open up to 4 or 8 connections to the server, depending +on your settings. This isn’t much.</p></div> +<div class="paragraph"><p>But think about it. You are not the only one accessing +the server at the same time. There can be hundreds, if +not thousands, if not millions of connections to the +same server at the same time.</p></div> +<div class="paragraph"><p>Even today a lot of systems used in production haven’t +solved the C10K problem (ten thousand concurrent connections). +And the ones who did are trying hard to get to the next +step, C100K, and are pretty far from it.</p></div> +<div class="paragraph"><p>Erlang meanwhile has no problem handling millions of +connections. At the time of writing there are application +servers written in Erlang that can handle more than two +million connections on a single server in a real production +application, with spare memory and CPU!</p></div> +<div class="paragraph"><p>The Web is concurrent, and Erlang is a language designed +for concurrency, so it is a perfect match.</p></div> +<div class="paragraph"><p>Of course, various platforms need to scale beyond a few +million connections. This is where Erlang’s built-in +distribution mechanisms come in. If one server isn’t +enough, add more! Erlang allows you to use the same code +for talking to local processes or to processes in other +parts of your cluster, which means you can scale very +quickly if the need arises.</p></div> +<div class="paragraph"><p>The Web has large userbases, and the Erlang platform was +designed to work in a distributed setting, so it is a +perfect match.</p></div> +<div class="paragraph"><p>Or is it? Surely you can find solutions to handle that many +concurrent connections with your favorite language… But all +these solutions will break down in the next few years. Why? +Firstly because servers don’t get any more powerful, they +instead get a lot more cores and memory. This is only useful +if your application can use them properly, and Erlang is +light-years away from anything else in that area. Secondly, +today your computer and your phone are online, tomorrow your +watch, goggles, bike, car, fridge and tons of other devices +will also connect to various applications on the Internet.</p></div> +<div class="paragraph"><p>Only Erlang is prepared to deal with what’s coming.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_web_is_soft_real_time">The Web is soft real time</h2> +<div class="sectionbody"> +<div class="paragraph"><p>What does soft real time mean, you ask? It means we want the +operations done as quickly as possible, and in the case of +web applications, it means we want the data propagated fast.</p></div> +<div class="paragraph"><p>In comparison, hard real time has a similar meaning, but also +has a hard time constraint, for example an operation needs to +be done in under N milliseconds otherwise the system fails +entirely.</p></div> +<div class="paragraph"><p>Users aren’t that needy yet, they just want to get access +to their content in a reasonable delay, and they want the +actions they make to register at most a few seconds after +they submitted them, otherwise they’ll start worrying about +whether it successfully went through.</p></div> +<div class="paragraph"><p>The Web is soft real time because taking longer to perform an +operation would be seen as bad quality of service.</p></div> +<div class="paragraph"><p>Erlang is a soft real time system. It will always run +processes fairly, a little at a time, switching to another +process after a while and preventing a single process to +steal resources from all others. This means that Erlang +can guarantee stable low latency of operations.</p></div> +<div class="paragraph"><p>Erlang provides the guarantees that the soft real time Web +requires.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_web_is_asynchronous">The Web is asynchronous</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Long ago, the Web was synchronous because HTTP was synchronous. +You fired a request, and then waited for a response. Not anymore. +It all began when XmlHttpRequest started being used. It allowed +the client to perform asynchronous calls to the server.</p></div> +<div class="paragraph"><p>Then Websocket appeared and allowed both the server and the client +to send data to the other endpoint completely asynchronously. The +data is contained within frames and no response is necessary.</p></div> +<div class="paragraph"><p>Erlang processes work the same. They send each other data contained +within messages and then continue running without needing a response. +They tend to spend most of their time inactive, waiting for a new +message, and the Erlang VM happily activate them when one is received.</p></div> +<div class="paragraph"><p>It is therefore quite easy to imagine Erlang being good at receiving +Websocket frames, which may come in at unpredictable times, pass the +data to the responsible processes which are always ready waiting for +new messages, and perform the operations required by only activating +the required parts of the system.</p></div> +<div class="paragraph"><p>The more recent Web technologies, like Websocket of course, but also +HTTP/2.0, are all fully asynchronous protocols. The concept +of requests and responses is retained of course, but anything could +be sent in between, by both the client or the browser, and the +responses could also be received in a completely different order.</p></div> +<div class="paragraph"><p>Erlang is by nature asynchronous and really good at it thanks to the +great engineering that has been done in the VM over the years. It’s +only natural that it’s so good at dealing with the asynchronous Web.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_web_is_omnipresent">The Web is omnipresent</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The Web has taken a very important part of our lives. We’re +connected at all times, when we’re on our phone, using our computer, +passing time using a tablet while in the bathroom… And this +isn’t going to slow down, every single device at home or on us +will be connected.</p></div> +<div class="paragraph"><p>All these devices are always connected. And with the number of +alternatives to give you access to the content you seek, users +tend to not stick around when problems arise. Users today want +their applications to be always available and if it’s having +too many issues they just move on.</p></div> +<div class="paragraph"><p>Despite this, when developers choose a product to use for building +web applications, their only concern seems to be "Is it fast?", +and they look around for synthetic benchmarks showing which one +is the fastest at sending "Hello world" with only a handful +concurrent connections. Web benchmarks haven’t been representative +of reality in a long time, and are drifting further away as +time goes on.</p></div> +<div class="paragraph"><p>What developers should really ask themselves is "Can I service +all my users with no interruption?" and they’d find that they have +two choices. They can either hope for the best, or they can use +Erlang.</p></div> +<div class="paragraph"><p>Erlang is built for fault tolerance. When writing code in any other +language, you have to check all the return values and act accordingly +to avoid any unforeseen issues. If you’re lucky, you won’t miss +anything important. When writing Erlang code, you can just check +the success condition and ignore all errors. If an error happens, +the Erlang process crashes and is then restarted by a special +process called a supervisor.</p></div> +<div class="paragraph"><p>Erlang developers thus have no need to fear unhandled +errors, and can focus on handling only the errors that should +give some feedback to the user and let the system take care of +the rest. This also has the advantage of allowing them to write +a lot less code, and let them sleep at night.</p></div> +<div class="paragraph"><p>Erlang’s fault tolerance oriented design is the first piece of +what makes it the best choice for the omnipresent, always available +Web.</p></div> +<div class="paragraph"><p>The second piece is Erlang’s built-in distribution. Distribution +is a key part of building a fault tolerant system, because it +allows you to handle bigger failures, like a whole server going +down, or even a data center entirely.</p></div> +<div class="paragraph"><p>Fault tolerance and distribution are important today, and will be +vital in the future of the Web. Erlang is ready.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_learn_erlang">Learn Erlang</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you are new to Erlang, you may want to grab a book or +two to get started. Those are my recommendations as the +author of Cowboy.</p></div> +<div class="sect3"> +<h4 id="_the_erlanger_playbook">The Erlanger Playbook</h4> +<div class="paragraph"><p>The Erlanger Playbook is an ebook I am currently writing, +which covers a number of different topics from code to +documentation to testing Erlang applications. It also has +an Erlang section where it covers directly the building +blocks and patterns, rather than details like the syntax.</p></div> +<div class="paragraph"><p>You can most likely read it as a complete beginner, but +you will need a companion book to make the most of it. +Buy it from the <a href="http://ninenines.eu">Nine Nines website</a>.</p></div> +</div> +<div class="sect3"> +<h4 id="_programming_erlang">Programming Erlang</h4> +<div class="paragraph"><p>This book is from one of the creator of Erlang, Joe +Armstrong. It provides a very good explanation of what +Erlang is and why it is so. It serves as a very good +introduction to the language and platform.</p></div> +<div class="paragraph"><p>The book is <a href="http://pragprog.com/book/jaerlang2/programming-erlang">Programming Erlang</a>, +and it also features a chapter on Cowboy.</p></div> +</div> +<div class="sect3"> +<h4 id="_learn_you_some_erlang_for_great_good">Learn You Some Erlang for Great Good!</h4> +<div class="paragraph"><p><a href="http://learnyousomeerlang.com">LYSE</a> is a much more complete +book covering many aspects of Erlang, while also providing +stories and humor. Be warned: it’s pretty verbose. It comes +with a free online version and a more refined paper and +ebook version.</p></div> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/flow_diagram/index.html b/docs/en/cowboy/2.0/guide/flow_diagram/index.html index 72e78d28..679ee0b1 100644 --- a/docs/en/cowboy/2.0/guide/flow_diagram/index.html +++ b/docs/en/cowboy/2.0/guide/flow_diagram/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Flow diagram</title> @@ -67,119 +67,122 @@ <h1 class="lined-header"><span>Flow diagram</span></h1> -<div class="paragraph"><p>Cowboy is a lightweight HTTP server with support for HTTP/1.1,
-HTTP/2 and Websocket.</p></div>
-<div class="paragraph"><p>It is built on top of Ranch. Please see the Ranch guide for more
-information about how the network connections are handled.</p></div>
-<div class="sect1">
-<h2 id="_overview">Overview</h2>
-<div class="sectionbody">
-<div class="imageblock">
-<div class="content">
-<img src="../http_req_resp.png" alt="HTTP request/response flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>As you can see on the diagram, the client
-begins by connecting to the server. This step is handled
-by a Ranch acceptor, which is a process dedicated to
-accepting new connections.</p></div>
-<div class="paragraph"><p>After Ranch accepts a new connection, whether it is an
-HTTP/1.1 or HTTP/2 connection, Cowboy starts receiving
-requests and handling them.</p></div>
-<div class="paragraph"><p>In HTTP/1.1 all requests come sequentially. In HTTP/2
-the requests may arrive and be processed concurrently.</p></div>
-<div class="paragraph"><p>When a request comes in, Cowboy creates a stream, which
-is a set of request/response and all the events associated
-with them. The protocol code in Cowboy defers the handling
-of these streams to stream handler modules. When you
-configure Cowboy you may define one or more module that
-will receive all events associated with a stream, including
-the request, response, bodies, Erlang messages and more.</p></div>
-<div class="paragraph"><p>By default Cowboy comes configured with a stream handler
-called <code>cowboy_stream_h</code>. This stream handler will create
-a new process for every request coming in, and then
-communicate with this process to read the body or send
-a response back. The request process executes middlewares
-which, by default, including the router and then the
-execution of handlers. Like stream handlers, middlewares
-may also be customized.</p></div>
-<div class="paragraph"><p>A response may be sent at almost any point in this
-diagram. If the response must be sent before the stream
-is initialized (because an error occurred early, for
-example) then stream handlers receive a special event
-indicating this error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_protocol_specific_headers">Protocol-specific headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy takes care of protocol-specific headers and prevents
-you from sending them manually. For HTTP/1.1 this includes
-the <code>transfer-encoding</code> and <code>connection</code> headers. For HTTP/2
-this includes the colon headers like <code>:status</code>.</p></div>
-<div class="paragraph"><p>Cowboy will also remove protocol-specific headers from
-requests before passing them to stream handlers. Cowboy
-tries to hide the implementation details of all protocols
-as well as possible.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_number_of_processes_per_connection">Number of processes per connection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, Cowboy will use one process per connection,
-plus one process per set of request/response (called a
-stream, internally).</p></div>
-<div class="paragraph"><p>The reason it creates a new process for every request is due
-to the requirements of HTTP/2 where requests are executed
-concurrently and independently from the connection. The
-frames from the different requests end up interleaved on
-the single TCP connection.</p></div>
-<div class="paragraph"><p>The request processes are never reused. There is therefore
-no need to perform any cleanup after the response has been
-sent. The process will terminate and Erlang/OTP will reclaim
-all memory at once.</p></div>
-<div class="paragraph"><p>Cowboy ultimately does not require more than one process
-per connection. It is possible to interact with the connection
-directly from a stream handler, a low level interface to Cowboy.
-They are executed from within the connection process, and can
-handle the incoming requests and send responses. This is however
-not recommended in normal circumstances, as a stream handler
-taking too long to execute could have a negative impact on
-concurrent requests or the state of the connection itself.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_date_header">Date header</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Because querying for the current date and time can be expensive,
-Cowboy generates one <em>Date</em> header value every second, shares it
-to all other processes, which then simply copy it in the response.
-This allows compliance with HTTP/1.1 with no actual performance loss.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_binaries">Binaries</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy makes extensive use of binaries.</p></div>
-<div class="paragraph"><p>Binaries are more efficient than lists for representing
-strings because they take less memory space. Processing
-performance can vary depending on the operation. Binaries
-are known for generally getting a great boost if the code
-is compiled natively. Please see the HiPE documentation
-for more details.</p></div>
-<div class="paragraph"><p>Binaries may end up being shared between processes. This
-can lead to some large memory usage when one process keeps
-the binary data around forever without freeing it. If you
-see some weird memory usage in your application, this might
-be the cause.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy is a lightweight HTTP server with support for HTTP/1.1, +HTTP/2 and Websocket.</p></div> +<div class="paragraph"><p>It is built on top of Ranch. Please see the Ranch guide for more +information about how the network connections are handled.</p></div> +<div class="sect1"> +<h2 id="_overview">Overview</h2> +<div class="sectionbody"> +<div class="imageblock"> +<div class="content"> +<img src="../http_req_resp.png" alt="HTTP request/response flowchart" /> +</div> +</div> +<div class="paragraph"><p>As you can see on the diagram, the client +begins by connecting to the server. This step is handled +by a Ranch acceptor, which is a process dedicated to +accepting new connections.</p></div> +<div class="paragraph"><p>After Ranch accepts a new connection, whether it is an +HTTP/1.1 or HTTP/2 connection, Cowboy starts receiving +requests and handling them.</p></div> +<div class="paragraph"><p>In HTTP/1.1 all requests come sequentially. In HTTP/2 +the requests may arrive and be processed concurrently.</p></div> +<div class="paragraph"><p>When a request comes in, Cowboy creates a stream, which +is a set of request/response and all the events associated +with them. The protocol code in Cowboy defers the handling +of these streams to stream handler modules. When you +configure Cowboy you may define one or more module that +will receive all events associated with a stream, including +the request, response, bodies, Erlang messages and more.</p></div> +<div class="paragraph"><p>By default Cowboy comes configured with a stream handler +called <code>cowboy_stream_h</code>. This stream handler will create +a new process for every request coming in, and then +communicate with this process to read the body or send +a response back. The request process executes middlewares +which, by default, including the router and then the +execution of handlers. Like stream handlers, middlewares +may also be customized.</p></div> +<div class="paragraph"><p>A response may be sent at almost any point in this +diagram. If the response must be sent before the stream +is initialized (because an error occurred early, for +example) then stream handlers receive a special event +indicating this error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_protocol_specific_headers">Protocol-specific headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy takes care of protocol-specific headers and prevents +you from sending them manually. For HTTP/1.1 this includes +the <code>transfer-encoding</code> and <code>connection</code> headers. For HTTP/2 +this includes the colon headers like <code>:status</code>.</p></div> +<div class="paragraph"><p>Cowboy will also remove protocol-specific headers from +requests before passing them to stream handlers. Cowboy +tries to hide the implementation details of all protocols +as well as possible.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_number_of_processes_per_connection">Number of processes per connection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default, Cowboy will use one process per connection, +plus one process per set of request/response (called a +stream, internally).</p></div> +<div class="paragraph"><p>The reason it creates a new process for every request is due +to the requirements of HTTP/2 where requests are executed +concurrently and independently from the connection. The +frames from the different requests end up interleaved on +the single TCP connection.</p></div> +<div class="paragraph"><p>The request processes are never reused. There is therefore +no need to perform any cleanup after the response has been +sent. The process will terminate and Erlang/OTP will reclaim +all memory at once.</p></div> +<div class="paragraph"><p>Cowboy ultimately does not require more than one process +per connection. It is possible to interact with the connection +directly from a stream handler, a low level interface to Cowboy. +They are executed from within the connection process, and can +handle the incoming requests and send responses. This is however +not recommended in normal circumstances, as a stream handler +taking too long to execute could have a negative impact on +concurrent requests or the state of the connection itself.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_date_header">Date header</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Because querying for the current date and time can be expensive, +Cowboy generates one <em>Date</em> header value every second, shares it +to all other processes, which then simply copy it in the response. +This allows compliance with HTTP/1.1 with no actual performance loss.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_binaries">Binaries</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy makes extensive use of binaries.</p></div> +<div class="paragraph"><p>Binaries are more efficient than lists for representing +strings because they take less memory space. Processing +performance can vary depending on the operation. Binaries +are known for generally getting a great boost if the code +is compiled natively. Please see the HiPE documentation +for more details.</p></div> +<div class="paragraph"><p>Binaries may end up being shared between processes. This +can lead to some large memory usage when one process keeps +the binary data around forever without freeing it. If you +see some weird memory usage in your application, this might +be the cause.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/getting_started/index.html b/docs/en/cowboy/2.0/guide/getting_started/index.html index 24cd3c71..9ec1da90 100644 --- a/docs/en/cowboy/2.0/guide/getting_started/index.html +++ b/docs/en/cowboy/2.0/guide/getting_started/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Getting started</title> @@ -67,167 +67,170 @@ <h1 class="lined-header"><span>Getting started</span></h1> -<div class="paragraph"><p>Erlang is more than a language, it is also an operating system
-for your applications. Erlang developers rarely write standalone
-modules, they write libraries or applications, and then bundle
-those into what is called a release. A release contains the
-Erlang VM plus all applications required to run the node, so
-it can be pushed to production directly.</p></div>
-<div class="paragraph"><p>This chapter walks you through all the steps of setting up
-Cowboy, writing your first application and generating your first
-release. At the end of this chapter you should know everything
-you need to push your first Cowboy application to production.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>We are going to use the <a href="https://github.com/ninenines/erlang.mk">Erlang.mk</a>
-build system. If you are using Windows, please check the
-<a href="http://erlang.mk/guide/installation.html">Installation instructions</a>
-to get your environment setup before you continue.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_bootstrap">Bootstrap</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>First, let’s create the directory for our application.</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>$ mkdir hello_erlang
-$ cd hello_erlang</tt></pre></div></div>
-<div class="paragraph"><p>Then we need to download Erlang.mk. Either use the following
-command or download it manually.</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>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
-<div class="paragraph"><p>We can now bootstrap our application. Since we are going to generate
-a release, we will also bootstrap it at the same time.</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>This creates a Makefile, a base application, and the release files
-necessary for creating the release. We can already build and start
-this release.</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>$ make run
-<span style="color: #990000">...</span>
-<span style="color: #990000">(</span>hello_erlang@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div>
-<div class="paragraph"><p>Entering the command <code>i().</code> will show the running processes, including
-one called <code>hello_erlang_sup</code>. This is the supervisor for our
-application.</p></div>
-<div class="paragraph"><p>The release currently does nothing. In the rest of this chapter we
-will add Cowboy as a dependency and write a simple "Hello world!"
-handler.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cowboy_setup">Cowboy setup</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>We will modify the <em>Makefile</em> to tell the build system it needs to
-fetch and compile Cowboy:</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="color: #009900">PROJECT =</span> hello_erlang
-
-<span style="color: #009900">DEPS =</span> cowboy
-<span style="color: #009900">dep_cowboy_commit =</span> master
-
-<span style="color: #009900">DEP_PLUGINS =</span> cowboy
-
-include erlang.mk</tt></pre></div></div>
-<div class="paragraph"><p>We also tell the build system to load the plugins Cowboy provides.
-These include predefined templates that we will use soon.</p></div>
-<div class="paragraph"><p>If you do <code>make run</code> now, Cowboy will be included in the release
-and started automatically. This is not enough however, as Cowboy
-doesn’t do anything by default. We still need to tell Cowboy to
-listen for connections.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_for_connections">Listening for connections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>First we define the routes that Cowboy will use to map requests
-to handler modules, and then we start the listener. This is best
-done at application startup.</p></div>
-<div class="paragraph"><p>Open the <em>src/hello_erlang_app.erl</em> file and add the necessary
-code to the <code>start/2</code> function to make it look like this:</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: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">hello_handler</span>, []}]}
- ]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>,
- [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
- #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}}
- ),
- <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Routes are explained in details in the <a href="../routing">Routing</a>
-chapter. For this tutorial we map the path <code>/</code> to the handler
-module <code>hello_handler</code>. This module doesn’t exist yet.</p></div>
-<div class="paragraph"><p>Build and start the release, then open <a href="http://localhost:8080">http://localhost:8080</a>
-in your browser. You will get a 500 error because the module is missing.
-Any other URL, like <a href="http://localhost:8080/test">http://localhost:8080/test</a>, will result in a
-404 error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_handling_requests">Handling requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy features different kinds of handlers, including REST
-and Websocket handlers. For this tutorial we will use a plain
-HTTP handler.</p></div>
-<div class="paragraph"><p>Generate a handler from a template:</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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>cowboy<span style="color: #990000">.</span>http <span style="color: #009900">n</span><span style="color: #990000">=</span>hello_handler</tt></pre></div></div>
-<div class="paragraph"><p>Then, open the <em>src/hello_handler.erl</em> file and modify
-the <code>init/2</code> function like this to send a reply.</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: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>,
- #{<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>},
- <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello Erlang!"</span><span style="color: #990000">>></span>,
- <span style="color: #009900">Req0</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>What the above code does is send a 200 OK reply, with the
-Content-type header set to <code>text/plain</code> and the response
-body set to <code>Hello Erlang!</code>.</p></div>
-<div class="paragraph"><p>If you run the release and open <a href="http://localhost:8080">http://localhost:8080</a>
-in your browser, you should get a nice <code>Hello Erlang!</code> displayed!</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang is more than a language, it is also an operating system +for your applications. Erlang developers rarely write standalone +modules, they write libraries or applications, and then bundle +those into what is called a release. A release contains the +Erlang VM plus all applications required to run the node, so +it can be pushed to production directly.</p></div> +<div class="paragraph"><p>This chapter walks you through all the steps of setting up +Cowboy, writing your first application and generating your first +release. At the end of this chapter you should know everything +you need to push your first Cowboy application to production.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>We are going to use the <a href="https://github.com/ninenines/erlang.mk">Erlang.mk</a> +build system. If you are using Windows, please check the +<a href="http://erlang.mk/guide/installation.html">Installation instructions</a> +to get your environment setup before you continue.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_bootstrap">Bootstrap</h2> +<div class="sectionbody"> +<div class="paragraph"><p>First, let’s create the directory for our application.</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>$ mkdir hello_erlang +$ cd hello_erlang</tt></pre></div></div> +<div class="paragraph"><p>Then we need to download Erlang.mk. Either use the following +command or download it manually.</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>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div> +<div class="paragraph"><p>We can now bootstrap our application. Since we are going to generate +a release, we will also bootstrap it at the same time.</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>This creates a Makefile, a base application, and the release files +necessary for creating the release. We can already build and start +this release.</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>$ make run +<span style="color: #990000">...</span> +<span style="color: #990000">(</span>hello_erlang@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div> +<div class="paragraph"><p>Entering the command <code>i().</code> will show the running processes, including +one called <code>hello_erlang_sup</code>. This is the supervisor for our +application.</p></div> +<div class="paragraph"><p>The release currently does nothing. In the rest of this chapter we +will add Cowboy as a dependency and write a simple "Hello world!" +handler.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_cowboy_setup">Cowboy setup</h2> +<div class="sectionbody"> +<div class="paragraph"><p>We will modify the <em>Makefile</em> to tell the build system it needs to +fetch and compile Cowboy:</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="color: #009900">PROJECT =</span> hello_erlang + +<span style="color: #009900">DEPS =</span> cowboy +<span style="color: #009900">dep_cowboy_commit =</span> master + +<span style="color: #009900">DEP_PLUGINS =</span> cowboy + +include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>We also tell the build system to load the plugins Cowboy provides. +These include predefined templates that we will use soon.</p></div> +<div class="paragraph"><p>If you do <code>make run</code> now, Cowboy will be included in the release +and started automatically. This is not enough however, as Cowboy +doesn’t do anything by default. We still need to tell Cowboy to +listen for connections.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_for_connections">Listening for connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>First we define the routes that Cowboy will use to map requests +to handler modules, and then we start the listener. This is best +done at application startup.</p></div> +<div class="paragraph"><p>Open the <em>src/hello_erlang_app.erl</em> file and add the necessary +code to the <code>start/2</code> function to make it look like this:</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: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">hello_handler</span>, []}]} + ]), + {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>, + [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], + #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}} + ), + <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Routes are explained in details in the <a href="../routing">Routing</a> +chapter. For this tutorial we map the path <code>/</code> to the handler +module <code>hello_handler</code>. This module doesn’t exist yet.</p></div> +<div class="paragraph"><p>Build and start the release, then open <a href="http://localhost:8080">http://localhost:8080</a> +in your browser. You will get a 500 error because the module is missing. +Any other URL, like <a href="http://localhost:8080/test">http://localhost:8080/test</a>, will result in a +404 error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_handling_requests">Handling requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy features different kinds of handlers, including REST +and Websocket handlers. For this tutorial we will use a plain +HTTP handler.</p></div> +<div class="paragraph"><p>Generate a handler from a template:</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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>cowboy<span style="color: #990000">.</span>http <span style="color: #009900">n</span><span style="color: #990000">=</span>hello_handler</tt></pre></div></div> +<div class="paragraph"><p>Then, open the <em>src/hello_handler.erl</em> file and modify +the <code>init/2</code> function like this to send a reply.</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: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, + #{<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>}, + <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello Erlang!"</span><span style="color: #990000">>></span>, + <span style="color: #009900">Req0</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>What the above code does is send a 200 OK reply, with the +Content-type header set to <code>text/plain</code> and the response +body set to <code>Hello Erlang!</code>.</p></div> +<div class="paragraph"><p>If you run the release and open <a href="http://localhost:8080">http://localhost:8080</a> +in your browser, you should get a nice <code>Hello Erlang!</code> displayed!</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/handlers/index.html b/docs/en/cowboy/2.0/guide/handlers/index.html index dbb50c85..33cd53e2 100644 --- a/docs/en/cowboy/2.0/guide/handlers/index.html +++ b/docs/en/cowboy/2.0/guide/handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Handlers</title> @@ -67,97 +67,100 @@ <h1 class="lined-header"><span>Handlers</span></h1> -<div class="paragraph"><p>Handlers are Erlang modules that handle HTTP requests.</p></div>
-<div class="sect1">
-<h2 id="_plain_http_handlers">Plain HTTP handlers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The most basic handler in Cowboy implements the mandatory
-<code>init/2</code> callback, manipulates the request, optionally
-sends a response and then returns.</p></div>
-<div class="paragraph"><p>This callback receives the <a href="../req">Req object</a> and the initial
-state defined in the <a href="../routing">router configuration</a>.</p></div>
-<div class="paragraph"><p>A handler that does nothing would look like this:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Despite sending no reply, a <code>204 No Content</code> response will be
-sent to the client, as Cowboy makes sure that a response is
-sent for every request.</p></div>
-<div class="paragraph"><p>We need to use the Req object to reply.</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: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>
- }, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello World!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy will immediately send a response when <code>cowboy:reply/4</code>
-is called.</p></div>
-<div class="paragraph"><p>We then return a 3-tuple. <code>ok</code> means that the handler ran
-successfully. We also give the modified Req back to Cowboy.</p></div>
-<div class="paragraph"><p>The last value of the tuple is a state that will be used
-in every subsequent callbacks to this handler. Plain HTTP
-handlers only have one additional callback, the optional
-and rarely used <code>terminate/3</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_other_handlers">Other handlers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>init/2</code> callback can also be used to inform Cowboy
-that this is a different kind of handler and that Cowboy
-should switch to it. To do this you simply need to return
-the module name of the handler type you want to switch to.</p></div>
-<div class="paragraph"><p>Cowboy comes with three handler types you can switch to:
-<a href="../rest_handlers">cowboy_rest</a>, <a href="#ws_handlers">cowboy_websocket</a>
-and <a href="../loop_handlers">cowboy_loop</a>. In addition to those you
-can define your own handler types.</p></div>
-<div class="paragraph"><p>Switching is simple. Instead of returning <code>ok</code>, you simply
-return the name of the handler type you want to use. The
-following snippet switches to a Websocket handler:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cleaning_up">Cleaning up</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All handler types provide the optional <code>terminate/3</code> callback.</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: #000000">terminate</span></span>(<span style="color: #009900">_Reason</span>, <span style="color: #009900">_Req</span>, <span style="color: #009900">_State</span>) <span style="color: #990000">-></span>
- <span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This callback is strictly reserved for any required cleanup.
-You cannot send a response from this function. There is no
-other return value.</p></div>
-<div class="paragraph"><p>This callback is optional because it is rarely necessary.
-Cleanup should be done in separate processes directly (by
-monitoring the handler process to detect when it exits).</p></div>
-<div class="paragraph"><p>Cowboy does not reuse processes for different requests. The
-process will terminate soon after this call returns.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Handlers are Erlang modules that handle HTTP requests.</p></div> +<div class="sect1"> +<h2 id="_plain_http_handlers">Plain HTTP handlers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The most basic handler in Cowboy implements the mandatory +<code>init/2</code> callback, manipulates the request, optionally +sends a response and then returns.</p></div> +<div class="paragraph"><p>This callback receives the <a href="../req">Req object</a> and the initial +state defined in the <a href="../routing">router configuration</a>.</p></div> +<div class="paragraph"><p>A handler that does nothing would look like this:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Despite sending no reply, a <code>204 No Content</code> response will be +sent to the client, as Cowboy makes sure that a response is +sent for every request.</p></div> +<div class="paragraph"><p>We need to use the Req object to reply.</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: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span> + }, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello World!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy will immediately send a response when <code>cowboy:reply/4</code> +is called.</p></div> +<div class="paragraph"><p>We then return a 3-tuple. <code>ok</code> means that the handler ran +successfully. We also give the modified Req back to Cowboy.</p></div> +<div class="paragraph"><p>The last value of the tuple is a state that will be used +in every subsequent callbacks to this handler. Plain HTTP +handlers only have one additional callback, the optional +and rarely used <code>terminate/3</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_other_handlers">Other handlers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>init/2</code> callback can also be used to inform Cowboy +that this is a different kind of handler and that Cowboy +should switch to it. To do this you simply need to return +the module name of the handler type you want to switch to.</p></div> +<div class="paragraph"><p>Cowboy comes with three handler types you can switch to: +<a href="../rest_handlers">cowboy_rest</a>, <a href="#ws_handlers">cowboy_websocket</a> +and <a href="../loop_handlers">cowboy_loop</a>. In addition to those you +can define your own handler types.</p></div> +<div class="paragraph"><p>Switching is simple. Instead of returning <code>ok</code>, you simply +return the name of the handler type you want to use. The +following snippet switches to a Websocket handler:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_cleaning_up">Cleaning up</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All handler types provide the optional <code>terminate/3</code> callback.</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: #000000">terminate</span></span>(<span style="color: #009900">_Reason</span>, <span style="color: #009900">_Req</span>, <span style="color: #009900">_State</span>) <span style="color: #990000">-></span> + <span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This callback is strictly reserved for any required cleanup. +You cannot send a response from this function. There is no +other return value.</p></div> +<div class="paragraph"><p>This callback is optional because it is rarely necessary. +Cleanup should be done in separate processes directly (by +monitoring the handler process to detect when it exits).</p></div> +<div class="paragraph"><p>Cowboy does not reuse processes for different requests. The +process will terminate soon after this call returns.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/index.html b/docs/en/cowboy/2.0/guide/index.html index 4932891e..533d8db1 100644 --- a/docs/en/cowboy/2.0/guide/index.html +++ b/docs/en/cowboy/2.0/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy User Guide</title> @@ -67,201 +67,199 @@ <h1 class="lined-header"><span>Cowboy User Guide</span></h1> -<div class="sect1">
-<h2 id="_rationale">Rationale</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="modern_web/">The modern Web</a>
-</p>
-</li>
-<li>
-<p>
-<a href="erlang_web/">Erlang and the Web</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_introduction">Introduction</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="getting_started/">Getting started</a>
-</p>
-</li>
-<li>
-<p>
-<a href="flow_diagram/">Flow diagram</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<a href="routing/">Routing</a>
-</p>
-</li>
-<li>
-<p>
-<a href="constraints/">Constraints</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_handlers">Handlers</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="handlers/">Handlers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="loop_handlers/">Loop handlers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="static_files/">Static files</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_request_and_response">Request and response</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="req/">Request details</a>
-</p>
-</li>
-<li>
-<p>
-<a href="req_body/">Reading the request body</a>
-</p>
-</li>
-<li>
-<p>
-<a href="resp/">Sending a response</a>
-</p>
-</li>
-<li>
-<p>
-<a href="cookies/">Using cookies</a>
-</p>
-</li>
-<li>
-<p>
-<a href="multipart/">Multipart</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest">REST</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="rest_principles/">REST principles</a>
-</p>
-</li>
-<li>
-<p>
-<a href="rest_handlers/">Handling REST requests</a>
-</p>
-</li>
-<li>
-<p>
-<a href="rest_flowcharts/">REST flowcharts</a>
-</p>
-</li>
-<li>
-<p>
-<a href="resource_design/">Designing a resource handler</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_websocket">Websocket</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="ws_protocol/">The Websocket protocol</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ws_handlers/">Websocket handlers</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_advanced">Advanced</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="streams/">Streams</a>
-</p>
-</li>
-<li>
-<p>
-<a href="middlewares/">Middlewares</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_additional_information">Additional information</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a>
-</p>
-</li>
-</ul></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="specs/">HTTP and other specifications</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_rationale">Rationale</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="modern_web/">The modern Web</a> +</p> +</li> +<li> +<p> +<a href="erlang_web/">Erlang and the Web</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_introduction">Introduction</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="getting_started/">Getting started</a> +</p> +</li> +<li> +<p> +<a href="flow_diagram/">Flow diagram</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="listeners/">Listeners</a> +</p> +</li> +<li> +<p> +<a href="routing/">Routing</a> +</p> +</li> +<li> +<p> +<a href="constraints/">Constraints</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_handlers">Handlers</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="handlers/">Handlers</a> +</p> +</li> +<li> +<p> +<a href="loop_handlers/">Loop handlers</a> +</p> +</li> +<li> +<p> +<a href="static_files/">Static files</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_request_and_response">Request and response</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="req/">Request details</a> +</p> +</li> +<li> +<p> +<a href="req_body/">Reading the request body</a> +</p> +</li> +<li> +<p> +<a href="resp/">Sending a response</a> +</p> +</li> +<li> +<p> +<a href="cookies/">Using cookies</a> +</p> +</li> +<li> +<p> +<a href="multipart/">Multipart</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rest">REST</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="rest_principles/">REST principles</a> +</p> +</li> +<li> +<p> +<a href="rest_handlers/">Handling REST requests</a> +</p> +</li> +<li> +<p> +<a href="rest_flowcharts/">REST flowcharts</a> +</p> +</li> +<li> +<p> +<a href="resource_design/">Designing a resource handler</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_websocket">Websocket</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="ws_protocol/">The Websocket protocol</a> +</p> +</li> +<li> +<p> +<a href="ws_handlers/">Websocket handlers</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_advanced">Advanced</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="streams/">Streams</a> +</p> +</li> +<li> +<p> +<a href="middlewares/">Middlewares</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_additional_information">Additional information</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a> +</p> +</li> +<li> +<p> +<a href="specs/">HTTP and other specifications</a> +</p> +</li> +</ul></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/guide/introduction/index.html b/docs/en/cowboy/2.0/guide/introduction/index.html index 8c0c25f8..63b07c4e 100644 --- a/docs/en/cowboy/2.0/guide/introduction/index.html +++ b/docs/en/cowboy/2.0/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,85 +67,88 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Cowboy is a small, fast and modern HTTP server for Erlang/OTP.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete <a href="../modern_web">modern Web stack</a>.
-This includes HTTP/1.1, HTTP/2, Websocket, Server-Sent Events and
-Webmachine-based REST.</p></div>
-<div class="paragraph"><p>Cowboy comes with functions for introspection and tracing, enabling
-developers to know precisely what is happening at any time. Its modular
-design also easily enable developers to add instrumentation.</p></div>
-<div class="paragraph"><p>Cowboy is a high quality project. It has a small code base, is very
-efficient (both in latency and memory use) and can easily be embedded
-in another application.</p></div>
-<div class="paragraph"><p>Cowboy is clean Erlang code. It includes hundreds of tests and its code
-is fully compliant with the Dialyzer. It is also well documented and
-features a Function Reference, a User Guide and numerous Tutorials.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Beginner Erlang knowledge is recommended for reading this guide.</p></div>
-<div class="paragraph"><p>Knowledge of the HTTP protocol is recommended but not required, as it
-will be detailed throughout the guide.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_supported_platforms">Supported platforms</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is tested and supported on Linux, FreeBSD, Windows and OSX.</p></div>
-<div class="paragraph"><p>Cowboy has been reported to work on other platforms, but we make no
-guarantee that the experience will be safe and smooth. You are advised
-to perform the necessary testing and security audits prior to deploying
-on other platforms.</p></div>
-<div class="paragraph"><p>Cowboy is developed for Erlang/OTP 19.0 and newer.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_license">License</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy uses the ISC License.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>Copyright (c) 2011-2017, Loïc Hoguin <[email protected]>
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a>.</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. When using HTTP/1.1, Cowboy converts
-all the request header names to lowercase. HTTP/2 requires clients to
-send them as lowercase. Any other header name is expected to be provided
-lowercased, including when querying information about the request or
-when sending responses.</p></div>
-<div class="paragraph"><p>The same applies to any other case insensitive value.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy is a small, fast and modern HTTP server for Erlang/OTP.</p></div> +<div class="paragraph"><p>Cowboy aims to provide a complete <a href="../modern_web">modern Web stack</a>. +This includes HTTP/1.1, HTTP/2, Websocket, Server-Sent Events and +Webmachine-based REST.</p></div> +<div class="paragraph"><p>Cowboy comes with functions for introspection and tracing, enabling +developers to know precisely what is happening at any time. Its modular +design also easily enable developers to add instrumentation.</p></div> +<div class="paragraph"><p>Cowboy is a high quality project. It has a small code base, is very +efficient (both in latency and memory use) and can easily be embedded +in another application.</p></div> +<div class="paragraph"><p>Cowboy is clean Erlang code. It includes hundreds of tests and its code +is fully compliant with the Dialyzer. It is also well documented and +features a Function Reference, a User Guide and numerous Tutorials.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Beginner Erlang knowledge is recommended for reading this guide.</p></div> +<div class="paragraph"><p>Knowledge of the HTTP protocol is recommended but not required, as it +will be detailed throughout the guide.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supported_platforms">Supported platforms</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy is tested and supported on Linux, FreeBSD, Windows and OSX.</p></div> +<div class="paragraph"><p>Cowboy has been reported to work on other platforms, but we make no +guarantee that the experience will be safe and smooth. You are advised +to perform the necessary testing and security audits prior to deploying +on other platforms.</p></div> +<div class="paragraph"><p>Cowboy is developed for Erlang/OTP 19.0 and newer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_license">License</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy uses the ISC License.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>Copyright (c) 2011-2017, Loïc Hoguin <[email protected]> + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</code></pre> +</div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a>.</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. When using HTTP/1.1, Cowboy converts +all the request header names to lowercase. HTTP/2 requires clients to +send them as lowercase. Any other header name is expected to be provided +lowercased, including when querying information about the request or +when sending responses.</p></div> +<div class="paragraph"><p>The same applies to any other case insensitive value.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/listeners/index.html b/docs/en/cowboy/2.0/guide/listeners/index.html index 49d841c6..a5fbb60e 100644 --- a/docs/en/cowboy/2.0/guide/listeners/index.html +++ b/docs/en/cowboy/2.0/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,115 +67,118 @@ <h1 class="lined-header"><span>Listeners</span></h1> -<div class="paragraph"><p>A listener is a set of processes that listens on a port for
-new connections. Incoming connections get handled by Cowboy.
-Depending on the connection handshake, one or another protocol
-may be used.</p></div>
-<div class="paragraph"><p>This chapter is specific to Cowboy. Please refer to the
-<a href="http://ninenines.eu/docs/en/ranch/1.3/guide/listeners/">Ranch User Guide</a>
-for more information about listeners.</p></div>
-<div class="paragraph"><p>Cowboy provides two types of listeners: one listening for
-clear TCP connections, and one listening for secure TLS
-connections. Both of them support the HTTP/1.1 and HTTP/2
-protocols.</p></div>
-<div class="sect1">
-<h2 id="_clear_tcp_listener">Clear TCP listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The clear TCP listener will accept connections on the
-given port. A typical HTTP server would listen on port 80.
-Port 80 requires special permissions on most platforms
-however so a common alternative is port 8080.</p></div>
-<div class="paragraph"><p>The following snippet starts listening for connections
-on port 8080:</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: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">hello_handler</span>, []}]}
- ]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>,
- [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
- #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}}
- ),
- <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <a href="../getting_started">Getting Started</a> chapter uses a
-clear TCP listener.</p></div>
-<div class="paragraph"><p>Clients connecting to Cowboy on the clear listener port are
-expected to use either HTTP/1.1 or HTTP/2.</p></div>
-<div class="paragraph"><p>Cowboy supports both methods of initiating a clear
-HTTP/2 connection: through the Upgrade mechanism
-(<a href="https://tools.ietf.org/html/rfc7540#section-3.2">RFC 7540 3.2</a>)
-or by sending the preface directly
-(<a href="https://tools.ietf.org/html/rfc7540#section-3.4">RFC 7540 3.4</a>).</p></div>
-<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1
-implementation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_secure_tls_listener">Secure TLS listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The secure TLS listener will accept connections on the
-given port. A typical HTTPS server would listen on port 443.
-Port 443 requires special permissions on most platforms
-however so a common alternative is port 8443.</p></div>
-<div class="paragraph"><p>The function provided by Cowboy will ensure that the TLS
-options given are following the HTTP/2 RFC with regards
-to security. For example some TLS extensions or ciphers
-may be disabled. This also applies to HTTP/1.1 connections
-on this listener. If this is not desirable, Ranch can be
-used directly to setup a custom listener.</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: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">hello_handler</span>, []}]}
- ]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_tls</span></span>(<span style="color: #FF6600">my_http_listener</span>,
- [
- {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>},
- {<span style="color: #FF6600">certfile</span>, <span style="color: #FF0000">"/path/to/certfile"</span>},
- {<span style="color: #FF6600">keyfile</span>, <span style="color: #FF0000">"/path/to/keyfile"</span>}
- ],
- #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}}
- ),
- <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Clients connecting to Cowboy on the secure listener are
-expected to use the ALPN TLS extension to indicate what
-protocols they understand. Cowboy always prefers HTTP/2
-over HTTP/1.1 when both are supported. When neither are
-supported by the client, or when the ALPN extension was
-missing, Cowboy expects HTTP/1.1 to be used.</p></div>
-<div class="paragraph"><p>Cowboy also advertises HTTP/2 support through the older
-NPN TLS extension for compatibility. Note however that
-this support will likely not be enabled by default when
-Cowboy 2.0 gets released.</p></div>
-<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1
-implementation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_protocol_configuration">Protocol configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP/1.1 and HTTP/2 protocols share the same semantics;
-only their framing differs. The first is a text protocol and
-the second a binary protocol.</p></div>
-<div class="paragraph"><p>Cowboy doesn’t separate the configuration for HTTP/1.1 and
-HTTP/2. Everything goes into the same map. Many options are
-shared.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A listener is a set of processes that listens on a port for +new connections. Incoming connections get handled by Cowboy. +Depending on the connection handshake, one or another protocol +may be used.</p></div> +<div class="paragraph"><p>This chapter is specific to Cowboy. Please refer to the +<a href="http://ninenines.eu/docs/en/ranch/1.3/guide/listeners/">Ranch User Guide</a> +for more information about listeners.</p></div> +<div class="paragraph"><p>Cowboy provides two types of listeners: one listening for +clear TCP connections, and one listening for secure TLS +connections. Both of them support the HTTP/1.1 and HTTP/2 +protocols.</p></div> +<div class="sect1"> +<h2 id="_clear_tcp_listener">Clear TCP listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The clear TCP listener will accept connections on the +given port. A typical HTTP server would listen on port 80. +Port 80 requires special permissions on most platforms +however so a common alternative is port 8080.</p></div> +<div class="paragraph"><p>The following snippet starts listening for connections +on port 8080:</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: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">hello_handler</span>, []}]} + ]), + {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>, + [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], + #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}} + ), + <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <a href="../getting_started">Getting Started</a> chapter uses a +clear TCP listener.</p></div> +<div class="paragraph"><p>Clients connecting to Cowboy on the clear listener port are +expected to use either HTTP/1.1 or HTTP/2.</p></div> +<div class="paragraph"><p>Cowboy supports both methods of initiating a clear +HTTP/2 connection: through the Upgrade mechanism +(<a href="https://tools.ietf.org/html/rfc7540#section-3.2">RFC 7540 3.2</a>) +or by sending the preface directly +(<a href="https://tools.ietf.org/html/rfc7540#section-3.4">RFC 7540 3.4</a>).</p></div> +<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 +implementation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_secure_tls_listener">Secure TLS listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The secure TLS listener will accept connections on the +given port. A typical HTTPS server would listen on port 443. +Port 443 requires special permissions on most platforms +however so a common alternative is port 8443.</p></div> +<div class="paragraph"><p>The function provided by Cowboy will ensure that the TLS +options given are following the HTTP/2 RFC with regards +to security. For example some TLS extensions or ciphers +may be disabled. This also applies to HTTP/1.1 connections +on this listener. If this is not desirable, Ranch can be +used directly to setup a custom listener.</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: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">hello_handler</span>, []}]} + ]), + {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_tls</span></span>(<span style="color: #FF6600">my_http_listener</span>, + [ + {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>}, + {<span style="color: #FF6600">certfile</span>, <span style="color: #FF0000">"/path/to/certfile"</span>}, + {<span style="color: #FF6600">keyfile</span>, <span style="color: #FF0000">"/path/to/keyfile"</span>} + ], + #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}} + ), + <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Clients connecting to Cowboy on the secure listener are +expected to use the ALPN TLS extension to indicate what +protocols they understand. Cowboy always prefers HTTP/2 +over HTTP/1.1 when both are supported. When neither are +supported by the client, or when the ALPN extension was +missing, Cowboy expects HTTP/1.1 to be used.</p></div> +<div class="paragraph"><p>Cowboy also advertises HTTP/2 support through the older +NPN TLS extension for compatibility. Note however that +this support will likely not be enabled by default when +Cowboy 2.0 gets released.</p></div> +<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 +implementation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_protocol_configuration">Protocol configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP/1.1 and HTTP/2 protocols share the same semantics; +only their framing differs. The first is a text protocol and +the second a binary protocol.</p></div> +<div class="paragraph"><p>Cowboy doesn’t separate the configuration for HTTP/1.1 and +HTTP/2. Everything goes into the same map. Many options are +shared.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc index 80bc484d..21bf8424 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc @@ -1,8 +1,6 @@ [[loop_handlers]] == Loop handlers -// @todo This description needs to be updated. - Loop handlers are a special kind of HTTP handlers used when the response can not be sent right away. The handler enters instead a receive loop waiting for the right message before it can send diff --git a/docs/en/cowboy/2.0/guide/loop_handlers/index.html b/docs/en/cowboy/2.0/guide/loop_handlers/index.html index 442bc7e0..0b0b50b5 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/loop_handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Loop handlers</title> @@ -67,137 +67,140 @@ <h1 class="lined-header"><span>Loop handlers</span></h1> -<div class="paragraph"><p>Loop handlers are a special kind of HTTP handlers used when the
-response can not be sent right away. The handler enters instead
-a receive loop waiting for the right message before it can send
-a response.</p></div>
-<div class="paragraph"><p>Loop handlers are used for requests where a response might not
-be immediately available, but where you would like to keep the
-connection open for a while in case the response arrives. The
-most known example of such practice is known as long polling.</p></div>
-<div class="paragraph"><p>Loop handlers can also be used for requests where a response is
-partially available and you need to stream the response body
-while the connection is open. The most known example of such
-practice is server-sent events.</p></div>
-<div class="paragraph"><p>While the same can be accomplished using plain HTTP handlers,
-it is recommended to use loop handlers because they are well-tested
-and allow using built-in features like hibernation and timeouts.</p></div>
-<div class="paragraph"><p>Loop handlers essentially wait for one or more Erlang messages
-and feed these messages to the <code>info/3</code> callback. It also features
-the <code>init/2</code> and <code>terminate/3</code> callbacks which work the same as
-for plain HTTP handlers.</p></div>
-<div class="sect1">
-<h2 id="_initialization">Initialization</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>init/2</code> function must return a <code>cowboy_loop</code> tuple to enable
-loop handler behavior. This tuple may optionally contain
-a timeout value and/or the atom <code>hibernate</code> to make the
-process enter hibernation until a message is received.</p></div>
-<div class="paragraph"><p>This snippet enables the loop handler:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This also makes the process hibernate:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_receive_loop">Receive loop</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Once initialized, Cowboy will wait for messages to arrive
-in the process' mailbox. When a message arrives, Cowboy
-calls the <code>info/3</code> function with the message, the Req object
-and the handler’s state.</p></div>
-<div class="paragraph"><p>The following snippet sends a reply when it receives a
-<code>reply</code> message from another process, or waits for another
-message otherwise.</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: #000000">info</span></span>({<span style="color: #FF6600">reply</span>, <span style="color: #009900">Body</span>}, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{}, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">_Msg</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Do note that the <code>reply</code> tuple here may be any message
-and is simply an example.</p></div>
-<div class="paragraph"><p>This callback may perform any necessary operation including
-sending all or parts of a reply, and will subsequently
-return a tuple indicating if more messages are to be expected.</p></div>
-<div class="paragraph"><p>The callback may also choose to do nothing at all and just
-skip the message received.</p></div>
-<div class="paragraph"><p>If a reply is sent, then the <code>stop</code> tuple should be returned.
-This will instruct Cowboy to end the request.</p></div>
-<div class="paragraph"><p>Otherwise an <code>ok</code> tuple should be returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_streaming_loop">Streaming loop</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Another common case well suited for loop handlers is
-streaming data received in the form of Erlang messages.
-This can be done by initiating a chunked reply in the
-<code>init/2</code> callback and then using <code>cowboy_req:chunk/2</code>
-every time a message is received.</p></div>
-<div class="paragraph"><p>The following snippet does exactly that. As you can see
-a chunk is sent every time an <code>event</code> message is received,
-and the loop is stopped by sending an <code>eof</code> message.</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #FF6600">eof</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>({<span style="color: #FF6600">event</span>, <span style="color: #009900">Data</span>}, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">_Msg</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cleaning_up">Cleaning up</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is recommended that you set the connection header to
-<code>close</code> when replying, as this process may be reused for
-a subsequent request.</p></div>
-<div class="paragraph"><p>Please refer to the <a href="../handlers">Handlers chapter</a>
-for general instructions about cleaning up.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hibernate">Hibernate</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To save memory, you may hibernate the process in between
-messages received. This is done by returning the atom
-<code>hibernate</code> as part of the <code>loop</code> tuple callbacks normally
-return. Just add the atom at the end and Cowboy will hibernate
-accordingly.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Loop handlers are a special kind of HTTP handlers used when the +response can not be sent right away. The handler enters instead +a receive loop waiting for the right message before it can send +a response.</p></div> +<div class="paragraph"><p>Loop handlers are used for requests where a response might not +be immediately available, but where you would like to keep the +connection open for a while in case the response arrives. The +most known example of such practice is known as long polling.</p></div> +<div class="paragraph"><p>Loop handlers can also be used for requests where a response is +partially available and you need to stream the response body +while the connection is open. The most known example of such +practice is server-sent events.</p></div> +<div class="paragraph"><p>While the same can be accomplished using plain HTTP handlers, +it is recommended to use loop handlers because they are well-tested +and allow using built-in features like hibernation and timeouts.</p></div> +<div class="paragraph"><p>Loop handlers essentially wait for one or more Erlang messages +and feed these messages to the <code>info/3</code> callback. It also features +the <code>init/2</code> and <code>terminate/3</code> callbacks which work the same as +for plain HTTP handlers.</p></div> +<div class="sect1"> +<h2 id="_initialization">Initialization</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>init/2</code> function must return a <code>cowboy_loop</code> tuple to enable +loop handler behavior. This tuple may optionally contain +a timeout value and/or the atom <code>hibernate</code> to make the +process enter hibernation until a message is received.</p></div> +<div class="paragraph"><p>This snippet enables the loop handler:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This also makes the process hibernate:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_receive_loop">Receive loop</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Once initialized, Cowboy will wait for messages to arrive +in the process' mailbox. When a message arrives, Cowboy +calls the <code>info/3</code> function with the message, the Req object +and the handler’s state.</p></div> +<div class="paragraph"><p>The following snippet sends a reply when it receives a +<code>reply</code> message from another process, or waits for another +message otherwise.</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: #000000">info</span></span>({<span style="color: #FF6600">reply</span>, <span style="color: #009900">Body</span>}, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{}, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>), + {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">_Msg</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Do note that the <code>reply</code> tuple here may be any message +and is simply an example.</p></div> +<div class="paragraph"><p>This callback may perform any necessary operation including +sending all or parts of a reply, and will subsequently +return a tuple indicating if more messages are to be expected.</p></div> +<div class="paragraph"><p>The callback may also choose to do nothing at all and just +skip the message received.</p></div> +<div class="paragraph"><p>If a reply is sent, then the <code>stop</code> tuple should be returned. +This will instruct Cowboy to end the request.</p></div> +<div class="paragraph"><p>Otherwise an <code>ok</code> tuple should be returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_streaming_loop">Streaming loop</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Another common case well suited for loop handlers is +streaming data received in the form of Erlang messages. +This can be done by initiating a chunked reply in the +<code>init/2</code> callback and then using <code>cowboy_req:chunk/2</code> +every time a message is received.</p></div> +<div class="paragraph"><p>The following snippet does exactly that. As you can see +a chunk is sent every time an <code>event</code> message is received, +and the loop is stopped by sending an <code>eof</code> message.</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req</span>), + {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #FF6600">eof</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">info</span></span>({<span style="color: #FF6600">event</span>, <span style="color: #009900">Data</span>}, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">_Msg</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_cleaning_up">Cleaning up</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is recommended that you set the connection header to +<code>close</code> when replying, as this process may be reused for +a subsequent request.</p></div> +<div class="paragraph"><p>Please refer to the <a href="../handlers">Handlers chapter</a> +for general instructions about cleaning up.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hibernate">Hibernate</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To save memory, you may hibernate the process in between +messages received. This is done by returning the atom +<code>hibernate</code> as part of the <code>loop</code> tuple callbacks normally +return. Just add the atom at the end and Cowboy will hibernate +accordingly.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/middlewares/index.html b/docs/en/cowboy/2.0/guide/middlewares/index.html index bb0a2a0c..5569e6f5 100644 --- a/docs/en/cowboy/2.0/guide/middlewares/index.html +++ b/docs/en/cowboy/2.0/guide/middlewares/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Middlewares</title> @@ -67,98 +67,101 @@ <h1 class="lined-header"><span>Middlewares</span></h1> -<div class="paragraph"><p>Cowboy delegates the request processing to middleware components.
-By default, two middlewares are defined, for the routing and handling
-of the request, as is detailed in most of this guide.</p></div>
-<div class="paragraph"><p>Middlewares give you complete control over how requests are to be
-processed. You can add your own middlewares to the mix or completely
-change the chain of middlewares as needed.</p></div>
-<div class="paragraph"><p>Cowboy will execute all middlewares in the given order, unless one
-of them decides to stop processing.</p></div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Middlewares only need to implement a single callback: <code>execute/2</code>.
-It is defined in the <code>cowboy_middleware</code> behavior.</p></div>
-<div class="paragraph"><p>This callback has two arguments. The first is the <code>Req</code> object.
-The second is the environment.</p></div>
-<div class="paragraph"><p>Middlewares can return one of three different values:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>{ok, Req, Env}</code> to continue the request processing
-</p>
-</li>
-<li>
-<p>
-<code>{suspend, Module, Function, Args}</code> to hibernate
-</p>
-</li>
-<li>
-<p>
-<code>{stop, Req}</code> to stop processing and move on to the next request
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Of note is that when hibernating, processing will resume on the given
-MFA, discarding all previous stacktrace. Make sure you keep the <code>Req</code>
-and <code>Env</code> in the arguments of this MFA for later use.</p></div>
-<div class="paragraph"><p>If an error happens during middleware processing, Cowboy will not try
-to send an error back to the socket, the process will just crash. It
-is up to the middleware to make sure that a reply is sent if something
-goes wrong.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The middleware environment is defined as the <code>env</code> protocol option.
-In the previous chapters we saw it briefly when we needed to pass
-the routing information. It is a list of tuples with the first
-element being an atom and the second any Erlang term.</p></div>
-<div class="paragraph"><p>Two values in the environment are reserved:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>listener</code> contains the name of the listener
-</p>
-</li>
-<li>
-<p>
-<code>result</code> contains the result of the processing
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The <code>listener</code> value is always defined. The <code>result</code> value can be
-set by any middleware. If set to anything other than <code>ok</code>, Cowboy
-will not process any subsequent requests on this connection.</p></div>
-<div class="paragraph"><p>The middlewares that come with Cowboy may define or require other
-environment values to perform.</p></div>
-<div class="paragraph"><p>You can update the environment by calling the <code>cowboy:set_env/3</code>
-convenience function, adding or replacing a value in the environment.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_routing_middleware">Routing middleware</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The routing middleware requires the <code>dispatch</code> value. If routing
-succeeds, it will put the handler name and options in the <code>handler</code>
-and <code>handler_opts</code> values of the environment, respectively.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_handler_middleware">Handler middleware</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The handler middleware requires the <code>handler</code> and <code>handler_opts</code>
-values. It puts the result of the request handling into <code>result</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy delegates the request processing to middleware components. +By default, two middlewares are defined, for the routing and handling +of the request, as is detailed in most of this guide.</p></div> +<div class="paragraph"><p>Middlewares give you complete control over how requests are to be +processed. You can add your own middlewares to the mix or completely +change the chain of middlewares as needed.</p></div> +<div class="paragraph"><p>Cowboy will execute all middlewares in the given order, unless one +of them decides to stop processing.</p></div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Middlewares only need to implement a single callback: <code>execute/2</code>. +It is defined in the <code>cowboy_middleware</code> behavior.</p></div> +<div class="paragraph"><p>This callback has two arguments. The first is the <code>Req</code> object. +The second is the environment.</p></div> +<div class="paragraph"><p>Middlewares can return one of three different values:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>{ok, Req, Env}</code> to continue the request processing +</p> +</li> +<li> +<p> +<code>{suspend, Module, Function, Args}</code> to hibernate +</p> +</li> +<li> +<p> +<code>{stop, Req}</code> to stop processing and move on to the next request +</p> +</li> +</ul></div> +<div class="paragraph"><p>Of note is that when hibernating, processing will resume on the given +MFA, discarding all previous stacktrace. Make sure you keep the <code>Req</code> +and <code>Env</code> in the arguments of this MFA for later use.</p></div> +<div class="paragraph"><p>If an error happens during middleware processing, Cowboy will not try +to send an error back to the socket, the process will just crash. It +is up to the middleware to make sure that a reply is sent if something +goes wrong.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The middleware environment is defined as the <code>env</code> protocol option. +In the previous chapters we saw it briefly when we needed to pass +the routing information. It is a list of tuples with the first +element being an atom and the second any Erlang term.</p></div> +<div class="paragraph"><p>Two values in the environment are reserved:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>listener</code> contains the name of the listener +</p> +</li> +<li> +<p> +<code>result</code> contains the result of the processing +</p> +</li> +</ul></div> +<div class="paragraph"><p>The <code>listener</code> value is always defined. The <code>result</code> value can be +set by any middleware. If set to anything other than <code>ok</code>, Cowboy +will not process any subsequent requests on this connection.</p></div> +<div class="paragraph"><p>The middlewares that come with Cowboy may define or require other +environment values to perform.</p></div> +<div class="paragraph"><p>You can update the environment by calling the <code>cowboy:set_env/3</code> +convenience function, adding or replacing a value in the environment.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_routing_middleware">Routing middleware</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The routing middleware requires the <code>dispatch</code> value. If routing +succeeds, it will put the handler name and options in the <code>handler</code> +and <code>handler_opts</code> values of the environment, respectively.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_handler_middleware">Handler middleware</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The handler middleware requires the <code>handler</code> and <code>handler_opts</code> +values. It puts the result of the request handling into <code>result</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html b/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html index c10169c4..f7f9492b 100644 --- a/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html +++ b/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Migrating from Cowboy 1.0 to 2.0</title> @@ -67,384 +67,387 @@ <h1 class="lined-header"><span>Migrating from Cowboy 1.0 to 2.0</span></h1> -<div class="paragraph"><p>A lot has changed between Cowboy 1.0 and 2.0. The <code>cowboy_req</code>
-interface in particular has seen a massive revamp. Hooks are
-gone, their functionality can now be achieved via stream
-handlers.</p></div>
-<div class="paragraph"><p>The documentation has seen great work, in particular the
-manual. Each module and each function now has its own dedicated
-manual page with full details and examples.</p></div>
-<div class="sect1">
-<h2 id="_compatibility">Compatibility</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Compatibility with Erlang/OTP R16, 17 and 18 has been dropped.
-Erlang/OTP 19.0 or above is required. It is non-trivial to
-make Cowboy 2.0 work with older Erlang/OTP versions.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 is not compatible with Cowlib versions older than
-2.0. It should be compatible with Ranch 1.0 or above, however
-it has not been tested with Ranch versions older than 1.4.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 is tested on Arch Linux, Ubuntu, FreeBSD, Windows
-and OSX. It is tested with every point release (latest patch
-release) and also with HiPE on the most recent release.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 now comes with Erlang.mk templates.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_features_added">Features added</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The HTTP/2 protocol is now supported.
-</p>
-</li>
-<li>
-<p>
-Cowboy no longer uses only one process per connection.
- It now uses one process per connection plus one process
- per request by default. This is necessary for HTTP/2.
- There might be a slight drop in performance for HTTP/1.1
- connections due to this change.
-</p>
-</li>
-<li>
-<p>
-Cowboy internals have largely been reworked in order to
- support HTTP/2. This opened the way to stream handlers,
- which are a chain of modules that are called whenever
- something happens relating to a request/response.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy_stream_h</code> stream handler has been added.
- It provides most of Cowboy’s default behavior.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy_compress_h</code> stream handler has been added.
- It compresses responses when possible. It’s worth noting
- that it compresses in more cases than Cowboy 1.0 ever did.
-</p>
-</li>
-<li>
-<p>
-Because of the many changes in the internals of Cowboy,
- many options have been added or modified. Of note is that
- the Websocket options are now given per handler rather
- than for the entire listener.
-</p>
-</li>
-<li>
-<p>
-Websocket permessage-deflate compression is now supported
- via the <code>compress</code> option.
-</p>
-</li>
-<li>
-<p>
-Static file handlers will now correctly find files found
- in <em>.ez</em> archives.
-</p>
-</li>
-<li>
-<p>
-Constraints have been generalized and are now used not only
- in the router but also in some <code>cowboy_req</code> functions. Their
- interface has also been modified to allow for reverse
- operations and formatting of errors.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_features_removed">Features removed</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-SPDY support has been removed. Use HTTP/2 instead.
-</p>
-</li>
-<li>
-<p>
-Hooks have been removed. Use <a href="../streams">stream handlers</a> instead.
-</p>
-</li>
-<li>
-<p>
-The undocumented <code>waiting_stream</code> hack has been removed.
- It allowed disabling chunked transfer-encoding for HTTP/1.1.
- It has no equivalent in Cowboy 2.0. Open a ticket if necessary.
-</p>
-</li>
-<li>
-<p>
-Sub protocols still exist, but their interface has largely changed
- and they are no longer documented for the time being.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changed_behaviors">Changed behaviors</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The handler behaviors have been renamed and are now <code>cowboy_handler</code>,
- <code>cowboy_loop</code>, <code>cowboy_rest</code> and <code>cowboy_websocket</code>.
-</p>
-</li>
-<li>
-<p>
-Plain HTTP, loop, REST and Websocket handlers have had their
- init and terminate callbacks unified. They now all use the
- <code>init/2</code> and <code>terminate/3</code> callbacks. The latter is now optional.
- The terminate reason has now been documented for all handlers.
-</p>
-</li>
-<li>
-<p>
-The tuple returned to switch to a different handler type has
- changed. It now takes the form <code>{Module, Req, State}</code> or
- <code>{Module, Req, State, Opts}</code>, where <code>Opts</code> is a map of options
- to configure the handler. The timeout and hibernate options
- must now be specified using this map, where applicable.
-</p>
-</li>
-<li>
-<p>
-All behaviors that used to accept <code>halt</code> or <code>shutdown</code> tuples
- as a return value no longer do so. The return value is now
- a <code>stop</code> tuple, consistent across Cowboy.
-</p>
-</li>
-<li>
-<p>
-Middlewares can no longer return an <code>error</code> tuple. They have
- to send the response and return a <code>stop</code> tuple instead.
-</p>
-</li>
-<li>
-<p>
-The <code>known_content_type</code> REST handler callback has been removed
- as it was found unnecessary.
-</p>
-</li>
-<li>
-<p>
-Websocket handlers have both the normal <code>init/2</code> and
- an optional <code>websocket_init/1</code> function. The reason for
- that exception is that the <code>websocket_*</code> callbacks execute
- in a separate process from the <code>init/2</code> callback, and it
- was therefore not obvious how timers or monitors should
- be setup properly. They are effectively initializing the
- handler before and after the HTTP/1.1 upgrade.
-</p>
-</li>
-<li>
-<p>
-Websocket handlers can now send frames directly from
- <code>websocket_init/1</code>. The frames will be sent immediately
- after the handshake.
-</p>
-</li>
-<li>
-<p>
-Websocket handler callbacks no longer receive the Req
- argument. The <code>init/2</code> callback still receives it and
- can be used to extract relevant information. The <code>terminate/3</code>
- callback, if implemented, may still receive the Req
- (see next bullet point).
-</p>
-</li>
-<li>
-<p>
-Websocket handlers have a new <code>req_filter</code> option that
- can be used to customize how much information should be
- discarded from the Req object after the handshake. Note
- that the Req object is only available in <code>terminate/3</code>
- past that point.
-</p>
-</li>
-<li>
-<p>
-Websocket handlers have their timeout default changed
- from infinity to 60 seconds.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_new_functions">New functions</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The <code>cowboy_req:scheme/1</code> function has been added.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy_req:uri/1,2</code> function has been added, replacing the
- less powerful functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code>.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:match_qs/2</code> and <code>cowboy_req:match_cookies/2</code>
- allow matching query string and cookies against constraints.
-</p>
-</li>
-<li>
-<p>
-The function <code>cowboy_req:set_resp_cookie/3</code> has been added to
- complement <code>cowboy_req:set_resp_cookie/4</code>.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:resp_header/2,3</code> and <code>cowboy_req:resp_headers/1</code>
- have been added. They can be used to retrieve response headers
- that were previously set.
-</p>
-</li>
-<li>
-<p>
-The function <code>cowboy_req:set_resp_headers/2</code> has been added. It
- allows setting many response headers at once.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:push/3,4</code> can be used to push resources
- for protocols that support it (by default only HTTP/2).
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changed_functions">Changed functions</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The <code>cowboy:start_http/4</code> function was renamed to <code>cowboy:start_clear/3</code>.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy:start_https/4</code> function was renamed to <code>cowboy:start_tls/3</code>.
-</p>
-</li>
-<li>
-<p>
-Most, if not all, functions in the <code>cowboy_req</code> module have been modified.
- Please consult the changelog of each individual functions. The changes
- are mainly about simplifying and clarifying the interface. The Req is no
- longer returned when not necessary, maps are used wherever possible,
- and some functions have been renamed.
-</p>
-</li>
-<li>
-<p>
-The position of the <code>Opts</code> argument for <code>cowboy_req:set_resp_cookie/4</code>
- has changed to improve consistency. It is now the last argument.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_removed_functions">Removed functions</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code> have been
- removed in favor of the new function <code>cowboy_req:uri/1,2</code>.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:meta/2,3</code> and <code>cowboy_req:set_meta/3</code> have
- been removed. The Req object is now a public map, therefore they became
- unnecessary.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:set_resp_body_fun/2,3</code> have been removed.
- For sending files, the function <code>cowboy_req:set_resp_body/2</code> can now
- take a sendfile tuple.
-</p>
-</li>
-<li>
-<p>
-Remove many undocumented functions from <code>cowboy_req</code>, including the
- functions <code>cowboy_req:get/2</code> and <code>cowboy_req:set/3</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_other_changes">Other changes</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The correct percent-decoding algorithm is now used for path elements
- during routing. It will no longer decode <code>+</code> characters.
-</p>
-</li>
-<li>
-<p>
-The router will now properly handle path segments <code>.</code> and <code>..</code>.
-</p>
-</li>
-<li>
-<p>
-Routing behavior has changed for URIs containing latin1 characters.
- They are no longer allowed. URIs are expected to be in UTF-8 once
- they are percent-decoded.
-</p>
-</li>
-<li>
-<p>
-Etag comparison in REST handlers has been fixed. Some requests may
- now fail when they succeeded in the past.
-</p>
-</li>
-<li>
-<p>
-The <code>If-*-Since</code> headers are now ignored in REST handlers if
- the corresponding <code>If*-Match</code> header exist. The former is
- largely a backward compatible header and this shouldn’t create
- any issue. The new behavior follows the current RFCs more closely.
-</p>
-</li>
-<li>
-<p>
-The static file handler has been improved to handle more special
- characters on systems that accept them.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="paragraph"><p>A lot has changed between Cowboy 1.0 and 2.0. The <code>cowboy_req</code> +interface in particular has seen a massive revamp. Hooks are +gone, their functionality can now be achieved via stream +handlers.</p></div> +<div class="paragraph"><p>The documentation has seen great work, in particular the +manual. Each module and each function now has its own dedicated +manual page with full details and examples.</p></div> +<div class="sect1"> +<h2 id="_compatibility">Compatibility</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Compatibility with Erlang/OTP R16, 17 and 18 has been dropped. +Erlang/OTP 19.0 or above is required. It is non-trivial to +make Cowboy 2.0 work with older Erlang/OTP versions.</p></div> +<div class="paragraph"><p>Cowboy 2.0 is not compatible with Cowlib versions older than +2.0. It should be compatible with Ranch 1.0 or above, however +it has not been tested with Ranch versions older than 1.4.</p></div> +<div class="paragraph"><p>Cowboy 2.0 is tested on Arch Linux, Ubuntu, FreeBSD, Windows +and OSX. It is tested with every point release (latest patch +release) and also with HiPE on the most recent release.</p></div> +<div class="paragraph"><p>Cowboy 2.0 now comes with Erlang.mk templates.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_features_added">Features added</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The HTTP/2 protocol is now supported. +</p> +</li> +<li> +<p> +Cowboy no longer uses only one process per connection. + It now uses one process per connection plus one process + per request by default. This is necessary for HTTP/2. + There might be a slight drop in performance for HTTP/1.1 + connections due to this change. +</p> +</li> +<li> +<p> +Cowboy internals have largely been reworked in order to + support HTTP/2. This opened the way to stream handlers, + which are a chain of modules that are called whenever + something happens relating to a request/response. +</p> +</li> +<li> +<p> +The <code>cowboy_stream_h</code> stream handler has been added. + It provides most of Cowboy’s default behavior. +</p> +</li> +<li> +<p> +The <code>cowboy_compress_h</code> stream handler has been added. + It compresses responses when possible. It’s worth noting + that it compresses in more cases than Cowboy 1.0 ever did. +</p> +</li> +<li> +<p> +Because of the many changes in the internals of Cowboy, + many options have been added or modified. Of note is that + the Websocket options are now given per handler rather + than for the entire listener. +</p> +</li> +<li> +<p> +Websocket permessage-deflate compression is now supported + via the <code>compress</code> option. +</p> +</li> +<li> +<p> +Static file handlers will now correctly find files found + in <em>.ez</em> archives. +</p> +</li> +<li> +<p> +Constraints have been generalized and are now used not only + in the router but also in some <code>cowboy_req</code> functions. Their + interface has also been modified to allow for reverse + operations and formatting of errors. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_features_removed">Features removed</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +SPDY support has been removed. Use HTTP/2 instead. +</p> +</li> +<li> +<p> +Hooks have been removed. Use <a href="../streams">stream handlers</a> instead. +</p> +</li> +<li> +<p> +The undocumented <code>waiting_stream</code> hack has been removed. + It allowed disabling chunked transfer-encoding for HTTP/1.1. + It has no equivalent in Cowboy 2.0. Open a ticket if necessary. +</p> +</li> +<li> +<p> +Sub protocols still exist, but their interface has largely changed + and they are no longer documented for the time being. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changed_behaviors">Changed behaviors</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The handler behaviors have been renamed and are now <code>cowboy_handler</code>, + <code>cowboy_loop</code>, <code>cowboy_rest</code> and <code>cowboy_websocket</code>. +</p> +</li> +<li> +<p> +Plain HTTP, loop, REST and Websocket handlers have had their + init and terminate callbacks unified. They now all use the + <code>init/2</code> and <code>terminate/3</code> callbacks. The latter is now optional. + The terminate reason has now been documented for all handlers. +</p> +</li> +<li> +<p> +The tuple returned to switch to a different handler type has + changed. It now takes the form <code>{Module, Req, State}</code> or + <code>{Module, Req, State, Opts}</code>, where <code>Opts</code> is a map of options + to configure the handler. The timeout and hibernate options + must now be specified using this map, where applicable. +</p> +</li> +<li> +<p> +All behaviors that used to accept <code>halt</code> or <code>shutdown</code> tuples + as a return value no longer do so. The return value is now + a <code>stop</code> tuple, consistent across Cowboy. +</p> +</li> +<li> +<p> +Middlewares can no longer return an <code>error</code> tuple. They have + to send the response and return a <code>stop</code> tuple instead. +</p> +</li> +<li> +<p> +The <code>known_content_type</code> REST handler callback has been removed + as it was found unnecessary. +</p> +</li> +<li> +<p> +Websocket handlers have both the normal <code>init/2</code> and + an optional <code>websocket_init/1</code> function. The reason for + that exception is that the <code>websocket_*</code> callbacks execute + in a separate process from the <code>init/2</code> callback, and it + was therefore not obvious how timers or monitors should + be setup properly. They are effectively initializing the + handler before and after the HTTP/1.1 upgrade. +</p> +</li> +<li> +<p> +Websocket handlers can now send frames directly from + <code>websocket_init/1</code>. The frames will be sent immediately + after the handshake. +</p> +</li> +<li> +<p> +Websocket handler callbacks no longer receive the Req + argument. The <code>init/2</code> callback still receives it and + can be used to extract relevant information. The <code>terminate/3</code> + callback, if implemented, may still receive the Req + (see next bullet point). +</p> +</li> +<li> +<p> +Websocket handlers have a new <code>req_filter</code> option that + can be used to customize how much information should be + discarded from the Req object after the handshake. Note + that the Req object is only available in <code>terminate/3</code> + past that point. +</p> +</li> +<li> +<p> +Websocket handlers have their timeout default changed + from infinity to 60 seconds. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_new_functions">New functions</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The <code>cowboy_req:scheme/1</code> function has been added. +</p> +</li> +<li> +<p> +The <code>cowboy_req:uri/1,2</code> function has been added, replacing the + less powerful functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code>. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:match_qs/2</code> and <code>cowboy_req:match_cookies/2</code> + allow matching query string and cookies against constraints. +</p> +</li> +<li> +<p> +The function <code>cowboy_req:set_resp_cookie/3</code> has been added to + complement <code>cowboy_req:set_resp_cookie/4</code>. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:resp_header/2,3</code> and <code>cowboy_req:resp_headers/1</code> + have been added. They can be used to retrieve response headers + that were previously set. +</p> +</li> +<li> +<p> +The function <code>cowboy_req:set_resp_headers/2</code> has been added. It + allows setting many response headers at once. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:push/3,4</code> can be used to push resources + for protocols that support it (by default only HTTP/2). +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changed_functions">Changed functions</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The <code>cowboy:start_http/4</code> function was renamed to <code>cowboy:start_clear/3</code>. +</p> +</li> +<li> +<p> +The <code>cowboy:start_https/4</code> function was renamed to <code>cowboy:start_tls/3</code>. +</p> +</li> +<li> +<p> +Most, if not all, functions in the <code>cowboy_req</code> module have been modified. + Please consult the changelog of each individual functions. The changes + are mainly about simplifying and clarifying the interface. The Req is no + longer returned when not necessary, maps are used wherever possible, + and some functions have been renamed. +</p> +</li> +<li> +<p> +The position of the <code>Opts</code> argument for <code>cowboy_req:set_resp_cookie/4</code> + has changed to improve consistency. It is now the last argument. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_removed_functions">Removed functions</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code> have been + removed in favor of the new function <code>cowboy_req:uri/1,2</code>. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:meta/2,3</code> and <code>cowboy_req:set_meta/3</code> have + been removed. The Req object is now a public map, therefore they became + unnecessary. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:set_resp_body_fun/2,3</code> have been removed. + For sending files, the function <code>cowboy_req:set_resp_body/2</code> can now + take a sendfile tuple. +</p> +</li> +<li> +<p> +Remove many undocumented functions from <code>cowboy_req</code>, including the + functions <code>cowboy_req:get/2</code> and <code>cowboy_req:set/3</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_other_changes">Other changes</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The correct percent-decoding algorithm is now used for path elements + during routing. It will no longer decode <code>+</code> characters. +</p> +</li> +<li> +<p> +The router will now properly handle path segments <code>.</code> and <code>..</code>. +</p> +</li> +<li> +<p> +Routing behavior has changed for URIs containing latin1 characters. + They are no longer allowed. URIs are expected to be in UTF-8 once + they are percent-decoded. +</p> +</li> +<li> +<p> +Etag comparison in REST handlers has been fixed. Some requests may + now fail when they succeeded in the past. +</p> +</li> +<li> +<p> +The <code>If-*-Since</code> headers are now ignored in REST handlers if + the corresponding <code>If*-Match</code> header exist. The former is + largely a backward compatible header and this shouldn’t create + any issue. The new behavior follows the current RFCs more closely. +</p> +</li> +<li> +<p> +The static file handler has been improved to handle more special + characters on systems that accept them. +</p> +</li> +</ul></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/modern_web.asciidoc b/docs/en/cowboy/2.0/guide/modern_web.asciidoc index 6c43adb0..48525732 100644 --- a/docs/en/cowboy/2.0/guide/modern_web.asciidoc +++ b/docs/en/cowboy/2.0/guide/modern_web.asciidoc @@ -1,8 +1,6 @@ [[modern_web]] == The modern Web -// @todo Link to related xrefs. - Cowboy is a server for the modern Web. This chapter explains what it means and details all the standards involved. @@ -56,9 +54,9 @@ methods, status codes, headers or semantics. === Websocket -Websocket is a protocol built on top of HTTP/1.1 that provides -a two-ways communication channel between the client and the -server. Communication is asynchronous and can occur concurrently. +xref:ws_protocol[Websocket] is a protocol built on top of HTTP/1.1 +that provides a two-ways communication channel between the client and +the server. Communication is asynchronous and can occur concurrently. It consists of a Javascript object allowing setting up a Websocket connection to the server, and a binary based @@ -79,6 +77,9 @@ is closer to TCP in that aspect, and requires you to design and implement your own protocol on top of it; or adapt an existing protocol to Websocket. +Cowboy provides an interface known as xref:ws_handlers[Websocket handlers] +that gives complete control over a Websocket connection. + The Websocket protocol is defined by RFC 6455. === Long-lived requests @@ -101,21 +102,21 @@ type, `text/event-stream`, along with a new HTTP header, `Last-Event-ID`. It is defined in the EventSource W3C specification. -Cowboy provides an interface known as loop handlers that -facilitates the implementation of long-polling or stream +Cowboy provides an interface known as xref:loop_handlers[loop handlers] +that facilitates the implementation of long-polling or stream mechanisms. It works regardless of the underlying protocol. === REST -REST, or REpresentational State Transfer, is a style of -architecture for loosely connected distributed systems. -It can easily be implemented on top of HTTP. +xref:rest_principles[REST, or REpresentational State Transfer], +is a style of architecture for loosely connected distributed +systems. It can easily be implemented on top of HTTP. REST is essentially a set of constraints to be followed. Many of these constraints are purely architectural and solved by simply using HTTP. Some constraints must be explicitly followed by the developer. -Cowboy provides an interface known as REST handlers that -simplifies the implementation of a REST API on top of +Cowboy provides an interface known as xref:rest_handlers[REST handlers] +that simplifies the implementation of a REST API on top of the HTTP protocol. diff --git a/docs/en/cowboy/2.0/guide/modern_web/index.html b/docs/en/cowboy/2.0/guide/modern_web/index.html index 62aef447..2bbf1072 100644 --- a/docs/en/cowboy/2.0/guide/modern_web/index.html +++ b/docs/en/cowboy/2.0/guide/modern_web/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The modern Web</title> @@ -67,119 +67,124 @@ <h1 class="lined-header"><span>The modern Web</span></h1> -<div class="paragraph"><p>Cowboy is a server for the modern Web. This chapter explains
-what it means and details all the standards involved.</p></div>
-<div class="paragraph"><p>Cowboy supports all the standards listed in this document.</p></div>
-<div class="sect1">
-<h2 id="_http_2">HTTP/2</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP/2 is the most efficient protocol for consuming Web
-services. It enables clients to keep a connection open
-for long periods of time; to send requests concurrently;
-to reduce the size of requests through HTTP headers
-compression; and more. The protocol is binary, greatly
-reducing the resources needed to parse it.</p></div>
-<div class="paragraph"><p>HTTP/2 also enables the server to push messages to the
-client. This can be used for various purposes, including
-the sending of related resources before the client requests
-them, in an effort to reduce latency. This can also be used
-to enable bidirectional communication.</p></div>
-<div class="paragraph"><p>Cowboy provides transparent support for HTTP/2. Clients
-that know it can use it; others fall back to HTTP/1.1
-automatically.</p></div>
-<div class="paragraph"><p>HTTP/2 is compatible with the HTTP/1.1 semantics.</p></div>
-<div class="paragraph"><p>HTTP/2 is defined by RFC 7540 and RFC 7541.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_http_1_1">HTTP/1.1</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP/1.1 is the previous version of the HTTP protocol.
-The protocol itself is text-based and suffers from numerous
-issues and limitations. In particular it is not possible
-to execute requests concurrently (though pipelining is
-sometimes possible), and it’s also sometimes difficult
-to detect that a client disconnected.</p></div>
-<div class="paragraph"><p>HTTP/1.1 does provide very good semantics for interacting
-with Web services. It defines the standard methods, headers
-and status codes used by HTTP/1.1 and HTTP/2 clients and
-servers.</p></div>
-<div class="paragraph"><p>HTTP/1.1 also defines compatibility with an older version
-of the protocol, HTTP/1.0, which was never really standardized
-across implementations.</p></div>
-<div class="paragraph"><p>The core of HTTP/1.1 is defined by RFC 7230, RFC 7231,
-RFC 7232, RFC 7233, RFC 7234 and RFC 7235. Numerous RFCs
-and other specifications exist defining additional HTTP
-methods, status codes, headers or semantics.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_websocket">Websocket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket is a protocol built on top of HTTP/1.1 that provides
-a two-ways communication channel between the client and the
-server. Communication is asynchronous and can occur concurrently.</p></div>
-<div class="paragraph"><p>It consists of a Javascript object allowing setting up a
-Websocket connection to the server, and a binary based
-protocol for sending data to the server or the client.</p></div>
-<div class="paragraph"><p>Websocket connections can transfer either UTF-8 encoded text
-data or binary data. The protocol also includes support for
-implementing a ping/pong mechanism, allowing the server and
-the client to have more confidence that the connection is still
-alive.</p></div>
-<div class="paragraph"><p>A Websocket connection can be used to transfer any kind of data,
-small or big, text or binary. Because of this Websocket is
-sometimes used for communication between systems.</p></div>
-<div class="paragraph"><p>Websocket messages have no semantics on their own. Websocket
-is closer to TCP in that aspect, and requires you to design
-and implement your own protocol on top of it; or adapt an
-existing protocol to Websocket.</p></div>
-<div class="paragraph"><p>The Websocket protocol is defined by RFC 6455.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_long_lived_requests">Long-lived requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides an interface that can be used to support
-long-polling or to stream large amounts of data reliably,
-including using Server-Sent Events.</p></div>
-<div class="paragraph"><p>Long-polling is a mechanism in which the client performs
-a request which may not be immediately answered by the
-server. It allows clients to request resources that may
-not currently exist, but are expected to be created soon,
-and which will be returned as soon as they are.</p></div>
-<div class="paragraph"><p>Long-polling is essentially a hack, but it is widely used
-to overcome limitations on older clients and servers.</p></div>
-<div class="paragraph"><p>Server-Sent Events is a small protocol defined as a media
-type, <code>text/event-stream</code>, along with a new HTTP header,
-<code>Last-Event-ID</code>. It is defined in the EventSource W3C
-specification.</p></div>
-<div class="paragraph"><p>Cowboy provides an interface known as loop handlers that
-facilitates the implementation of long-polling or stream
-mechanisms. It works regardless of the underlying protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest">REST</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>REST, or REpresentational State Transfer, is a style of
-architecture for loosely connected distributed systems.
-It can easily be implemented on top of HTTP.</p></div>
-<div class="paragraph"><p>REST is essentially a set of constraints to be followed.
-Many of these constraints are purely architectural and
-solved by simply using HTTP. Some constraints must be
-explicitly followed by the developer.</p></div>
-<div class="paragraph"><p>Cowboy provides an interface known as REST handlers that
-simplifies the implementation of a REST API on top of
-the HTTP protocol.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy is a server for the modern Web. This chapter explains +what it means and details all the standards involved.</p></div> +<div class="paragraph"><p>Cowboy supports all the standards listed in this document.</p></div> +<div class="sect1"> +<h2 id="_http_2">HTTP/2</h2> +<div class="sectionbody"> +<div class="paragraph"><p>HTTP/2 is the most efficient protocol for consuming Web +services. It enables clients to keep a connection open +for long periods of time; to send requests concurrently; +to reduce the size of requests through HTTP headers +compression; and more. The protocol is binary, greatly +reducing the resources needed to parse it.</p></div> +<div class="paragraph"><p>HTTP/2 also enables the server to push messages to the +client. This can be used for various purposes, including +the sending of related resources before the client requests +them, in an effort to reduce latency. This can also be used +to enable bidirectional communication.</p></div> +<div class="paragraph"><p>Cowboy provides transparent support for HTTP/2. Clients +that know it can use it; others fall back to HTTP/1.1 +automatically.</p></div> +<div class="paragraph"><p>HTTP/2 is compatible with the HTTP/1.1 semantics.</p></div> +<div class="paragraph"><p>HTTP/2 is defined by RFC 7540 and RFC 7541.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_http_1_1">HTTP/1.1</h2> +<div class="sectionbody"> +<div class="paragraph"><p>HTTP/1.1 is the previous version of the HTTP protocol. +The protocol itself is text-based and suffers from numerous +issues and limitations. In particular it is not possible +to execute requests concurrently (though pipelining is +sometimes possible), and it’s also sometimes difficult +to detect that a client disconnected.</p></div> +<div class="paragraph"><p>HTTP/1.1 does provide very good semantics for interacting +with Web services. It defines the standard methods, headers +and status codes used by HTTP/1.1 and HTTP/2 clients and +servers.</p></div> +<div class="paragraph"><p>HTTP/1.1 also defines compatibility with an older version +of the protocol, HTTP/1.0, which was never really standardized +across implementations.</p></div> +<div class="paragraph"><p>The core of HTTP/1.1 is defined by RFC 7230, RFC 7231, +RFC 7232, RFC 7233, RFC 7234 and RFC 7235. Numerous RFCs +and other specifications exist defining additional HTTP +methods, status codes, headers or semantics.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_websocket">Websocket</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../ws_protocol">Websocket</a> is a protocol built on top of HTTP/1.1 +that provides a two-ways communication channel between the client and +the server. Communication is asynchronous and can occur concurrently.</p></div> +<div class="paragraph"><p>It consists of a Javascript object allowing setting up a +Websocket connection to the server, and a binary based +protocol for sending data to the server or the client.</p></div> +<div class="paragraph"><p>Websocket connections can transfer either UTF-8 encoded text +data or binary data. The protocol also includes support for +implementing a ping/pong mechanism, allowing the server and +the client to have more confidence that the connection is still +alive.</p></div> +<div class="paragraph"><p>A Websocket connection can be used to transfer any kind of data, +small or big, text or binary. Because of this Websocket is +sometimes used for communication between systems.</p></div> +<div class="paragraph"><p>Websocket messages have no semantics on their own. Websocket +is closer to TCP in that aspect, and requires you to design +and implement your own protocol on top of it; or adapt an +existing protocol to Websocket.</p></div> +<div class="paragraph"><p>Cowboy provides an interface known as <a href="../ws_handlers">Websocket handlers</a> +that gives complete control over a Websocket connection.</p></div> +<div class="paragraph"><p>The Websocket protocol is defined by RFC 6455.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_long_lived_requests">Long-lived requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides an interface that can be used to support +long-polling or to stream large amounts of data reliably, +including using Server-Sent Events.</p></div> +<div class="paragraph"><p>Long-polling is a mechanism in which the client performs +a request which may not be immediately answered by the +server. It allows clients to request resources that may +not currently exist, but are expected to be created soon, +and which will be returned as soon as they are.</p></div> +<div class="paragraph"><p>Long-polling is essentially a hack, but it is widely used +to overcome limitations on older clients and servers.</p></div> +<div class="paragraph"><p>Server-Sent Events is a small protocol defined as a media +type, <code>text/event-stream</code>, along with a new HTTP header, +<code>Last-Event-ID</code>. It is defined in the EventSource W3C +specification.</p></div> +<div class="paragraph"><p>Cowboy provides an interface known as <a href="../loop_handlers">loop handlers</a> +that facilitates the implementation of long-polling or stream +mechanisms. It works regardless of the underlying protocol.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rest">REST</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../rest_principles">REST, or REpresentational State Transfer</a>, +is a style of architecture for loosely connected distributed +systems. It can easily be implemented on top of HTTP.</p></div> +<div class="paragraph"><p>REST is essentially a set of constraints to be followed. +Many of these constraints are purely architectural and +solved by simply using HTTP. Some constraints must be +explicitly followed by the developer.</p></div> +<div class="paragraph"><p>Cowboy provides an interface known as <a href="../rest_handlers">REST handlers</a> +that simplifies the implementation of a REST API on top of +the HTTP protocol.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/multipart.asciidoc b/docs/en/cowboy/2.0/guide/multipart.asciidoc index 756d3b46..0825244c 100644 --- a/docs/en/cowboy/2.0/guide/multipart.asciidoc +++ b/docs/en/cowboy/2.0/guide/multipart.asciidoc @@ -112,9 +112,9 @@ multipart(Req0) -> stream_file(Req0) -> case cowboy_req:read_part_body(Req0) of - {ok, _Body, Req} -> + {ok, _LastBodyChunk, Req} -> Req; - {more, _Body, Req} -> + {more, _BodyChunk, Req} -> stream_file(Req) end. ---- diff --git a/docs/en/cowboy/2.0/guide/multipart/index.html b/docs/en/cowboy/2.0/guide/multipart/index.html index cc53b55d..4f173126 100644 --- a/docs/en/cowboy/2.0/guide/multipart/index.html +++ b/docs/en/cowboy/2.0/guide/multipart/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Multipart requests</title> @@ -67,175 +67,178 @@ <h1 class="lined-header"><span>Multipart requests</span></h1> -<div class="paragraph"><p>Multipart originates from MIME, an Internet standard that
-extends the format of emails.</p></div>
-<div class="paragraph"><p>A multipart message is a list of parts. A part contains
-headers and a body. The body of the parts may be
-of any media type, and contain text or binary data.
-It is possible for parts to contain a multipart media
-type.</p></div>
-<div class="paragraph"><p>In the context of HTTP, multipart is most often used
-with the <code>multipart/form-data</code> media type. It is what
-browsers use to upload files through HTML forms.</p></div>
-<div class="paragraph"><p>The <code>multipart/byteranges</code> is also common. It is the
-media type used to send arbitrary bytes from a resource,
-enabling clients to resume downloads.</p></div>
-<div class="sect1">
-<h2 id="_form_data">Form-data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In the normal case, when a form is submitted, the
-browser will use the <code>application/x-www-form-urlencoded</code>
-content-type. This type is just a list of keys and
-values and is therefore not fit for uploading files.</p></div>
-<div class="paragraph"><p>That’s where the <code>multipart/form-data</code> content-type
-comes in. When the form is configured to use this
-content-type, the browser will create a multipart
-message where each part corresponds to a field on
-the form. For files, it also adds some metadata in
-the part headers, like the file name.</p></div>
-<div class="paragraph"><p>A form with a text input, a file input and a select
-choice box will result in a multipart message with
-three parts, one for each field.</p></div>
-<div class="paragraph"><p>The browser does its best to determine the media type
-of the files it sends this way, but you should not
-rely on it for determining the contents of the file.
-Proper investigation of the contents is recommended.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_checking_for_multipart_messages">Checking for multipart messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The content-type header indicates the presence of
-a multipart message:</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="color: #990000"><<</span><span style="color: #FF0000">"multipart"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"form-data"</span><span style="color: #990000">>></span>, <span style="color: #990000">_</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reading_a_multipart_message">Reading a multipart message</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides two sets of functions for reading
-request bodies as multipart messages.</p></div>
-<div class="paragraph"><p>The <code>cowboy_req:read_part/1,2</code> functions return the
-next part’s headers, if any.</p></div>
-<div class="paragraph"><p>The <code>cowboy_req:read_part_body/1,2</code> functions return
-the current part’s body. For large bodies you may
-need to call the function multiple times.</p></div>
-<div class="paragraph"><p>To read a multipart message you need to iterate over
-all its parts:</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: #000000">multipart</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>),
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req</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>When part bodies are too large, Cowboy will return
-a <code>more</code> tuple, and allow you to loop until the part
-body has been fully read.</p></div>
-<div class="paragraph"><p>The function <code>cow_multipart:form_data/1</code> can be used
-to quickly obtain information about a part from a
-<code>multipart/form-data</code> message. The function returns
-a <code>data</code> or a <code>file</code> tuple depending on whether this
-is a normal field or a file being uploaded.</p></div>
-<div class="paragraph"><p>The following snippet will use this function and
-use different strategies depending on whether the
-part is a file:</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: #000000">multipart</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req</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">cow_multipart:form_data</span></span>(<span style="color: #009900">Headers</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">data</span>, <span style="color: #009900">_FieldName</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>),
- <span style="color: #009900">Req2</span>;
- {<span style="color: #FF6600">file</span>, <span style="color: #009900">_FieldName</span>, <span style="color: #009900">_Filename</span>, <span style="color: #009900">_CType</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req1</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req</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">stream_file</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span>;
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req</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>Both the part header and body reading functions can take
-options that will be given to the request body reading
-functions. By default, <code>cowboy_req:read_part/1</code> reads
-up to 64KB for up to 5 seconds. <code>cowboy_req:read_part_body/1</code>
-has the same defaults as <code>cowboy_req:read_body/1</code>.</p></div>
-<div class="paragraph"><p>To change the defaults for part headers:</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: #000000">cowboy_req:read_part</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">128000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And for part bodies:</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: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">7000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_skipping_unwanted_parts">Skipping unwanted parts</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Part bodies do not have to be read. Cowboy will automatically
-skip it when you request the next part’s body.</p></div>
-<div class="paragraph"><p>The following snippet reads all part headers and skips
-all bodies:</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: #000000">multipart</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req</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>Similarly, if you start reading the body and it ends up
-being too big, you can simply continue with the next part.
-Cowboy will automatically skip what remains.</p></div>
-<div class="paragraph"><p>While Cowboy can skip part bodies automatically, the read
-rate is not configurable. Depending on your application
-you may want to skip manually, in particular if you observe
-poor performance while skipping.</p></div>
-<div class="paragraph"><p>You do not have to read all parts either. You can stop
-reading as soon as you find the data you need.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Multipart originates from MIME, an Internet standard that +extends the format of emails.</p></div> +<div class="paragraph"><p>A multipart message is a list of parts. A part contains +headers and a body. The body of the parts may be +of any media type, and contain text or binary data. +It is possible for parts to contain a multipart media +type.</p></div> +<div class="paragraph"><p>In the context of HTTP, multipart is most often used +with the <code>multipart/form-data</code> media type. It is what +browsers use to upload files through HTML forms.</p></div> +<div class="paragraph"><p>The <code>multipart/byteranges</code> is also common. It is the +media type used to send arbitrary bytes from a resource, +enabling clients to resume downloads.</p></div> +<div class="sect1"> +<h2 id="_form_data">Form-data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In the normal case, when a form is submitted, the +browser will use the <code>application/x-www-form-urlencoded</code> +content-type. This type is just a list of keys and +values and is therefore not fit for uploading files.</p></div> +<div class="paragraph"><p>That’s where the <code>multipart/form-data</code> content-type +comes in. When the form is configured to use this +content-type, the browser will create a multipart +message where each part corresponds to a field on +the form. For files, it also adds some metadata in +the part headers, like the file name.</p></div> +<div class="paragraph"><p>A form with a text input, a file input and a select +choice box will result in a multipart message with +three parts, one for each field.</p></div> +<div class="paragraph"><p>The browser does its best to determine the media type +of the files it sends this way, but you should not +rely on it for determining the contents of the file. +Proper investigation of the contents is recommended.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_checking_for_multipart_messages">Checking for multipart messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The content-type header indicates the presence of +a multipart message:</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="color: #990000"><<</span><span style="color: #FF0000">"multipart"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"form-data"</span><span style="color: #990000">>></span>, <span style="color: #990000">_</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reading_a_multipart_message">Reading a multipart message</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides two sets of functions for reading +request bodies as multipart messages.</p></div> +<div class="paragraph"><p>The <code>cowboy_req:read_part/1,2</code> functions return the +next part’s headers, if any.</p></div> +<div class="paragraph"><p>The <code>cowboy_req:read_part_body/1,2</code> functions return +the current part’s body. For large bodies you may +need to call the function multiple times.</p></div> +<div class="paragraph"><p>To read a multipart message you need to iterate over +all its parts:</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: #000000">multipart</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>), + <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Req</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>When part bodies are too large, Cowboy will return +a <code>more</code> tuple, and allow you to loop until the part +body has been fully read.</p></div> +<div class="paragraph"><p>The function <code>cow_multipart:form_data/1</code> can be used +to quickly obtain information about a part from a +<code>multipart/form-data</code> message. The function returns +a <code>data</code> or a <code>file</code> tuple depending on whether this +is a normal field or a file being uploaded.</p></div> +<div class="paragraph"><p>The following snippet will use this function and +use different strategies depending on whether the +part is a file:</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: #000000">multipart</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Req</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">cow_multipart:form_data</span></span>(<span style="color: #009900">Headers</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">data</span>, <span style="color: #009900">_FieldName</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>), + <span style="color: #009900">Req2</span>; + {<span style="color: #FF6600">file</span>, <span style="color: #009900">_FieldName</span>, <span style="color: #009900">_Filename</span>, <span style="color: #009900">_CType</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req1</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>, + <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Req</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">stream_file</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_LastBodyChunk</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Req</span>; + {<span style="color: #FF6600">more</span>, <span style="color: #009900">_BodyChunk</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req</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>Both the part header and body reading functions can take +options that will be given to the request body reading +functions. By default, <code>cowboy_req:read_part/1</code> reads +up to 64KB for up to 5 seconds. <code>cowboy_req:read_part_body/1</code> +has the same defaults as <code>cowboy_req:read_body/1</code>.</p></div> +<div class="paragraph"><p>To change the defaults for part headers:</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: #000000">cowboy_req:read_part</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">128000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And for part bodies:</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: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">7000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_skipping_unwanted_parts">Skipping unwanted parts</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Part bodies do not have to be read. Cowboy will automatically +skip it when you request the next part’s body.</p></div> +<div class="paragraph"><p>The following snippet reads all part headers and skips +all bodies:</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: #000000">multipart</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Req</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>Similarly, if you start reading the body and it ends up +being too big, you can simply continue with the next part. +Cowboy will automatically skip what remains.</p></div> +<div class="paragraph"><p>While Cowboy can skip part bodies automatically, the read +rate is not configurable. Depending on your application +you may want to skip manually, in particular if you observe +poor performance while skipping.</p></div> +<div class="paragraph"><p>You do not have to read all parts either. You can stop +reading as soon as you find the data you need.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/req/index.html b/docs/en/cowboy/2.0/guide/req/index.html index 6ff5b0a7..bdf6b6b9 100644 --- a/docs/en/cowboy/2.0/guide/req/index.html +++ b/docs/en/cowboy/2.0/guide/req/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The Req object</title> @@ -67,413 +67,416 @@ <h1 class="lined-header"><span>The Req object</span></h1> -<div class="paragraph"><p>The Req object is a variable used for obtaining information
-about a request, read its body or send a response.</p></div>
-<div class="paragraph"><p>It is not really an object in the object-oriented sense.
-It is a simple map that can be directly accessed or
-used when calling functions from the <code>cowboy_req</code> module.</p></div>
-<div class="paragraph"><p>The Req object is the subject of a few different chapters.
-In this chapter we will learn about the Req object and
-look at how to retrieve information about the request.</p></div>
-<div class="sect1">
-<h2 id="_direct_access">Direct access</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The Req map contains a number of fields which are documented
-and can be accessed directly. They are the fields that have
-a direct mapping to HTTP: the request <code>method</code>; the HTTP
-<code>version</code> used; the effective URI components <code>scheme</code>,
-<code>host</code>, <code>port</code>, <code>path</code> and <code>qs</code>; the request <code>headers</code>;
-and the connection <code>peer</code> address and port.</p></div>
-<div class="paragraph"><p>Note that the <code>version</code> field can be used to determine
-whether a connection is using HTTP/2.</p></div>
-<div class="paragraph"><p>To access a field, you can simply match in the function
-head. The following example sends a simple "Hello world!"
-response when the <code>method</code> is GET, and a 405 error
-otherwise.</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: #000000">init</span></span>(<span style="color: #009900">Req0</span><span style="color: #990000">=</span>#{<span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>
- }, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello world!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">405</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>
- }, <span style="color: #009900">Req0</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Any other field is internal and should not be accessed.
-They may change in future releases, including maintenance
-releases, without notice.</p></div>
-<div class="paragraph"><p>Modifying the Req object, while allowed, is not recommended
-unless strictly necessary. If adding new fields, make sure
-to namespace the field names so that no conflict can occur
-with future Cowboy updates or third party projects.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_introduction_to_the_cowboy_req_interface">Introduction to the cowboy_req interface</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Functions in the <code>cowboy_req</code> module provide access to
-the request information but also various operations that
-are common when dealing with HTTP requests.</p></div>
-<div class="paragraph"><p>All the functions that begin with a verb indicate an action.
-Other functions simply return the corresponding value
-(sometimes that value does need to be built, but the
-cost of the operation is equivalent to retrieving a value).</p></div>
-<div class="paragraph"><p>Some of the <code>cowboy_req</code> functions return an updated Req
-object. They are the read, reply, set and delete functions.
-While ignoring the returned Req will not cause incorrect
-behavior for some of them, it is highly recommended to
-always keep and use the last returned Req object. The
-manual for <code>cowboy_req</code> details these functions and what
-modifications are done to the Req object.</p></div>
-<div class="paragraph"><p>Some of the calls to <code>cowboy_req</code> have side effects. This
-is the case of the read and reply functions. Cowboy reads
-the request body or replies immediately when the function
-is called.</p></div>
-<div class="paragraph"><p>All functions will crash if something goes wrong. There
-is usually no need to catch these errors, Cowboy will
-send the appropriate 4xx or 5xx response depending on
-where the crash occurred.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_request_method">Request method</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The request method can be retrieved directly:</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="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #009900">Method</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or using a function:</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="color: #009900">Method</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:method</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The method is a case sensitive binary string. Standard
-methods include GET, HEAD, OPTIONS, PATCH, POST, PUT
-or DELETE.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_http_version">HTTP version</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP version is informational. It does not indicate that
-the client implements the protocol well or fully.</p></div>
-<div class="paragraph"><p>There is typically no need to change behavior based on the
-HTTP version: Cowboy already does it for you.</p></div>
-<div class="paragraph"><p>It can be useful in some cases, though. For example, one may
-want to redirect HTTP/1.1 clients to use Websocket, while HTTP/2
-clients keep using HTTP/2.</p></div>
-<div class="paragraph"><p>The HTTP version can be retrieved directly:</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="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="color: #009900">Version</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or using a function:</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="color: #009900">Version</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:version</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy defines the <code>'HTTP/1.0'</code>, <code>'HTTP/1.1'</code> and <code>'HTTP/2'</code>
-versions. Custom protocols can define their own values as
-atoms.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_effective_request_uri">Effective request URI</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The scheme, host, port, path and query string components
-of the effective request URI can all be retrieved directly:</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="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="color: #009900">Scheme</span>,
- <span style="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="color: #009900">Host</span>,
- <span style="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="color: #009900">Port</span>,
- <span style="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="color: #009900">Path</span>,
- <span style="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="color: #009900">Qs</span>
-} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or using the related functions:</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="color: #009900">Scheme</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:scheme</span></span>(<span style="color: #009900">Req</span>),
-<span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host</span></span>(<span style="color: #009900">Req</span>),
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:port</span></span>(<span style="color: #009900">Req</span>),
-<span style="color: #009900">Path</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:qs</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The scheme and host are lowercased case insensitive binary
-strings. The port is an integer representing the port number.
-The path and query string are case sensitive binary strings.</p></div>
-<div class="paragraph"><p>Cowboy defines only the <code><<"http">></code> and <code><<"https">></code> schemes.
-They are chosen so that the scheme will only be <code><<"https">></code>
-for requests on secure HTTP/1.1 or HTTP/2 connections.</p></div>
-<div class="paragraph"><p>The effective request URI itself can be reconstructed with
-the <code>cowboy_req:uri/1,2</code> function. By default, an absolute
-URI is returned:</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">scheme://host</span></span><span style="font-style: italic"><span style="color: #9A1900">[:port]/path[?qs]</span></span>
-<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Options are available to either disable or replace some
-or all of the components. Various URIs or URI formats can
-be generated this way, including the origin form:</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-style: italic"><span style="color: #9A1900">%% /path[?qs]</span></span>
-<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The protocol relative form:</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-style: italic"><span style="color: #9A1900">%% //host[:port]/path[?qs]</span></span>
-<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The absolute URI without a query string:</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="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>A different host:</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="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"example.org"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And any other combination.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_bindings">Bindings</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Bindings are the host and path components that you chose
-to extract when defining the routes of your application.
-They are only available after the routing.</p></div>
-<div class="paragraph"><p>Cowboy provides functions to retrieve one or all bindings.</p></div>
-<div class="paragraph"><p>To retrieve a single value:</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="color: #009900">Value</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">userid</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>When attempting to retrieve a value that was not bound,
-<code>undefined</code> will be returned. A different default value
-can be provided:</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="color: #009900">Value</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">userid</span>, <span style="color: #009900">Req</span>, <span style="color: #993399">42</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To retrieve everything that was bound:</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="color: #009900">Bindings</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:bindings</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>They are returned as a map, with keys being atoms.</p></div>
-<div class="paragraph"><p>The Cowboy router also allows you to capture many host
-or path segments at once using the <code>...</code> qualifier.</p></div>
-<div class="paragraph"><p>To retrieve the segments captured from the host name:</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="color: #009900">HostInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And the path segments:</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="color: #009900">PathInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy will return <code>undefined</code> if <code>...</code> was not used
-in the route.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_query_parameters">Query parameters</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides two functions to access query parameters.
-You can use the first to get the entire list of parameters.</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="color: #009900">QsVals</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_qs</span></span>(<span style="color: #009900">Req</span>),
-{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">QsVals</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy will only parse the query string, and not do any
-transformation. This function may therefore return duplicates,
-or parameter names without an associated value. The order of
-the list returned is undefined.</p></div>
-<div class="paragraph"><p>When a query string is <code>key=1&key=2</code>, the list returned will
-contain two parameters of name <code>key</code>.</p></div>
-<div class="paragraph"><p>The same is true when trying to use the PHP-style suffix <code>[]</code>.
-When a query string is <code>key[]=1&key[]=2</code>, the list returned will
-contain two parameters of name <code>key[]</code>.</p></div>
-<div class="paragraph"><p>When a query string is simply <code>key</code>, Cowboy will return the
-list <code>[{<<"key">>, true}]</code>, using <code>true</code> to indicate that the
-parameter <code>key</code> was defined, but with no value.</p></div>
-<div class="paragraph"><p>The second function Cowboy provides allows you to match out
-only the parameters you are interested in, and at the same
-time do any post processing you require using <a href="../constraints">constraints</a>.
-This function returns a map.</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="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Constraints can be applied automatically. The following
-snippet will crash when the <code>id</code> parameter is not an integer,
-or when the <code>lang</code> parameter is empty. At the same time, the
-value for <code>id</code> will be converted to an integer term:</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="color: #009900">QsMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>A default value may also be provided. The default will be used
-if the <code>lang</code> key is not found. It will not be used if
-the key is found but has an empty value.</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="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If no default is provided and the value is missing, the
-query string is deemed invalid and the process will crash.</p></div>
-<div class="paragraph"><p>When the query string is <code>key=1&key=2</code>, the value for <code>key</code>
-will be the list <code>[1, 2]</code>. Parameter names do not need to
-include the PHP-style suffix. Constraints may be used to
-ensure that only one value was passed through.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_headers">Headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Header values can be retrieved either as a binary string
-or parsed into a more meaningful representation.</p></div>
-<div class="paragraph"><p>The get the raw value:</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="color: #009900">HeaderVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy expects all header names to be provided as lowercase
-binary strings. This is true for both requests and responses,
-regardless of the underlying protocol.</p></div>
-<div class="paragraph"><p>When the header is missing from the request, <code>undefined</code>
-will be returned. A different default can be provided:</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="color: #009900">HeaderVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All headers can be retrieved at once, either directly:</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="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="color: #009900">AllHeaders</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or using a function:</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="color: #009900">AllHeaders</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy provides equivalent functions to parse individual
-headers. There is no function to parse all headers at once.</p></div>
-<div class="paragraph"><p>To parse a specific header:</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="color: #009900">ParsedVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>An exception will be thrown if it doesn’t know how to parse the
-given header, or if the value is invalid. The list of known headers
-and default values can be found in the manual.</p></div>
-<div class="paragraph"><p>When the header is missing, <code>undefined</code> is returned. You can
-change the default value. Note that it should be the parsed value
-directly:</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="color: #009900">ParsedVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>,
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"plain"</span><span style="color: #990000">>></span>, []})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_peer">Peer</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The peer address and port number for the connection can be
-retrieved either directly or using a function.</p></div>
-<div class="paragraph"><p>To retrieve the peer directly:</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="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="color: #009900">IP</span>, <span style="color: #009900">Port</span>}} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And using a function:</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="color: #009900">IP</span>, <span style="color: #009900">Port</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:peer</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the peer corresponds to the remote end of the
-connection to the server, which may or may not be the
-client itself. It may also be a proxy or a gateway.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>The Req object is a variable used for obtaining information +about a request, read its body or send a response.</p></div> +<div class="paragraph"><p>It is not really an object in the object-oriented sense. +It is a simple map that can be directly accessed or +used when calling functions from the <code>cowboy_req</code> module.</p></div> +<div class="paragraph"><p>The Req object is the subject of a few different chapters. +In this chapter we will learn about the Req object and +look at how to retrieve information about the request.</p></div> +<div class="sect1"> +<h2 id="_direct_access">Direct access</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The Req map contains a number of fields which are documented +and can be accessed directly. They are the fields that have +a direct mapping to HTTP: the request <code>method</code>; the HTTP +<code>version</code> used; the effective URI components <code>scheme</code>, +<code>host</code>, <code>port</code>, <code>path</code> and <code>qs</code>; the request <code>headers</code>; +and the connection <code>peer</code> address and port.</p></div> +<div class="paragraph"><p>Note that the <code>version</code> field can be used to determine +whether a connection is using HTTP/2.</p></div> +<div class="paragraph"><p>To access a field, you can simply match in the function +head. The following example sends a simple "Hello world!" +response when the <code>method</code> is GET, and a 405 error +otherwise.</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: #000000">init</span></span>(<span style="color: #009900">Req0</span><span style="color: #990000">=</span>#{<span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span> + }, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello world!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">405</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span> + }, <span style="color: #009900">Req0</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Any other field is internal and should not be accessed. +They may change in future releases, including maintenance +releases, without notice.</p></div> +<div class="paragraph"><p>Modifying the Req object, while allowed, is not recommended +unless strictly necessary. If adding new fields, make sure +to namespace the field names so that no conflict can occur +with future Cowboy updates or third party projects.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_introduction_to_the_cowboy_req_interface">Introduction to the cowboy_req interface</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Functions in the <code>cowboy_req</code> module provide access to +the request information but also various operations that +are common when dealing with HTTP requests.</p></div> +<div class="paragraph"><p>All the functions that begin with a verb indicate an action. +Other functions simply return the corresponding value +(sometimes that value does need to be built, but the +cost of the operation is equivalent to retrieving a value).</p></div> +<div class="paragraph"><p>Some of the <code>cowboy_req</code> functions return an updated Req +object. They are the read, reply, set and delete functions. +While ignoring the returned Req will not cause incorrect +behavior for some of them, it is highly recommended to +always keep and use the last returned Req object. The +manual for <code>cowboy_req</code> details these functions and what +modifications are done to the Req object.</p></div> +<div class="paragraph"><p>Some of the calls to <code>cowboy_req</code> have side effects. This +is the case of the read and reply functions. Cowboy reads +the request body or replies immediately when the function +is called.</p></div> +<div class="paragraph"><p>All functions will crash if something goes wrong. There +is usually no need to catch these errors, Cowboy will +send the appropriate 4xx or 5xx response depending on +where the crash occurred.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_request_method">Request method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The request method can be retrieved directly:</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="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #009900">Method</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or using a function:</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="color: #009900">Method</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:method</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The method is a case sensitive binary string. Standard +methods include GET, HEAD, OPTIONS, PATCH, POST, PUT +or DELETE.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_http_version">HTTP version</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP version is informational. It does not indicate that +the client implements the protocol well or fully.</p></div> +<div class="paragraph"><p>There is typically no need to change behavior based on the +HTTP version: Cowboy already does it for you.</p></div> +<div class="paragraph"><p>It can be useful in some cases, though. For example, one may +want to redirect HTTP/1.1 clients to use Websocket, while HTTP/2 +clients keep using HTTP/2.</p></div> +<div class="paragraph"><p>The HTTP version can be retrieved directly:</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="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="color: #009900">Version</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or using a function:</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="color: #009900">Version</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:version</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy defines the <code>'HTTP/1.0'</code>, <code>'HTTP/1.1'</code> and <code>'HTTP/2'</code> +versions. Custom protocols can define their own values as +atoms.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_effective_request_uri">Effective request URI</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The scheme, host, port, path and query string components +of the effective request URI can all be retrieved directly:</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="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="color: #009900">Scheme</span>, + <span style="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="color: #009900">Host</span>, + <span style="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="color: #009900">Port</span>, + <span style="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="color: #009900">Path</span>, + <span style="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="color: #009900">Qs</span> +} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or using the related functions:</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="color: #009900">Scheme</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:scheme</span></span>(<span style="color: #009900">Req</span>), +<span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host</span></span>(<span style="color: #009900">Req</span>), +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:port</span></span>(<span style="color: #009900">Req</span>), +<span style="color: #009900">Path</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:qs</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The scheme and host are lowercased case insensitive binary +strings. The port is an integer representing the port number. +The path and query string are case sensitive binary strings.</p></div> +<div class="paragraph"><p>Cowboy defines only the <code><<"http">></code> and <code><<"https">></code> schemes. +They are chosen so that the scheme will only be <code><<"https">></code> +for requests on secure HTTP/1.1 or HTTP/2 connections.</p></div> +<div class="paragraph"><p>The effective request URI itself can be reconstructed with +the <code>cowboy_req:uri/1,2</code> function. By default, an absolute +URI is returned:</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">scheme://host</span></span><span style="font-style: italic"><span style="color: #9A1900">[:port]/path[?qs]</span></span> +<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Options are available to either disable or replace some +or all of the components. Various URIs or URI formats can +be generated this way, including the origin form:</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-style: italic"><span style="color: #9A1900">%% /path[?qs]</span></span> +<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The protocol relative form:</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-style: italic"><span style="color: #9A1900">%% //host[:port]/path[?qs]</span></span> +<span style="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The absolute URI without a query string:</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="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>A different host:</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="color: #009900">URI</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"example.org"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And any other combination.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_bindings">Bindings</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Bindings are the host and path components that you chose +to extract when defining the routes of your application. +They are only available after the routing.</p></div> +<div class="paragraph"><p>Cowboy provides functions to retrieve one or all bindings.</p></div> +<div class="paragraph"><p>To retrieve a single value:</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="color: #009900">Value</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">userid</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>When attempting to retrieve a value that was not bound, +<code>undefined</code> will be returned. A different default value +can be provided:</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="color: #009900">Value</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">userid</span>, <span style="color: #009900">Req</span>, <span style="color: #993399">42</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To retrieve everything that was bound:</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="color: #009900">Bindings</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:bindings</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>They are returned as a map, with keys being atoms.</p></div> +<div class="paragraph"><p>The Cowboy router also allows you to capture many host +or path segments at once using the <code>...</code> qualifier.</p></div> +<div class="paragraph"><p>To retrieve the segments captured from the host name:</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="color: #009900">HostInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And the path segments:</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="color: #009900">PathInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy will return <code>undefined</code> if <code>...</code> was not used +in the route.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_query_parameters">Query parameters</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides two functions to access query parameters. +You can use the first to get the entire list of parameters.</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="color: #009900">QsVals</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_qs</span></span>(<span style="color: #009900">Req</span>), +{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">QsVals</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy will only parse the query string, and not do any +transformation. This function may therefore return duplicates, +or parameter names without an associated value. The order of +the list returned is undefined.</p></div> +<div class="paragraph"><p>When a query string is <code>key=1&key=2</code>, the list returned will +contain two parameters of name <code>key</code>.</p></div> +<div class="paragraph"><p>The same is true when trying to use the PHP-style suffix <code>[]</code>. +When a query string is <code>key[]=1&key[]=2</code>, the list returned will +contain two parameters of name <code>key[]</code>.</p></div> +<div class="paragraph"><p>When a query string is simply <code>key</code>, Cowboy will return the +list <code>[{<<"key">>, true}]</code>, using <code>true</code> to indicate that the +parameter <code>key</code> was defined, but with no value.</p></div> +<div class="paragraph"><p>The second function Cowboy provides allows you to match out +only the parameters you are interested in, and at the same +time do any post processing you require using <a href="../constraints">constraints</a>. +This function returns a map.</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="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Constraints can be applied automatically. The following +snippet will crash when the <code>id</code> parameter is not an integer, +or when the <code>lang</code> parameter is empty. At the same time, the +value for <code>id</code> will be converted to an integer term:</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="color: #009900">QsMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>A default value may also be provided. The default will be used +if the <code>lang</code> key is not found. It will not be used if +the key is found but has an empty value.</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="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If no default is provided and the value is missing, the +query string is deemed invalid and the process will crash.</p></div> +<div class="paragraph"><p>When the query string is <code>key=1&key=2</code>, the value for <code>key</code> +will be the list <code>[1, 2]</code>. Parameter names do not need to +include the PHP-style suffix. Constraints may be used to +ensure that only one value was passed through.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_headers">Headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Header values can be retrieved either as a binary string +or parsed into a more meaningful representation.</p></div> +<div class="paragraph"><p>The get the raw value:</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="color: #009900">HeaderVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy expects all header names to be provided as lowercase +binary strings. This is true for both requests and responses, +regardless of the underlying protocol.</p></div> +<div class="paragraph"><p>When the header is missing from the request, <code>undefined</code> +will be returned. A different default can be provided:</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="color: #009900">HeaderVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All headers can be retrieved at once, either directly:</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="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="color: #009900">AllHeaders</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or using a function:</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="color: #009900">AllHeaders</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy provides equivalent functions to parse individual +headers. There is no function to parse all headers at once.</p></div> +<div class="paragraph"><p>To parse a specific header:</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="color: #009900">ParsedVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>An exception will be thrown if it doesn’t know how to parse the +given header, or if the value is invalid. The list of known headers +and default values can be found in the manual.</p></div> +<div class="paragraph"><p>When the header is missing, <code>undefined</code> is returned. You can +change the default value. Note that it should be the parsed value +directly:</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="color: #009900">ParsedVal</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, + {<span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"plain"</span><span style="color: #990000">>></span>, []})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_peer">Peer</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The peer address and port number for the connection can be +retrieved either directly or using a function.</p></div> +<div class="paragraph"><p>To retrieve the peer directly:</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="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="color: #009900">IP</span>, <span style="color: #009900">Port</span>}} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And using a function:</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="color: #009900">IP</span>, <span style="color: #009900">Port</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:peer</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that the peer corresponds to the remote end of the +connection to the server, which may or may not be the +client itself. It may also be a proxy or a gateway.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/req_body/index.html b/docs/en/cowboy/2.0/guide/req_body/index.html index 821b512c..4fce0fd5 100644 --- a/docs/en/cowboy/2.0/guide/req_body/index.html +++ b/docs/en/cowboy/2.0/guide/req_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Reading the request body</title> @@ -67,150 +67,153 @@ <h1 class="lined-header"><span>Reading the request body</span></h1> -<div class="paragraph"><p>The request body can be read using the Req object.</p></div>
-<div class="paragraph"><p>Cowboy will not attempt to read the body until requested.
-You need to call the body reading functions in order to
-retrieve it.</p></div>
-<div class="paragraph"><p>Cowboy will not cache the body, it is therefore only
-possible to read it once.</p></div>
-<div class="paragraph"><p>You are not required to read it, however. If a body is
-present and was not read, Cowboy will either cancel or
-skip its download, depending on the protocol.</p></div>
-<div class="paragraph"><p>Cowboy provides functions for reading the body raw,
-and read and parse form urlencoded or <a href="../multipart">multipart bodies</a>.
-The latter is covered in its own chapter.</p></div>
-<div class="sect1">
-<h2 id="_request_body_presence">Request body presence</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Not all requests come with a body. You can check for
-the presence of a request body with this function:</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: #000000">cowboy_req:has_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It returns <code>true</code> if there is a body; <code>false</code> otherwise.</p></div>
-<div class="paragraph"><p>In practice, this function is rarely used. When the
-method is <code>POST</code>, <code>PUT</code> or <code>PATCH</code>, the request body
-is often required by the application, which should
-just attempt to read it directly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_request_body_length">Request body length</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can obtain the length of the body:</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="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_length</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the length may not be known in advance. In
-that case <code>undefined</code> will be returned. This can happen
-with HTTP/1.1’s chunked transfer-encoding, or HTTP/2
-when no content-length was provided.</p></div>
-<div class="paragraph"><p>Cowboy will update the body length in the Req object
-once the body has been read completely. A length will
-always be returned when attempting to call this function
-after reading the body completely.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reading_the_body">Reading the body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can read the entire body with one function call:</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="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy returns an <code>ok</code> tuple when the body has been
-read fully.</p></div>
-<div class="paragraph"><p>By default, Cowboy will attempt to read up to 8MB
-of data, for up to 15 seconds. The call will return
-once Cowboy has read at least 8MB of data, or at
-the end of the 15 seconds period.</p></div>
-<div class="paragraph"><p>These values can be customized. For example, to read
-only up to 1MB for up to 5 seconds:</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="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>,
- #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">5000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You may also disable the length limit:</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="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #FF6600">infinity</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This makes the function wait 15 seconds and return with
-whatever arrived during that period. This is not
-recommended for public facing applications.</p></div>
-<div class="paragraph"><p>These two options can effectively be used to control
-the rate of transmission of the request body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_streaming_the_body">Streaming the body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When the body is too large, the first call will return
-a <code>more</code> tuple instead of <code>ok</code>. You can call the
-function again to read more of the body, reading
-it one chunk at a time.</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: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
- <span style="color: #009900">Req</span>;
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
- <span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req</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>The <code>length</code> and <code>period</code> options can also be used.
-They need to be passed for every call.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reading_a_form_urlencoded_body">Reading a form urlencoded body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides a convenient function for reading and
-parsing bodies sent as application/x-www-form-urlencoded.</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="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This function returns a list of key/values, exactly like
-the function <code>cowboy_req:parse_qs/1</code>.</p></div>
-<div class="paragraph"><p>The defaults for this function are different. Cowboy will
-read for up to 64KB and up to 5 seconds. They can be modified:</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="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>,
- #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">4096</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">3000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>The request body can be read using the Req object.</p></div> +<div class="paragraph"><p>Cowboy will not attempt to read the body until requested. +You need to call the body reading functions in order to +retrieve it.</p></div> +<div class="paragraph"><p>Cowboy will not cache the body, it is therefore only +possible to read it once.</p></div> +<div class="paragraph"><p>You are not required to read it, however. If a body is +present and was not read, Cowboy will either cancel or +skip its download, depending on the protocol.</p></div> +<div class="paragraph"><p>Cowboy provides functions for reading the body raw, +and read and parse form urlencoded or <a href="../multipart">multipart bodies</a>. +The latter is covered in its own chapter.</p></div> +<div class="sect1"> +<h2 id="_request_body_presence">Request body presence</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Not all requests come with a body. You can check for +the presence of a request body with this function:</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: #000000">cowboy_req:has_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It returns <code>true</code> if there is a body; <code>false</code> otherwise.</p></div> +<div class="paragraph"><p>In practice, this function is rarely used. When the +method is <code>POST</code>, <code>PUT</code> or <code>PATCH</code>, the request body +is often required by the application, which should +just attempt to read it directly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_request_body_length">Request body length</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can obtain the length of the body:</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="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_length</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that the length may not be known in advance. In +that case <code>undefined</code> will be returned. This can happen +with HTTP/1.1’s chunked transfer-encoding, or HTTP/2 +when no content-length was provided.</p></div> +<div class="paragraph"><p>Cowboy will update the body length in the Req object +once the body has been read completely. A length will +always be returned when attempting to call this function +after reading the body completely.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reading_the_body">Reading the body</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can read the entire body with one function call:</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="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy returns an <code>ok</code> tuple when the body has been +read fully.</p></div> +<div class="paragraph"><p>By default, Cowboy will attempt to read up to 8MB +of data, for up to 15 seconds. The call will return +once Cowboy has read at least 8MB of data, or at +the end of the 15 seconds period.</p></div> +<div class="paragraph"><p>These values can be customized. For example, to read +only up to 1MB for up to 5 seconds:</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="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>, + #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">5000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You may also disable the length limit:</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="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #FF6600">infinity</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This makes the function wait 15 seconds and return with +whatever arrived during that period. This is not +recommended for public facing applications.</p></div> +<div class="paragraph"><p>These two options can effectively be used to control +the rate of transmission of the request body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_streaming_the_body">Streaming the body</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When the body is too large, the first call will return +a <code>more</code> tuple instead of <code>ok</code>. You can call the +function again to read more of the body, reading +it one chunk at a time.</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: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req0</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">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]), + <span style="color: #009900">Req</span>; + {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]), + <span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req</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>The <code>length</code> and <code>period</code> options can also be used. +They need to be passed for every call.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reading_a_form_urlencoded_body">Reading a form urlencoded body</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides a convenient function for reading and +parsing bodies sent as application/x-www-form-urlencoded.</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="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This function returns a list of key/values, exactly like +the function <code>cowboy_req:parse_qs/1</code>.</p></div> +<div class="paragraph"><p>The defaults for this function are different. Cowboy will +read for up to 64KB and up to 5 seconds. They can be modified:</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="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>, + #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">4096</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">3000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/resource_design/index.html b/docs/en/cowboy/2.0/guide/resource_design/index.html index 1a288856..32c8a129 100644 --- a/docs/en/cowboy/2.0/guide/resource_design/index.html +++ b/docs/en/cowboy/2.0/guide/resource_design/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Designing a resource handler</title> @@ -67,219 +67,222 @@ <h1 class="lined-header"><span>Designing a resource handler</span></h1> -<div class="paragraph"><p>This chapter aims to provide you with a list of questions
-you must answer in order to write a good resource handler.
-It is meant to be usable as a step by step guide.</p></div>
-<div class="sect1">
-<h2 id="_the_service">The service</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Can the service become unavailable, and when it does, can
-we detect it? For example, database connectivity problems
-may be detected early. We may also have planned outages
-of all or parts of the system. Implement the
-<code>service_available</code> callback.</p></div>
-<div class="paragraph"><p>What HTTP methods does the service implement? Do we need
-more than the standard OPTIONS, HEAD, GET, PUT, POST,
-PATCH and DELETE? Are we not using one of those at all?
-Implement the <code>known_methods</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_type_of_resource_handler">Type of resource handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Am I writing a handler for a collection of resources,
-or for a single resource?</p></div>
-<div class="paragraph"><p>The semantics for each of these are quite different.
-You should not mix collection and single resource in
-the same handler.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_collection_handler">Collection handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Skip this section if you are not doing a collection.</p></div>
-<div class="paragraph"><p>Is the collection hardcoded or dynamic? For example,
-if you use the route <code>/users</code> for the collection of
-users then the collection is hardcoded; if you use
-<code>/forums/:category</code> for the collection of threads
-then it isn’t. When the collection is hardcoded you
-can safely assume the resource always exists.</p></div>
-<div class="paragraph"><p>What methods should I implement?</p></div>
-<div class="paragraph"><p>OPTIONS is used to get some information about the
-collection. It is recommended to allow it even if you
-do not implement it, as Cowboy has a default
-implementation built-in.</p></div>
-<div class="paragraph"><p>HEAD and GET are used to retrieve the collection.
-If you allow GET, also allow HEAD as there’s no extra
-work required to make it work.</p></div>
-<div class="paragraph"><p>POST is used to create a new resource inside the
-collection. Creating a resource by using POST on
-the collection is useful when resources may be
-created before knowing their URI, usually because
-parts of it are generated dynamically. A common
-case is some kind of auto incremented integer
-identifier.</p></div>
-<div class="paragraph"><p>The next methods are more rarely allowed.</p></div>
-<div class="paragraph"><p>PUT is used to create a new collection (when
-the collection isn’t hardcoded), or replace
-the entire collection.</p></div>
-<div class="paragraph"><p>DELETE is used to delete the entire collection.</p></div>
-<div class="paragraph"><p>PATCH is used to modify the collection using
-instructions given in the request body. A PATCH
-operation is atomic. The PATCH operation may
-be used for such things as reordering; adding,
-modifying or deleting parts of the collection.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_single_resource_handler">Single resource handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Skip this section if you are doing a collection.</p></div>
-<div class="paragraph"><p>What methods should I implement?</p></div>
-<div class="paragraph"><p>OPTIONS is used to get some information about the
-resource. It is recommended to allow it even if you
-do not implement it, as Cowboy has a default
-implementation built-in.</p></div>
-<div class="paragraph"><p>HEAD and GET are used to retrieve the resource.
-If you allow GET, also allow HEAD as there’s no extra
-work required to make it work.</p></div>
-<div class="paragraph"><p>POST is used to update the resource.</p></div>
-<div class="paragraph"><p>PUT is used to create a new resource (when it doesn’t
-already exist) or replace the resource.</p></div>
-<div class="paragraph"><p>DELETE is used to delete the resource.</p></div>
-<div class="paragraph"><p>PATCH is used to modify the resource using
-instructions given in the request body. A PATCH
-operation is atomic. The PATCH operation may
-be used for adding, removing or modifying specific
-values in the resource.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_resource">The resource</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Following the above discussion, implement the
-<code>allowed_methods</code> callback.</p></div>
-<div class="paragraph"><p>Does the resource always exist? If it may not, implement
-the <code>resource_exists</code> callback.</p></div>
-<div class="paragraph"><p>Do I need to authenticate the client before they can
-access the resource? What authentication mechanisms
-should I provide? This may include form-based, token-based
-(in the URL or a cookie), HTTP basic, HTTP digest,
-SSL certificate or any other form of authentication.
-Implement the <code>is_authorized</code> callback.</p></div>
-<div class="paragraph"><p>Do I need fine-grained access control? How do I determine
-that they are authorized access? Handle that in your
-<code>is_authorized</code> callback.</p></div>
-<div class="paragraph"><p>Can access to a resource be forbidden regardless of access
-being authorized? A simple example of that is censorship
-of a resource. Implement the <code>forbidden</code> callback.</p></div>
-<div class="paragraph"><p>Are there any constraints on the length of the resource URI?
-For example, the URI may be used as a key in storage and may
-have a limit in length. Implement <code>uri_too_long</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_representations">Representations</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>What media types do I provide? If text based, what charsets
-are provided? What languages do I provide?</p></div>
-<div class="paragraph"><p>Implement the mandatory <code>content_types_provided</code>. Prefix
-the callbacks with <code>to_</code> for clarity. For example, <code>to_html</code>
-or <code>to_text</code>.</p></div>
-<div class="paragraph"><p>Implement the <code>languages_provided</code> or <code>charsets_provided</code>
-callbacks if applicable.</p></div>
-<div class="paragraph"><p>Is there any other header that may make the representation
-of the resource vary? Implement the <code>variances</code> callback.</p></div>
-<div class="paragraph"><p>Depending on your choices for caching content, you may
-want to implement one or more of the <code>generate_etag</code>,
-<code>last_modified</code> and <code>expires</code> callbacks.</p></div>
-<div class="paragraph"><p>Do I want the user or user agent to actively choose a
-representation available? Send a list of available
-representations in the response body and implement
-the <code>multiple_choices</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_redirections">Redirections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Do I need to keep track of what resources were deleted?
-For example, you may have a mechanism where moving a
-resource leaves a redirect link to its new location.
-Implement the <code>previously_existed</code> callback.</p></div>
-<div class="paragraph"><p>Was the resource moved, and is the move temporary? If
-it is explicitly temporary, for example due to maintenance,
-implement the <code>moved_temporarily</code> callback. Otherwise,
-implement the <code>moved_permanently</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_request">The request</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Do you need to read the query string? Individual headers?
-Implement <code>malformed_request</code> and do all the parsing and
-validation in this function. Note that the body should not
-be read at this point.</p></div>
-<div class="paragraph"><p>May there be a request body? Will I know its size?
-What’s the maximum size of the request body I’m willing
-to accept? Implement <code>valid_entity_length</code>.</p></div>
-<div class="paragraph"><p>Finally, take a look at the sections corresponding to the
-methods you are implementing.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options_method">OPTIONS method</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy by default will send back a list of allowed methods.
-Do I need to add more information to the response? Implement
-the <code>options</code> method.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_get_and_head_methods">GET and HEAD methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you implement the methods GET and/or HEAD, you must
-implement one <code>ProvideResource</code> callback for each
-content-type returned by the <code>content_types_provided</code>
-callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you implement the methods PUT, POST and/or PATCH,
-you must implement the <code>content_types_accepted</code> callback,
-and one <code>AcceptResource</code> callback for each content-type
-it returns. Prefix the <code>AcceptResource</code> callback names
-with <code>from_</code> for clarity. For example, <code>from_html</code> or
-<code>from_json</code>.</p></div>
-<div class="paragraph"><p>Do we want to allow the POST method to create individual
-resources directly through their URI (like PUT)? Implement
-the <code>allow_missing_post</code> callback. It is recommended to
-explicitly use PUT in these cases instead.</p></div>
-<div class="paragraph"><p>May there be conflicts when using PUT to create or replace
-a resource? Do we want to make sure that two updates around
-the same time are not cancelling one another? Implement the
-<code>is_conflict</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_delete_methods">DELETE methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you implement the method DELETE, you must implement
-the <code>delete_resource</code> callback.</p></div>
-<div class="paragraph"><p>When <code>delete_resource</code> returns, is the resource completely
-removed from the server, including from any caching service?
-If not, and/or if the deletion is asynchronous and we have
-no way of knowing it has been completed yet, implement the
-<code>delete_completed</code> callback.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter aims to provide you with a list of questions +you must answer in order to write a good resource handler. +It is meant to be usable as a step by step guide.</p></div> +<div class="sect1"> +<h2 id="_the_service">The service</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Can the service become unavailable, and when it does, can +we detect it? For example, database connectivity problems +may be detected early. We may also have planned outages +of all or parts of the system. Implement the +<code>service_available</code> callback.</p></div> +<div class="paragraph"><p>What HTTP methods does the service implement? Do we need +more than the standard OPTIONS, HEAD, GET, PUT, POST, +PATCH and DELETE? Are we not using one of those at all? +Implement the <code>known_methods</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_type_of_resource_handler">Type of resource handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Am I writing a handler for a collection of resources, +or for a single resource?</p></div> +<div class="paragraph"><p>The semantics for each of these are quite different. +You should not mix collection and single resource in +the same handler.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_collection_handler">Collection handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Skip this section if you are not doing a collection.</p></div> +<div class="paragraph"><p>Is the collection hardcoded or dynamic? For example, +if you use the route <code>/users</code> for the collection of +users then the collection is hardcoded; if you use +<code>/forums/:category</code> for the collection of threads +then it isn’t. When the collection is hardcoded you +can safely assume the resource always exists.</p></div> +<div class="paragraph"><p>What methods should I implement?</p></div> +<div class="paragraph"><p>OPTIONS is used to get some information about the +collection. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.</p></div> +<div class="paragraph"><p>HEAD and GET are used to retrieve the collection. +If you allow GET, also allow HEAD as there’s no extra +work required to make it work.</p></div> +<div class="paragraph"><p>POST is used to create a new resource inside the +collection. Creating a resource by using POST on +the collection is useful when resources may be +created before knowing their URI, usually because +parts of it are generated dynamically. A common +case is some kind of auto incremented integer +identifier.</p></div> +<div class="paragraph"><p>The next methods are more rarely allowed.</p></div> +<div class="paragraph"><p>PUT is used to create a new collection (when +the collection isn’t hardcoded), or replace +the entire collection.</p></div> +<div class="paragraph"><p>DELETE is used to delete the entire collection.</p></div> +<div class="paragraph"><p>PATCH is used to modify the collection using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for such things as reordering; adding, +modifying or deleting parts of the collection.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_single_resource_handler">Single resource handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Skip this section if you are doing a collection.</p></div> +<div class="paragraph"><p>What methods should I implement?</p></div> +<div class="paragraph"><p>OPTIONS is used to get some information about the +resource. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.</p></div> +<div class="paragraph"><p>HEAD and GET are used to retrieve the resource. +If you allow GET, also allow HEAD as there’s no extra +work required to make it work.</p></div> +<div class="paragraph"><p>POST is used to update the resource.</p></div> +<div class="paragraph"><p>PUT is used to create a new resource (when it doesn’t +already exist) or replace the resource.</p></div> +<div class="paragraph"><p>DELETE is used to delete the resource.</p></div> +<div class="paragraph"><p>PATCH is used to modify the resource using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for adding, removing or modifying specific +values in the resource.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_resource">The resource</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Following the above discussion, implement the +<code>allowed_methods</code> callback.</p></div> +<div class="paragraph"><p>Does the resource always exist? If it may not, implement +the <code>resource_exists</code> callback.</p></div> +<div class="paragraph"><p>Do I need to authenticate the client before they can +access the resource? What authentication mechanisms +should I provide? This may include form-based, token-based +(in the URL or a cookie), HTTP basic, HTTP digest, +SSL certificate or any other form of authentication. +Implement the <code>is_authorized</code> callback.</p></div> +<div class="paragraph"><p>Do I need fine-grained access control? How do I determine +that they are authorized access? Handle that in your +<code>is_authorized</code> callback.</p></div> +<div class="paragraph"><p>Can access to a resource be forbidden regardless of access +being authorized? A simple example of that is censorship +of a resource. Implement the <code>forbidden</code> callback.</p></div> +<div class="paragraph"><p>Are there any constraints on the length of the resource URI? +For example, the URI may be used as a key in storage and may +have a limit in length. Implement <code>uri_too_long</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_representations">Representations</h2> +<div class="sectionbody"> +<div class="paragraph"><p>What media types do I provide? If text based, what charsets +are provided? What languages do I provide?</p></div> +<div class="paragraph"><p>Implement the mandatory <code>content_types_provided</code>. Prefix +the callbacks with <code>to_</code> for clarity. For example, <code>to_html</code> +or <code>to_text</code>.</p></div> +<div class="paragraph"><p>Implement the <code>languages_provided</code> or <code>charsets_provided</code> +callbacks if applicable.</p></div> +<div class="paragraph"><p>Is there any other header that may make the representation +of the resource vary? Implement the <code>variances</code> callback.</p></div> +<div class="paragraph"><p>Depending on your choices for caching content, you may +want to implement one or more of the <code>generate_etag</code>, +<code>last_modified</code> and <code>expires</code> callbacks.</p></div> +<div class="paragraph"><p>Do I want the user or user agent to actively choose a +representation available? Send a list of available +representations in the response body and implement +the <code>multiple_choices</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_redirections">Redirections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Do I need to keep track of what resources were deleted? +For example, you may have a mechanism where moving a +resource leaves a redirect link to its new location. +Implement the <code>previously_existed</code> callback.</p></div> +<div class="paragraph"><p>Was the resource moved, and is the move temporary? If +it is explicitly temporary, for example due to maintenance, +implement the <code>moved_temporarily</code> callback. Otherwise, +implement the <code>moved_permanently</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_request">The request</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Do you need to read the query string? Individual headers? +Implement <code>malformed_request</code> and do all the parsing and +validation in this function. Note that the body should not +be read at this point.</p></div> +<div class="paragraph"><p>May there be a request body? Will I know its size? +What’s the maximum size of the request body I’m willing +to accept? Implement <code>valid_entity_length</code>.</p></div> +<div class="paragraph"><p>Finally, take a look at the sections corresponding to the +methods you are implementing.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options_method">OPTIONS method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy by default will send back a list of allowed methods. +Do I need to add more information to the response? Implement +the <code>options</code> method.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_get_and_head_methods">GET and HEAD methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the methods GET and/or HEAD, you must +implement one <code>ProvideResource</code> callback for each +content-type returned by the <code>content_types_provided</code> +callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the methods PUT, POST and/or PATCH, +you must implement the <code>content_types_accepted</code> callback, +and one <code>AcceptResource</code> callback for each content-type +it returns. Prefix the <code>AcceptResource</code> callback names +with <code>from_</code> for clarity. For example, <code>from_html</code> or +<code>from_json</code>.</p></div> +<div class="paragraph"><p>Do we want to allow the POST method to create individual +resources directly through their URI (like PUT)? Implement +the <code>allow_missing_post</code> callback. It is recommended to +explicitly use PUT in these cases instead.</p></div> +<div class="paragraph"><p>May there be conflicts when using PUT to create or replace +a resource? Do we want to make sure that two updates around +the same time are not cancelling one another? Implement the +<code>is_conflict</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_delete_methods">DELETE methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the method DELETE, you must implement +the <code>delete_resource</code> callback.</p></div> +<div class="paragraph"><p>When <code>delete_resource</code> returns, is the resource completely +removed from the server, including from any caching service? +If not, and/or if the deletion is asynchronous and we have +no way of knowing it has been completed yet, implement the +<code>delete_completed</code> callback.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/resp/index.html b/docs/en/cowboy/2.0/guide/resp/index.html index 9e6a7c8a..60035278 100644 --- a/docs/en/cowboy/2.0/guide/resp/index.html +++ b/docs/en/cowboy/2.0/guide/resp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Sending a response</title> @@ -67,328 +67,331 @@ <h1 class="lined-header"><span>Sending a response</span></h1> -<div class="paragraph"><p>The response must be sent using the Req object.</p></div>
-<div class="paragraph"><p>Cowboy provides two different ways of sending responses:
-either directly or by streaming the body. Response headers
-and body may be set in advance. The response is sent as
-soon as one of the reply or stream reply function is
-called.</p></div>
-<div class="paragraph"><p>Cowboy also provides a simplified interface for sending
-files. It can also send only specific parts of a file.</p></div>
-<div class="paragraph"><p>While only one response is allowed for every request,
-HTTP/2 introduced a mechanism that allows the server
-to push additional resources related to the response.
-This chapter also describes how this feature works in
-Cowboy.</p></div>
-<div class="sect1">
-<h2 id="_reply">Reply</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides three functions for sending the entire reply,
-depending on whether you need to set headers and body. In all
-cases, Cowboy will add any headers required by the protocol
-(for example the date header will always be sent).</p></div>
-<div class="paragraph"><p>When you need to set only the status code,
-use <code>cowboy_req:reply/2</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>When you need to set response headers at the same time,
-use <code>cowboy_req:reply/3</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">303</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http://ninenines.eu"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the header name must always be a lowercase
-binary.</p></div>
-<div class="paragraph"><p>When you also need to set the response body,
-use <code>cowboy_req:reply/4</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>
-}, <span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You should always set the content-type header when the
-response has a body. There is however no need to set
-the content-length header; Cowboy does it automatically.</p></div>
-<div class="paragraph"><p>The response body and the header values must be either
-a binary or an iolist. An iolist is a list containing
-binaries, characters, strings or other iolists. This
-allows you to build a response from different parts
-without having to do any concatenation:</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="color: #009900">Title</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"Hello world!"</span>,
-<span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Hats off!"</span><span style="color: #990000">>></span>,
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>
-}, [<span style="color: #FF0000">"<html><head><title>"</span>, <span style="color: #009900">Title</span>, <span style="color: #FF0000">"</title></head>"</span>,
- <span style="color: #FF0000">"<body><p>"</span>, <span style="color: #009900">Body</span>, <span style="color: #FF0000">"</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This method of building responses is more efficient than
-concatenating. Behind the scenes, each element of the list
-is simply a pointer, and those pointers are used directly
-when writing to the socket.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stream_reply">Stream reply</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides two functions for initiating a response,
-and an additional function for streaming the response body.
-Cowboy will add any required headers to the response.</p></div>
-<div class="paragraph"><p>When you need to set only the status code,
-use <code>cowboy_req:stream_reply/2</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>),
-
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"Hello..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"chunked..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"world!!"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The second argument to <code>cowboy_req:stream_body/3</code> indicates
-whether this data terminates the body. Use <code>fin</code> for the
-final flag, and <code>nofin</code> otherwise.</p></div>
-<div class="paragraph"><p>This snippet does not set a content-type header. This is
-not recommended. All responses with a body should have
-a content-type. The header can be set beforehand, or
-using the <code>cowboy_req:stream_reply/3</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>),
-
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<html><head>Hello world!</head>"</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<body><p>Hats off!</p></body></html>"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>HTTP provides a few different ways to stream response bodies.
-Cowboy will select the most appropriate one based on the HTTP
-version and the request and response headers.</p></div>
-<div class="paragraph"><p>While not required by any means, it is recommended that you
-set the content-length header in the response if you know it
-in advance. This will ensure that the best response method
-is selected and help clients understand when the response
-is fully received.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_preset_response_headers">Preset response headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides functions to set response headers without
-immediately sending them. They are stored in the Req object
-and sent as part of the response when a reply function is
-called.</p></div>
-<div class="paragraph"><p>To set response headers:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Header names must be a lowercase binary.</p></div>
-<div class="paragraph"><p>Do not use this function for setting cookies. Refer to
-the <a href="../cookies">Cookies</a> chapter for more information.</p></div>
-<div class="paragraph"><p>To check if a response header has already been set:</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: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It returns <code>true</code> if the header was set, <code>false</code> otherwise.</p></div>
-<div class="paragraph"><p>To delete a response header that was set previously:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_overriding_headers">Overriding headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>As Cowboy provides different ways of setting response
-headers and body, clashes may occur, so it’s important
-to understand what happens when a header is set twice.</p></div>
-<div class="paragraph"><p>Headers come from five different origins:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Protocol-specific headers (for example HTTP/1.1’s connection header)
-</p>
-</li>
-<li>
-<p>
-Other required headers (for example the date header)
-</p>
-</li>
-<li>
-<p>
-Preset headers
-</p>
-</li>
-<li>
-<p>
-Headers given to the reply function
-</p>
-</li>
-<li>
-<p>
-Set-cookie headers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Cowboy does not allow overriding protocol-specific headers.</p></div>
-<div class="paragraph"><p>Set-cookie headers will always be appended at the end of
-the list of headers before sending the response.</p></div>
-<div class="paragraph"><p>Headers given to the reply function will always override
-preset headers and required headers. If a header is found
-in two or three of these, then the one in the reply function
-is picked and the others are dropped.</p></div>
-<div class="paragraph"><p>Similarly, preset headers will always override required
-headers.</p></div>
-<div class="paragraph"><p>To illustrate, look at the following snippet. Cowboy by
-default sends the server header with the value "Cowboy".
-We can override 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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"server"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"yaws"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_preset_response_body">Preset response body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides functions to set the response body without
-immediately sending it. It is stored in the Req object and
-sent when the reply function is called.</p></div>
-<div class="paragraph"><p>To set the response body:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To check if a response body has already been set:</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: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It returns <code>true</code> if the body was set and is non-empty,
-<code>false</code> otherwise.</p></div>
-<div class="paragraph"><p>The preset response body is only sent if the reply function
-used is <code>cowboy_req:reply/2</code> or <code>cowboy_req:reply/3</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_files">Sending files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides a shortcut for sending files. When
-using <code>cowboy_req:reply/4</code>, or when presetting the
-response header, you can give a <code>sendfile</code> tuple to
-Cowboy:</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="color: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>}</tt></pre></div></div>
-<div class="paragraph"><p>Depending on the values for <code>Offset</code> or <code>Length</code>, the
-entire file may be sent, or just a part of it.</p></div>
-<div class="paragraph"><p>The length is required even for sending the entire file.
-Cowboy sends it in the content-length header.</p></div>
-<div class="paragraph"><p>To send a file while replying:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #FF0000">"image/png"</span>
-}, {<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #993399">12345</span>, <span style="color: #FF0000">"path/to/logo.png"</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_push">Push</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP/2 protocol introduced the ability to push resources
-related to the one sent in the response. Cowboy provides two
-functions for that purpose: <code>cowboy_req:push/3,4</code>.</p></div>
-<div class="paragraph"><p>Push is only available for HTTP/2. Cowboy will automatically
-ignore push requests if the protocol doesn’t support it.</p></div>
-<div class="paragraph"><p>The push function must be called before any of the reply
-functions. Doing otherwise will result in a crash.</p></div>
-<div class="paragraph"><p>To push a resource, you need to provide the same information
-as a client performing a request would. This includes the
-HTTP method, the URI and any necessary request headers.</p></div>
-<div class="paragraph"><p>Cowboy by default only requires you to give the path to
-the resource and the request headers. The rest of the URI
-is taken from the current request (excluding the query
-string, set to empty) and the method is GET by default.</p></div>
-<div class="paragraph"><p>The following snippet pushes a CSS file that is linked to
-in the response:</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: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>
-}, [<span style="color: #FF0000">"<html><head><title>My web page</title>"</span>,
- <span style="color: #FF0000">"<link rel='stylesheet' type='text/css' href='/static/style.css'>"</span>,
- <span style="color: #FF0000">"<body><p>Welcome to Erlang!</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To override the method, scheme, host, port or query string,
-simply pass in a fourth argument. The following snippet
-uses a different host name:</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: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div>
-<div class="paragraph"><p>Pushed resources don’t have to be files. As long as the push
-request is cacheable, safe and does not include a body, the
-resource can be pushed.</p></div>
-<div class="paragraph"><p>Under the hood, Cowboy handles pushed requests the same as
-normal requests: a different process is created which will
-ultimately send a response to the client.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>The response must be sent using the Req object.</p></div> +<div class="paragraph"><p>Cowboy provides two different ways of sending responses: +either directly or by streaming the body. Response headers +and body may be set in advance. The response is sent as +soon as one of the reply or stream reply function is +called.</p></div> +<div class="paragraph"><p>Cowboy also provides a simplified interface for sending +files. It can also send only specific parts of a file.</p></div> +<div class="paragraph"><p>While only one response is allowed for every request, +HTTP/2 introduced a mechanism that allows the server +to push additional resources related to the response. +This chapter also describes how this feature works in +Cowboy.</p></div> +<div class="sect1"> +<h2 id="_reply">Reply</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides three functions for sending the entire reply, +depending on whether you need to set headers and body. In all +cases, Cowboy will add any headers required by the protocol +(for example the date header will always be sent).</p></div> +<div class="paragraph"><p>When you need to set only the status code, +use <code>cowboy_req:reply/2</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>When you need to set response headers at the same time, +use <code>cowboy_req:reply/3</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">303</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http://ninenines.eu"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that the header name must always be a lowercase +binary.</p></div> +<div class="paragraph"><p>When you also need to set the response body, +use <code>cowboy_req:reply/4</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span> +}, <span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You should always set the content-type header when the +response has a body. There is however no need to set +the content-length header; Cowboy does it automatically.</p></div> +<div class="paragraph"><p>The response body and the header values must be either +a binary or an iolist. An iolist is a list containing +binaries, characters, strings or other iolists. This +allows you to build a response from different parts +without having to do any concatenation:</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="color: #009900">Title</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"Hello world!"</span>, +<span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Hats off!"</span><span style="color: #990000">>></span>, +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span> +}, [<span style="color: #FF0000">"<html><head><title>"</span>, <span style="color: #009900">Title</span>, <span style="color: #FF0000">"</title></head>"</span>, + <span style="color: #FF0000">"<body><p>"</span>, <span style="color: #009900">Body</span>, <span style="color: #FF0000">"</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This method of building responses is more efficient than +concatenating. Behind the scenes, each element of the list +is simply a pointer, and those pointers are used directly +when writing to the socket.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stream_reply">Stream reply</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides two functions for initiating a response, +and an additional function for streaming the response body. +Cowboy will add any required headers to the response.</p></div> +<div class="paragraph"><p>When you need to set only the status code, +use <code>cowboy_req:stream_reply/2</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>), + +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"Hello..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"chunked..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"world!!"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The second argument to <code>cowboy_req:stream_body/3</code> indicates +whether this data terminates the body. Use <code>fin</code> for the +final flag, and <code>nofin</code> otherwise.</p></div> +<div class="paragraph"><p>This snippet does not set a content-type header. This is +not recommended. All responses with a body should have +a content-type. The header can be set beforehand, or +using the <code>cowboy_req:stream_reply/3</code>:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>), + +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<html><head>Hello world!</head>"</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<body><p>Hats off!</p></body></html>"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>HTTP provides a few different ways to stream response bodies. +Cowboy will select the most appropriate one based on the HTTP +version and the request and response headers.</p></div> +<div class="paragraph"><p>While not required by any means, it is recommended that you +set the content-length header in the response if you know it +in advance. This will ensure that the best response method +is selected and help clients understand when the response +is fully received.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_preset_response_headers">Preset response headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides functions to set response headers without +immediately sending them. They are stored in the Req object +and sent as part of the response when a reply function is +called.</p></div> +<div class="paragraph"><p>To set response headers:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Header names must be a lowercase binary.</p></div> +<div class="paragraph"><p>Do not use this function for setting cookies. Refer to +the <a href="../cookies">Cookies</a> chapter for more information.</p></div> +<div class="paragraph"><p>To check if a response header has already been set:</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: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It returns <code>true</code> if the header was set, <code>false</code> otherwise.</p></div> +<div class="paragraph"><p>To delete a response header that was set previously:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_overriding_headers">Overriding headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>As Cowboy provides different ways of setting response +headers and body, clashes may occur, so it’s important +to understand what happens when a header is set twice.</p></div> +<div class="paragraph"><p>Headers come from five different origins:</p></div> +<div class="ulist"><ul> +<li> +<p> +Protocol-specific headers (for example HTTP/1.1’s connection header) +</p> +</li> +<li> +<p> +Other required headers (for example the date header) +</p> +</li> +<li> +<p> +Preset headers +</p> +</li> +<li> +<p> +Headers given to the reply function +</p> +</li> +<li> +<p> +Set-cookie headers +</p> +</li> +</ul></div> +<div class="paragraph"><p>Cowboy does not allow overriding protocol-specific headers.</p></div> +<div class="paragraph"><p>Set-cookie headers will always be appended at the end of +the list of headers before sending the response.</p></div> +<div class="paragraph"><p>Headers given to the reply function will always override +preset headers and required headers. If a header is found +in two or three of these, then the one in the reply function +is picked and the others are dropped.</p></div> +<div class="paragraph"><p>Similarly, preset headers will always override required +headers.</p></div> +<div class="paragraph"><p>To illustrate, look at the following snippet. Cowboy by +default sends the server header with the value "Cowboy". +We can override 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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"server"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"yaws"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_preset_response_body">Preset response body</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides functions to set the response body without +immediately sending it. It is stored in the Req object and +sent when the reply function is called.</p></div> +<div class="paragraph"><p>To set the response body:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To check if a response body has already been set:</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: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It returns <code>true</code> if the body was set and is non-empty, +<code>false</code> otherwise.</p></div> +<div class="paragraph"><p>The preset response body is only sent if the reply function +used is <code>cowboy_req:reply/2</code> or <code>cowboy_req:reply/3</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_files">Sending files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides a shortcut for sending files. When +using <code>cowboy_req:reply/4</code>, or when presetting the +response header, you can give a <code>sendfile</code> tuple to +Cowboy:</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="color: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>}</tt></pre></div></div> +<div class="paragraph"><p>Depending on the values for <code>Offset</code> or <code>Length</code>, the +entire file may be sent, or just a part of it.</p></div> +<div class="paragraph"><p>The length is required even for sending the entire file. +Cowboy sends it in the content-length header.</p></div> +<div class="paragraph"><p>To send a file while replying:</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="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #FF0000">"image/png"</span> +}, {<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #993399">12345</span>, <span style="color: #FF0000">"path/to/logo.png"</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_push">Push</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP/2 protocol introduced the ability to push resources +related to the one sent in the response. Cowboy provides two +functions for that purpose: <code>cowboy_req:push/3,4</code>.</p></div> +<div class="paragraph"><p>Push is only available for HTTP/2. Cowboy will automatically +ignore push requests if the protocol doesn’t support it.</p></div> +<div class="paragraph"><p>The push function must be called before any of the reply +functions. Doing otherwise will result in a crash.</p></div> +<div class="paragraph"><p>To push a resource, you need to provide the same information +as a client performing a request would. This includes the +HTTP method, the URI and any necessary request headers.</p></div> +<div class="paragraph"><p>Cowboy by default only requires you to give the path to +the resource and the request headers. The rest of the URI +is taken from the current request (excluding the query +string, set to empty) and the method is GET by default.</p></div> +<div class="paragraph"><p>The following snippet pushes a CSS file that is linked to +in the response:</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: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span> +}, [<span style="color: #FF0000">"<html><head><title>My web page</title>"</span>, + <span style="color: #FF0000">"<link rel='stylesheet' type='text/css' href='/static/style.css'>"</span>, + <span style="color: #FF0000">"<body><p>Welcome to Erlang!</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To override the method, scheme, host, port or query string, +simply pass in a fourth argument. The following snippet +uses a different host name:</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: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div> +<div class="paragraph"><p>Pushed resources don’t have to be files. As long as the push +request is cacheable, safe and does not include a body, the +resource can be pushed.</p></div> +<div class="paragraph"><p>Under the hood, Cowboy handles pushed requests the same as +normal requests: a different process is created which will +ultimately send a response to the client.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html b/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html index bc8427be..88241cbf 100644 --- a/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html +++ b/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: REST flowcharts</title> @@ -67,250 +67,253 @@ <h1 class="lined-header"><span>REST flowcharts</span></h1> -<div class="paragraph"><p>This chapter will explain the REST handler state machine through
-a number of different diagrams.</p></div>
-<div class="paragraph"><p>There are four main paths that requests may follow. One for the
-method OPTIONS; one for the methods GET and HEAD; one for the
-methods PUT, POST and PATCH; and one for the method DELETE.</p></div>
-<div class="paragraph"><p>All paths start with the "Start" diagram, and all paths excluding
-the OPTIONS path go through the "Content negotiation" diagram
-and optionally the "Conditional requests" diagram if the resource
-exists.</p></div>
-<div class="paragraph"><p>The red squares refer to another diagram. The light green squares
-indicate a response. Other squares may be either a callback or a
-question answered by Cowboy itself. Green arrows tend to indicate
-the default behavior if the callback is undefined.</p></div>
-<div class="sect1">
-<h2 id="_start">Start</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All requests start from here.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_start.png" alt="REST starting flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>A series of callbacks are called in succession to perform
-a general checkup of the service, the request line and
-request headers.</p></div>
-<div class="paragraph"><p>The request body, if any, is not expected to have been
-received for any of these steps. It is only processed
-at the end of the "PUT, POST and PATCH methods" diagram,
-when all conditions have been met.</p></div>
-<div class="paragraph"><p>The <code>known_methods</code> and <code>allowed_methods</code> callbacks
-return a list of methods. Cowboy then checks if the request
-method is in the list, and stops otherwise.</p></div>
-<div class="paragraph"><p>The <code>is_authorized</code> callback may be used to check that
-access to the resource is authorized. Authentication
-may also be performed as needed. When authorization is
-denied, the return value from the callback must include
-a challenge applicable to the requested resource, which
-will be sent back to the client in the www-authenticate
-header.</p></div>
-<div class="paragraph"><p>This diagram is immediately followed by either the
-"OPTIONS method" diagram when the request method is
-OPTIONS, or the "Content negotiation" diagram otherwise.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options_method">OPTIONS method</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to OPTIONS requests.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_options.png" alt="REST OPTIONS method flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>The <code>options</code> callback may be used to add information
-about the resource, such as media types or languages
-provided; allowed methods; any extra information. A
-response body may also be set, although clients should
-not be expected to read it.</p></div>
-<div class="paragraph"><p>If the <code>options</code> callback is not defined, Cowboy will
-send a response containing the list of allowed methods
-by default.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_content_negotiation">Content negotiation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram applies to all request methods other than
-OPTIONS. It is executed right after the "Start" diagram
-is completed.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_conneg.png" alt="REST content negotiation flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>The purpose of these steps is to determine an appropriate
-representation to be sent back to the client.</p></div>
-<div class="paragraph"><p>The request may contain any of the accept header; the
-accept-language header; or the accept-charset header.
-When present, Cowboy will parse the headers and then
-call the corresponding callback to obtain the list
-of provided content-type, language or charset for this
-resource. It then automatically select the best match
-based on the request.</p></div>
-<div class="paragraph"><p>If a callback is not defined, Cowboy will select the
-content-type, language or charset that the client
-prefers.</p></div>
-<div class="paragraph"><p>The <code>content_types_provided</code> also returns the name of
-a callback for every content-type it accepts. This
-callback will only be called at the end of the
-"GET and HEAD methods" diagram, when all conditions
-have been met.</p></div>
-<div class="paragraph"><p>The selected content-type, language and charset are
-saved as meta values in the Req object. You <strong>should</strong>
-use the appropriate representation if you set a
-response body manually (alongside an error code,
-for example).</p></div>
-<div class="paragraph"><p>This diagram is immediately followed by
-the "GET and HEAD methods" diagram,
-the "PUT, POST and PATCH methods" diagram,
-or the "DELETE method" diagram, depending on the
-method.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_get_and_head_methods">GET and HEAD methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to GET and HEAD requests.</p></div>
-<div class="paragraph"><p>For a description of the <code>cond</code> step, please see
-the "Conditional requests" diagram.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_get_head.png" alt="REST GET/HEAD methods flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>When the resource exists, and the conditional steps
-succeed, the resource can be retrieved.</p></div>
-<div class="paragraph"><p>Cowboy prepares the response by first retrieving
-metadata about the representation, then by calling
-the <code>ProvideResource</code> callback. This is the callback
-you defined for each content-types you returned from
-<code>content_types_provided</code>. This callback returns the body
-that will be sent back to the client, or a fun if the
-body must be streamed.</p></div>
-<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out
-whether the resource existed previously, and if so whether
-it was moved elsewhere in order to redirect the client to
-the new URI.</p></div>
-<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks
-must return the new location of the resource if it was in
-fact moved.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to PUT, POST and PATCH requests.</p></div>
-<div class="paragraph"><p>For a description of the <code>cond</code> step, please see
-the "Conditional requests" diagram.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_put_post_patch.png" alt="REST PUT/POST/PATCH methods flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>When the resource exists, first the conditional steps
-are executed. When that succeeds, and the method is PUT,
-Cowboy will call the <code>is_conflict</code> callback. This function
-can be used to prevent potential race conditions, by locking
-the resource for example.</p></div>
-<div class="paragraph"><p>Then all three methods reach the <code>content_types_accepted</code>
-step that we will describe in a few paragraphs.</p></div>
-<div class="paragraph"><p>When the resource does not exist, and the method is PUT,
-Cowboy will check for conflicts and then move on to the
-<code>content_types_accepted</code> step. For other methods, Cowboy
-will figure out whether the resource existed previously,
-and if so whether it was moved elsewhere. If the resource
-is truly non-existent, the method is POST and the call
-for <code>allow_missing_post</code> returns <code>true</code>, then Cowboy will
-move on to the <code>content_types_accepted</code> step. Otherwise
-the request processing ends there.</p></div>
-<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks
-must return the new location of the resource if it was in
-fact moved.</p></div>
-<div class="paragraph"><p>The <code>content_types_accepted</code> returns a list of
-content-types it accepts, but also the name of a callback
-for each of them. Cowboy will select the appropriate
-callback for processing the request body and call it.</p></div>
-<div class="paragraph"><p>This callback may return one of three different return
-values.</p></div>
-<div class="paragraph"><p>If an error occurred while processing the request body,
-it must return <code>false</code> and Cowboy will send an
-appropriate error response.</p></div>
-<div class="paragraph"><p>If the method is POST, then you may return <code>true</code> with
-an URI of where the resource has been created. This is
-especially useful for writing handlers for collections.</p></div>
-<div class="paragraph"><p>Otherwise, return <code>true</code> to indicate success. Cowboy
-will select the appropriate response to be sent depending
-on whether a resource has been created, rather than
-modified, and on the availability of a location header
-or a body in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_delete_method">DELETE method</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to DELETE requests.</p></div>
-<div class="paragraph"><p>For a description of the <code>cond</code> step, please see
-the "Conditional requests" diagram.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_delete.png" alt="REST DELETE method flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>When the resource exists, and the conditional steps
-succeed, the resource can be deleted.</p></div>
-<div class="paragraph"><p>Deleting the resource is a two steps process. First
-the callback <code>delete_resource</code> is executed. Use this
-callback to delete the resource.</p></div>
-<div class="paragraph"><p>Because the resource may be cached, you must also
-delete all cached representations of this resource
-in the system. This operation may take a while though,
-so you may return before it finished.</p></div>
-<div class="paragraph"><p>Cowboy will then call the <code>delete_completed</code> callback.
-If you know that the resource has been completely
-deleted from your system, including from caches, then
-you can return <code>true</code>. If any doubts persist, return
-<code>false</code>. Cowboy will assume <code>true</code> by default.</p></div>
-<div class="paragraph"><p>To finish, Cowboy checks if you set a response body,
-and depending on that, sends the appropriate response.</p></div>
-<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out
-whether the resource existed previously, and if so whether
-it was moved elsewhere in order to redirect the client to
-the new URI.</p></div>
-<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks
-must return the new location of the resource if it was in
-fact moved.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_conditional_requests">Conditional requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram applies to all request methods other than
-OPTIONS. It is executed right after the <code>resource_exists</code>
-callback, when the resource exists.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_cond.png" alt="REST conditional requests flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>A request becomes conditional when it includes either of
-the if-match header; the if-unmodified-since header; the
-if-none-match header; or the if-modified-since header.</p></div>
-<div class="paragraph"><p>If the condition fails, the request ends immediately
-without any retrieval or modification of the resource.</p></div>
-<div class="paragraph"><p>The <code>generate_etag</code> and <code>last_modified</code> are called as
-needed. Cowboy will only call them once and then cache
-the results for subsequent use.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter will explain the REST handler state machine through +a number of different diagrams.</p></div> +<div class="paragraph"><p>There are four main paths that requests may follow. One for the +method OPTIONS; one for the methods GET and HEAD; one for the +methods PUT, POST and PATCH; and one for the method DELETE.</p></div> +<div class="paragraph"><p>All paths start with the "Start" diagram, and all paths excluding +the OPTIONS path go through the "Content negotiation" diagram +and optionally the "Conditional requests" diagram if the resource +exists.</p></div> +<div class="paragraph"><p>The red squares refer to another diagram. The light green squares +indicate a response. Other squares may be either a callback or a +question answered by Cowboy itself. Green arrows tend to indicate +the default behavior if the callback is undefined.</p></div> +<div class="sect1"> +<h2 id="_start">Start</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All requests start from here.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_start.png" alt="REST starting flowchart" /> +</div> +</div> +<div class="paragraph"><p>A series of callbacks are called in succession to perform +a general checkup of the service, the request line and +request headers.</p></div> +<div class="paragraph"><p>The request body, if any, is not expected to have been +received for any of these steps. It is only processed +at the end of the "PUT, POST and PATCH methods" diagram, +when all conditions have been met.</p></div> +<div class="paragraph"><p>The <code>known_methods</code> and <code>allowed_methods</code> callbacks +return a list of methods. Cowboy then checks if the request +method is in the list, and stops otherwise.</p></div> +<div class="paragraph"><p>The <code>is_authorized</code> callback may be used to check that +access to the resource is authorized. Authentication +may also be performed as needed. When authorization is +denied, the return value from the callback must include +a challenge applicable to the requested resource, which +will be sent back to the client in the www-authenticate +header.</p></div> +<div class="paragraph"><p>This diagram is immediately followed by either the +"OPTIONS method" diagram when the request method is +OPTIONS, or the "Content negotiation" diagram otherwise.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options_method">OPTIONS method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to OPTIONS requests.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_options.png" alt="REST OPTIONS method flowchart" /> +</div> +</div> +<div class="paragraph"><p>The <code>options</code> callback may be used to add information +about the resource, such as media types or languages +provided; allowed methods; any extra information. A +response body may also be set, although clients should +not be expected to read it.</p></div> +<div class="paragraph"><p>If the <code>options</code> callback is not defined, Cowboy will +send a response containing the list of allowed methods +by default.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_content_negotiation">Content negotiation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram applies to all request methods other than +OPTIONS. It is executed right after the "Start" diagram +is completed.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_conneg.png" alt="REST content negotiation flowchart" /> +</div> +</div> +<div class="paragraph"><p>The purpose of these steps is to determine an appropriate +representation to be sent back to the client.</p></div> +<div class="paragraph"><p>The request may contain any of the accept header; the +accept-language header; or the accept-charset header. +When present, Cowboy will parse the headers and then +call the corresponding callback to obtain the list +of provided content-type, language or charset for this +resource. It then automatically select the best match +based on the request.</p></div> +<div class="paragraph"><p>If a callback is not defined, Cowboy will select the +content-type, language or charset that the client +prefers.</p></div> +<div class="paragraph"><p>The <code>content_types_provided</code> also returns the name of +a callback for every content-type it accepts. This +callback will only be called at the end of the +"GET and HEAD methods" diagram, when all conditions +have been met.</p></div> +<div class="paragraph"><p>The selected content-type, language and charset are +saved as meta values in the Req object. You <strong>should</strong> +use the appropriate representation if you set a +response body manually (alongside an error code, +for example).</p></div> +<div class="paragraph"><p>This diagram is immediately followed by +the "GET and HEAD methods" diagram, +the "PUT, POST and PATCH methods" diagram, +or the "DELETE method" diagram, depending on the +method.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_get_and_head_methods">GET and HEAD methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to GET and HEAD requests.</p></div> +<div class="paragraph"><p>For a description of the <code>cond</code> step, please see +the "Conditional requests" diagram.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_get_head.png" alt="REST GET/HEAD methods flowchart" /> +</div> +</div> +<div class="paragraph"><p>When the resource exists, and the conditional steps +succeed, the resource can be retrieved.</p></div> +<div class="paragraph"><p>Cowboy prepares the response by first retrieving +metadata about the representation, then by calling +the <code>ProvideResource</code> callback. This is the callback +you defined for each content-types you returned from +<code>content_types_provided</code>. This callback returns the body +that will be sent back to the client, or a fun if the +body must be streamed.</p></div> +<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI.</p></div> +<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks +must return the new location of the resource if it was in +fact moved.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to PUT, POST and PATCH requests.</p></div> +<div class="paragraph"><p>For a description of the <code>cond</code> step, please see +the "Conditional requests" diagram.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_put_post_patch.png" alt="REST PUT/POST/PATCH methods flowchart" /> +</div> +</div> +<div class="paragraph"><p>When the resource exists, first the conditional steps +are executed. When that succeeds, and the method is PUT, +Cowboy will call the <code>is_conflict</code> callback. This function +can be used to prevent potential race conditions, by locking +the resource for example.</p></div> +<div class="paragraph"><p>Then all three methods reach the <code>content_types_accepted</code> +step that we will describe in a few paragraphs.</p></div> +<div class="paragraph"><p>When the resource does not exist, and the method is PUT, +Cowboy will check for conflicts and then move on to the +<code>content_types_accepted</code> step. For other methods, Cowboy +will figure out whether the resource existed previously, +and if so whether it was moved elsewhere. If the resource +is truly non-existent, the method is POST and the call +for <code>allow_missing_post</code> returns <code>true</code>, then Cowboy will +move on to the <code>content_types_accepted</code> step. Otherwise +the request processing ends there.</p></div> +<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks +must return the new location of the resource if it was in +fact moved.</p></div> +<div class="paragraph"><p>The <code>content_types_accepted</code> returns a list of +content-types it accepts, but also the name of a callback +for each of them. Cowboy will select the appropriate +callback for processing the request body and call it.</p></div> +<div class="paragraph"><p>This callback may return one of three different return +values.</p></div> +<div class="paragraph"><p>If an error occurred while processing the request body, +it must return <code>false</code> and Cowboy will send an +appropriate error response.</p></div> +<div class="paragraph"><p>If the method is POST, then you may return <code>true</code> with +an URI of where the resource has been created. This is +especially useful for writing handlers for collections.</p></div> +<div class="paragraph"><p>Otherwise, return <code>true</code> to indicate success. Cowboy +will select the appropriate response to be sent depending +on whether a resource has been created, rather than +modified, and on the availability of a location header +or a body in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_delete_method">DELETE method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to DELETE requests.</p></div> +<div class="paragraph"><p>For a description of the <code>cond</code> step, please see +the "Conditional requests" diagram.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_delete.png" alt="REST DELETE method flowchart" /> +</div> +</div> +<div class="paragraph"><p>When the resource exists, and the conditional steps +succeed, the resource can be deleted.</p></div> +<div class="paragraph"><p>Deleting the resource is a two steps process. First +the callback <code>delete_resource</code> is executed. Use this +callback to delete the resource.</p></div> +<div class="paragraph"><p>Because the resource may be cached, you must also +delete all cached representations of this resource +in the system. This operation may take a while though, +so you may return before it finished.</p></div> +<div class="paragraph"><p>Cowboy will then call the <code>delete_completed</code> callback. +If you know that the resource has been completely +deleted from your system, including from caches, then +you can return <code>true</code>. If any doubts persist, return +<code>false</code>. Cowboy will assume <code>true</code> by default.</p></div> +<div class="paragraph"><p>To finish, Cowboy checks if you set a response body, +and depending on that, sends the appropriate response.</p></div> +<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI.</p></div> +<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks +must return the new location of the resource if it was in +fact moved.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_conditional_requests">Conditional requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram applies to all request methods other than +OPTIONS. It is executed right after the <code>resource_exists</code> +callback, when the resource exists.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_cond.png" alt="REST conditional requests flowchart" /> +</div> +</div> +<div class="paragraph"><p>A request becomes conditional when it includes either of +the if-match header; the if-unmodified-since header; the +if-none-match header; or the if-modified-since header.</p></div> +<div class="paragraph"><p>If the condition fails, the request ends immediately +without any retrieval or modification of the resource.</p></div> +<div class="paragraph"><p>The <code>generate_etag</code> and <code>last_modified</code> are called as +needed. Cowboy will only call them once and then cache +the results for subsequent use.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_get_head.png b/docs/en/cowboy/2.0/guide/rest_get_head.png Binary files differindex efee892a..211ab603 100644 --- a/docs/en/cowboy/2.0/guide/rest_get_head.png +++ b/docs/en/cowboy/2.0/guide/rest_get_head.png diff --git a/docs/en/cowboy/2.0/guide/rest_get_head.svg b/docs/en/cowboy/2.0/guide/rest_get_head.svg index c78e9399..92030cf3 100644 --- a/docs/en/cowboy/2.0/guide/rest_get_head.svg +++ b/docs/en/cowboy/2.0/guide/rest_get_head.svg @@ -15,7 +15,7 @@ height="1052.3622047" id="svg2" version="1.1" - inkscape:version="0.48.4 r9939" + inkscape:version="0.92.1 r" sodipodi:docname="rest_get_head.svg" inkscape:export-filename="/home/essen/Dropbox/Public/drawing.png" inkscape:export-xdpi="90" @@ -65,15 +65,15 @@ inkscape:pageopacity="1" inkscape:pageshadow="2" inkscape:zoom="1.4142136" - inkscape:cx="122.28875" - inkscape:cy="777.29526" + inkscape:cx="353.51266" + inkscape:cy="522.73683" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" - inkscape:window-width="2560" - inkscape:window-height="1402" + inkscape:window-width="1920" + inkscape:window-height="1043" inkscape:window-x="0" - inkscape:window-y="38" + inkscape:window-y="0" inkscape:window-maximized="1" inkscape:snap-global="true" showguides="true"> @@ -93,7 +93,7 @@ <dc:format>image/svg+xml</dc:format> <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> + <dc:title /> </cc:Work> </rdf:RDF> </metadata> @@ -514,135 +514,135 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="-58.692513" y="114.39204" - id="text5371" - sodipodi:linespacing="125%"><tspan + id="text5371"><tspan sodipodi:role="line" id="tspan5373" x="-58.692513" - y="114.39204">some text</tspan></text> + y="114.39204" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-58.692513" y="53.112247" - id="text5371-2" - sodipodi:linespacing="125%"><tspan + id="text5371-2"><tspan sodipodi:role="line" id="tspan5373-6" x="-58.692513" - y="53.112247">some text</tspan></text> + y="53.112247" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="213.07524" y="379.78381" id="text5371-2-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7" x="213.07524" - y="379.78381">last_modified</tspan></text> + y="379.78381" + style="font-size:16px;line-height:1.25;font-family:sans-serif">last_modified</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="212.74321" y="546.59912" id="text5371-2-3-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3" x="212.74321" - y="546.59912">ProvideResource</tspan></text> + y="546.59912" + style="font-size:16px;line-height:1.25;font-family:sans-serif">ProvideCallback</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="-58.692513" y="236.95154" - id="text5371-4" - sodipodi:linespacing="125%"><tspan + id="text5371-4"><tspan sodipodi:role="line" id="tspan5373-9" x="-58.692513" - y="236.95154">some text</tspan></text> + y="236.95154" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="359.14185" y="50.482433" id="text5371-4-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="359.14185" y="50.482433" - id="tspan17171">conneg</tspan></text> + id="tspan17171" + style="font-size:16px;line-height:1.25;font-family:sans-serif">conneg</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="212.77055" y="627.34662" id="text5371-2-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-8" x="212.77055" - y="627.34662">multiple_choices</tspan></text> + y="627.34662" + style="font-size:16px;line-height:1.25;font-family:sans-serif">multiple_choices</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="358.52466" y="134.49161" id="text5371-2-95" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-80" x="358.52466" - y="134.49161">resource_exists</tspan></text> + y="134.49161" + style="font-size:16px;line-height:1.25;font-family:sans-serif">resource_exists</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="213.38774" y="296.80188" id="text5371-2-32" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27" x="213.38774" - y="296.80188">generate_etag</tspan></text> + y="296.80188" + style="font-size:16px;line-height:1.25;font-family:sans-serif">generate_etag</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="213.05571" y="462.5274" id="text5371-2-74" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18" x="213.05571" - y="462.5274">expires</tspan></text> + y="462.5274" + style="font-size:16px;line-height:1.25;font-family:sans-serif">expires</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-2" @@ -653,32 +653,32 @@ rx="15" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="251.83722" y="175.92931" id="text5371-2-391" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63" x="251.83722" - y="175.92931">true</tspan></text> + y="175.92931" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="161.54012" y="670.38055" id="text5371-2-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3" x="161.54012" - y="670.38055">false</tspan></text> + y="670.38055" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="matrix(0,-1,1,0,-513.31414,353.05561)" id="g5650-2"> @@ -707,18 +707,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="447.26678" y="176.39024" id="text5371-4-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-0" x="447.26678" - y="176.39024">false</tspan></text> + y="176.39024" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(563.72619,-141.76777)" id="g5650-2-2"> @@ -758,19 +758,19 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-544.69421" y="-354.17184" id="text5371-2-3-0-7" - sodipodi:linespacing="125%" - transform="matrix(0,-1,1,0,0,0)" + transform="rotate(-90)" inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3-9" x="-544.69421" - y="-354.17184">middlewares</tspan></text> + y="-354.17184" + style="font-size:16px;line-height:1.25;font-family:sans-serif">middlewares</tspan></text> <g transform="matrix(0,-1,1,0,-508.93096,565.23553)" id="g5650-2-0-4" @@ -804,32 +804,32 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="46.409981" y="711.18011" id="text5371-4-3-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-62-9" x="46.409981" - y="711.18011">true</tspan></text> + y="711.18011" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="545.12921" y="257.43518" id="text5371-4-4-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6" x="545.12921" - y="257.43518">true</tspan></text> + y="257.43518" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0.70710678,0.70710678,-0.70710678,0.70710678,547.47379,-62.310424)" id="g5650-9-9" @@ -872,18 +872,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="213.38774" y="216.5154" id="text5371-4-0-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="213.38774" y="216.5154" - id="tspan17171-6">cond</tspan></text> + id="tspan17171-6" + style="font-size:16px;line-height:1.25;font-family:sans-serif">cond</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-1" @@ -897,18 +897,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="212.88774" y="792.61121" id="text5371-43-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-62" x="212.88774" - y="792.61121">300 multiple choices</tspan></text> + y="792.61121" + style="font-size:16px;line-height:1.25;font-family:sans-serif">300 multiple choices</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8" @@ -922,18 +922,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="212.35258" y="711.50043" id="text5371-43-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1" x="212.35258" - y="711.50043">200 OK</tspan></text> + y="711.50043" + style="font-size:16px;line-height:1.25;font-family:sans-serif">200 OK</tspan></text> <g transform="matrix(0,-1,-1,0,1028.2004,317.70407)" id="g5650-2-0-4-3-8" @@ -978,32 +978,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.77957" y="216.51541" id="text5371-2-32-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-8" x="505.77957" - y="216.51541">has if-match?</tspan></text> + y="216.51541" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has if-match?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="651.74426" y="299.27689" id="text5371-2-391-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7" x="651.74426" - y="299.27689">false</tspan></text> + y="299.27689" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(563.72619,22.800669)" id="g5650-0-6" @@ -1077,18 +1077,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.94363" y="379.78381" id="text5371-2-32-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-1" x="505.94363" - y="379.78381">previously_existed</tspan></text> + y="379.78381" + style="font-size:16px;line-height:1.25;font-family:sans-serif">previously_existed</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5" @@ -1102,32 +1102,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="506.2796" y="463.83755" id="text5371-43-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9" x="506.2796" - y="463.83755">404 not found</tspan></text> + y="463.83755" + style="font-size:16px;line-height:1.25;font-family:sans-serif">404 not found</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="528.75421" y="422.69736" id="text5371-2-8-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4" x="528.75421" - y="422.69736">false</tspan></text> + y="422.69736" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(563.72619,187.85116)" id="g5650-2-2-17"> @@ -1198,18 +1198,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.45535" y="544.82568" id="text5371-2-74-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2" x="505.45535" - y="544.82568">moved_permanently</tspan></text> + y="544.82568" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_permanently</tspan></text> <g transform="matrix(0,-1,-1,0,347.00351,567.35686)" id="g5650-2-0-4-3-8-9" @@ -1254,60 +1254,60 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="506.2796" y="297.7261" id="text5371-43" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3" x="506.2796" - y="297.7261">412 precondition failed</tspan></text> + y="297.7261" + style="font-size:16px;line-height:1.25;font-family:sans-serif">412 precondition failed</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="668.11926" y="463.37662" id="text5371-4-3-9-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-62-9-9" x="668.11926" - y="463.37662">true</tspan></text> + y="463.37662" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="549.12921" y="587.59863" id="text5371-4-4-9-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2" x="549.12921" - y="587.59863">true*</tspan></text> + y="587.59863" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="651.74426" y="628.87946" id="text5371-2-391-5-5-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9" x="651.74426" - y="628.87946">false</tspan></text> + y="628.87946" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9" @@ -1321,18 +1321,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="505.57257" y="627.32867" id="text5371-43-2-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7" x="505.57257" - y="627.32867">301 moved permanently</tspan></text> + y="627.32867" + style="font-size:16px;line-height:1.25;font-family:sans-serif">301 moved permanently</tspan></text> <g transform="translate(563.72619,353.12604)" id="g5650-2-2-65"> @@ -1403,46 +1403,46 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.45535" y="709.62695" id="text5371-2-74-0-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8" x="505.45535" - y="709.62695">moved_temporarily</tspan></text> + y="709.62695" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_temporarily</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="549.12921" y="752.64056" id="text5371-4-4-9-3-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-6" x="549.12921" - y="752.64056">true*</tspan></text> + y="752.64056" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="651.74426" y="794.16199" id="text5371-2-391-5-5-1-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-2" x="651.74426" - y="794.16199">false</tspan></text> + y="794.16199" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2" @@ -1456,18 +1456,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="505.57257" y="792.61121" id="text5371-43-2-9-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8" x="505.57257" - y="792.61121">307 moved temporarily</tspan></text> + y="792.61121" + style="font-size:16px;line-height:1.25;font-family:sans-serif">307 moved temporarily</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-4" @@ -1481,18 +1481,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="505.97882" y="874.99164" id="text5371-43-2-9-7-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-7" x="505.97882" - y="874.99164">410 gone</tspan></text> + y="874.99164" + style="font-size:16px;line-height:1.25;font-family:sans-serif">410 gone</tspan></text> <g transform="translate(31.619614,4.2328831)" id="g5650-2-2-6"> diff --git a/docs/en/cowboy/2.0/guide/rest_handlers/index.html b/docs/en/cowboy/2.0/guide/rest_handlers/index.html index f27c58fc..93a311d0 100644 --- a/docs/en/cowboy/2.0/guide/rest_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/rest_handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: REST handlers</title> @@ -67,289 +67,292 @@ <h1 class="lined-header"><span>REST handlers</span></h1> -<div class="paragraph"><p>REST is implemented in Cowboy as a sub protocol. The request
-is handled as a state machine with many optional callbacks
-describing the resource and modifying the machine’s behavior.</p></div>
-<div class="paragraph"><p>The REST handler is the recommended way to handle HTTP requests.</p></div>
-<div class="sect1">
-<h2 id="_initialization">Initialization</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>First, the <code>init/2</code> callback is called. This callback is common
-to all handlers. To use REST for the current request, this function
-must return a <code>cowboy_rest</code> tuple.</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy will then switch to the REST protocol and start executing
-the state machine.</p></div>
-<div class="paragraph"><p>After reaching the end of the flowchart, the <code>terminate/3</code> callback
-will be called if it is defined.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_methods">Methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The REST component has code for handling the following HTTP methods:
-HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.</p></div>
-<div class="paragraph"><p>Other methods can be accepted, however they have no specific callback
-defined for them at this time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All callbacks are optional. Some may become mandatory depending
-on what other defined callbacks return. The various flowcharts
-in the next chapter should be a useful to determine which callbacks
-you need.</p></div>
-<div class="paragraph"><p>All callbacks take two arguments, the Req object and the State,
-and return a three-element tuple of the form <code>{Value, Req, State}</code>.</p></div>
-<div class="paragraph"><p>All callbacks can also return <code>{stop, Req, State}</code> to stop execution
-of the request.</p></div>
-<div class="paragraph"><p>The following table summarizes the callbacks and their default values.
-If the callback isn’t defined, then the default value will be used.
-Please look at the flowcharts to find out the result of each return
-value.</p></div>
-<div class="paragraph"><p>In the following table, "skip" means the callback is entirely skipped
-if it is undefined, moving directly to the next step. Similarly,
-"none" means there is no default value for this callback.</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Callback name </th>
-<th align="center" valign="top"> Default value</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">allowed_methods</p></td>
-<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">allow_missing_post</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">charsets_provided</p></td>
-<td align="center" valign="top"><p class="table">skip</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">content_types_accepted</p></td>
-<td align="center" valign="top"><p class="table">none</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">content_types_provided</p></td>
-<td align="center" valign="top"><p class="table"><code>[{{ <<"text">>, <<"html">>, '*'}, to_html}]</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">delete_completed</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">delete_resource</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">expires</p></td>
-<td align="center" valign="top"><p class="table"><code>undefined</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">forbidden</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">generate_etag</p></td>
-<td align="center" valign="top"><p class="table"><code>undefined</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">is_authorized</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">is_conflict</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">known_methods</p></td>
-<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">languages_provided</p></td>
-<td align="center" valign="top"><p class="table">skip</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">last_modified</p></td>
-<td align="center" valign="top"><p class="table"><code>undefined</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">malformed_request</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">moved_permanently</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">moved_temporarily</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">multiple_choices</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">options</p></td>
-<td align="center" valign="top"><p class="table"><code>ok</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">previously_existed</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">resource_exists</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">service_available</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">uri_too_long</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">valid_content_headers</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">valid_entity_length</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">variances</p></td>
-<td align="center" valign="top"><p class="table"><code>[]</code></p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>As you can see, Cowboy tries to move on with the request whenever
-possible by using well thought out default values.</p></div>
-<div class="paragraph"><p>In addition to these, there can be any number of user-defined
-callbacks that are specified through <code>content_types_accepted/2</code>
-and <code>content_types_provided/2</code>. They can take any name, however
-it is recommended to use a separate prefix for the callbacks of
-each function. For example, <code>from_html</code> and <code>to_html</code> indicate
-in the first case that we’re accepting a resource given as HTML,
-and in the second case that we send one as HTML.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_meta_data">Meta data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will set informative values to the Req object at various
-points of the execution. You can retrieve them by matching the
-Req object directly. The values are defined in the following table:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Key </th>
-<th align="left" valign="top"> Details</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">media_type</p></td>
-<td align="left" valign="top"><p class="table">The content-type negotiated for the response entity.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">language</p></td>
-<td align="left" valign="top"><p class="table">The language negotiated for the response entity.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">charset</p></td>
-<td align="left" valign="top"><p class="table">The charset negotiated for the response entity.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>They can be used to send a proper body with the response to a
-request that used a method other than HEAD or GET.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_response_headers">Response headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will set response headers automatically over the execution
-of the REST code. They are listed in the following table.</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Header name </th>
-<th align="left" valign="top"> Details</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">content-language</p></td>
-<td align="left" valign="top"><p class="table">Language used in the response body</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">content-type</p></td>
-<td align="left" valign="top"><p class="table">Media type and charset of the response body</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">etag</p></td>
-<td align="left" valign="top"><p class="table">Etag of the resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">expires</p></td>
-<td align="left" valign="top"><p class="table">Expiration date of the resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">last-modified</p></td>
-<td align="left" valign="top"><p class="table">Last modification date for the resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">location</p></td>
-<td align="left" valign="top"><p class="table">Relative or absolute URI to the requested resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">vary</p></td>
-<td align="left" valign="top"><p class="table">List of headers that may change the representation of the resource</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
+<div class="paragraph"><p>REST is implemented in Cowboy as a sub protocol. The request +is handled as a state machine with many optional callbacks +describing the resource and modifying the machine’s behavior.</p></div> +<div class="paragraph"><p>The REST handler is the recommended way to handle HTTP requests.</p></div> +<div class="sect1"> +<h2 id="_initialization">Initialization</h2> +<div class="sectionbody"> +<div class="paragraph"><p>First, the <code>init/2</code> callback is called. This callback is common +to all handlers. To use REST for the current request, this function +must return a <code>cowboy_rest</code> tuple.</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy will then switch to the REST protocol and start executing +the state machine.</p></div> +<div class="paragraph"><p>After reaching the end of the flowchart, the <code>terminate/3</code> callback +will be called if it is defined.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_methods">Methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The REST component has code for handling the following HTTP methods: +HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.</p></div> +<div class="paragraph"><p>Other methods can be accepted, however they have no specific callback +defined for them at this time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All callbacks are optional. Some may become mandatory depending +on what other defined callbacks return. The various flowcharts +in the next chapter should be a useful to determine which callbacks +you need.</p></div> +<div class="paragraph"><p>All callbacks take two arguments, the Req object and the State, +and return a three-element tuple of the form <code>{Value, Req, State}</code>.</p></div> +<div class="paragraph"><p>All callbacks can also return <code>{stop, Req, State}</code> to stop execution +of the request.</p></div> +<div class="paragraph"><p>The following table summarizes the callbacks and their default values. +If the callback isn’t defined, then the default value will be used. +Please look at the flowcharts to find out the result of each return +value.</p></div> +<div class="paragraph"><p>In the following table, "skip" means the callback is entirely skipped +if it is undefined, moving directly to the next step. Similarly, +"none" means there is no default value for this callback.</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Callback name </th> +<th align="center" valign="top"> Default value</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">allowed_methods</p></td> +<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">allow_missing_post</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">charsets_provided</p></td> +<td align="center" valign="top"><p class="table">skip</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">content_types_accepted</p></td> +<td align="center" valign="top"><p class="table">none</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">content_types_provided</p></td> +<td align="center" valign="top"><p class="table"><code>[{{ <<"text">>, <<"html">>, '*'}, to_html}]</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">delete_completed</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">delete_resource</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">expires</p></td> +<td align="center" valign="top"><p class="table"><code>undefined</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">forbidden</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">generate_etag</p></td> +<td align="center" valign="top"><p class="table"><code>undefined</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">is_authorized</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">is_conflict</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">known_methods</p></td> +<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">languages_provided</p></td> +<td align="center" valign="top"><p class="table">skip</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">last_modified</p></td> +<td align="center" valign="top"><p class="table"><code>undefined</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">malformed_request</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">moved_permanently</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">moved_temporarily</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">multiple_choices</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">options</p></td> +<td align="center" valign="top"><p class="table"><code>ok</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">previously_existed</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">resource_exists</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">service_available</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">uri_too_long</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">valid_content_headers</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">valid_entity_length</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">variances</p></td> +<td align="center" valign="top"><p class="table"><code>[]</code></p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>As you can see, Cowboy tries to move on with the request whenever +possible by using well thought out default values.</p></div> +<div class="paragraph"><p>In addition to these, there can be any number of user-defined +callbacks that are specified through <code>content_types_accepted/2</code> +and <code>content_types_provided/2</code>. They can take any name, however +it is recommended to use a separate prefix for the callbacks of +each function. For example, <code>from_html</code> and <code>to_html</code> indicate +in the first case that we’re accepting a resource given as HTML, +and in the second case that we send one as HTML.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_meta_data">Meta data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will set informative values to the Req object at various +points of the execution. You can retrieve them by matching the +Req object directly. The values are defined in the following table:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Key </th> +<th align="left" valign="top"> Details</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">media_type</p></td> +<td align="left" valign="top"><p class="table">The content-type negotiated for the response entity.</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">language</p></td> +<td align="left" valign="top"><p class="table">The language negotiated for the response entity.</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">charset</p></td> +<td align="left" valign="top"><p class="table">The charset negotiated for the response entity.</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>They can be used to send a proper body with the response to a +request that used a method other than HEAD or GET.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_response_headers">Response headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will set response headers automatically over the execution +of the REST code. They are listed in the following table.</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Header name </th> +<th align="left" valign="top"> Details</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">content-language</p></td> +<td align="left" valign="top"><p class="table">Language used in the response body</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">content-type</p></td> +<td align="left" valign="top"><p class="table">Media type and charset of the response body</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">etag</p></td> +<td align="left" valign="top"><p class="table">Etag of the resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">expires</p></td> +<td align="left" valign="top"><p class="table">Expiration date of the resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">last-modified</p></td> +<td align="left" valign="top"><p class="table">Last modification date for the resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">location</p></td> +<td align="left" valign="top"><p class="table">Relative or absolute URI to the requested resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">vary</p></td> +<td align="left" valign="top"><p class="table">List of headers that may change the representation of the resource</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_principles/index.html b/docs/en/cowboy/2.0/guide/rest_principles/index.html index 94ec56f5..c221d123 100644 --- a/docs/en/cowboy/2.0/guide/rest_principles/index.html +++ b/docs/en/cowboy/2.0/guide/rest_principles/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: REST principles</title> @@ -67,159 +67,162 @@ <h1 class="lined-header"><span>REST principles</span></h1> -<div class="paragraph"><p>This chapter will attempt to define the concepts behind REST
-and explain what makes a service RESTful.</p></div>
-<div class="paragraph"><p>REST is often confused with performing a distinct operation
-depending on the HTTP method, while using more than the GET
-and POST methods. That’s highly misguided at best.</p></div>
-<div class="paragraph"><p>We will first attempt to define REST and will look at what
-it means in the context of HTTP and the Web.
-For a more in-depth explanation of REST, you can read
-<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Roy T. Fielding’s dissertation</a>
-as it does a great job explaining where it comes from and
-what it achieves.</p></div>
-<div class="sect1">
-<h2 id="_rest_architecture">REST architecture</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>REST is a <strong>client-server</strong> architecture. The client and the server
-both have a different set of concerns. The server stores and/or
-manipulates information and makes it available to the user in
-an efficient manner. The client takes that information and
-displays it to the user and/or uses it to perform subsequent
-requests for information. This separation of concerns allows both
-the client and the server to evolve independently as it only
-requires that the interface stays the same.</p></div>
-<div class="paragraph"><p>REST is <strong>stateless</strong>. That means the communication between the
-client and the server always contains all the information needed
-to perform the request. There is no session state in the server,
-it is kept entirely on the client’s side. If access to a resource
-requires authentication, then the client needs to authenticate
-itself with every request.</p></div>
-<div class="paragraph"><p>REST is <strong>cacheable</strong>. The client, the server and any intermediary
-components can all cache resources in order to improve performance.</p></div>
-<div class="paragraph"><p>REST provides a <strong>uniform interface</strong> between components. This
-simplifies the architecture, as all components follow the same
-rules to speak to one another. It also makes it easier to understand
-the interactions between the different components of the system.
-A number of constraints are required to achieve this. They are
-covered in the rest of the chapter.</p></div>
-<div class="paragraph"><p>REST is a <strong>layered system</strong>. Individual components cannot see
-beyond the immediate layer with which they are interacting. This
-means that a client connecting to an intermediate component, like
-a proxy, has no knowledge of what lies beyond. This allows
-components to be independent and thus easily replaceable or
-extendable.</p></div>
-<div class="paragraph"><p>REST optionally provides <strong>code on demand</strong>. Code may be downloaded
-to extend client functionality. This is optional however because
-the client may not be able to download or run this code, and so
-a REST component cannot rely on it being executed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_resources_and_resource_identifiers">Resources and resource identifiers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A resource is an abstract concept. In a REST system, any information
-that can be named may be a resource. This includes documents, images,
-a collection of resources and any other information. Any information
-that can be the target of an hypertext link can be a resource.</p></div>
-<div class="paragraph"><p>A resource is a conceptual mapping to a set of entities. The set of
-entities evolves over time; a resource doesn’t. For example, a resource
-can map to "users who have logged in this past month" and another
-to "all users". At some point in time they may map to the same set of
-entities, because all users logged in this past month. But they are
-still different resources. Similarly, if nobody logged in recently,
-then the first resource may map to the empty set. This resource exists
-regardless of the information it maps to.</p></div>
-<div class="paragraph"><p>Resources are identified by uniform resource identifiers, also known
-as URIs. Sometimes internationalized resource identifiers, or IRIs,
-may also be used, but these can be directly translated into a URI.</p></div>
-<div class="paragraph"><p>In practice we will identify two kinds of resources. Individual
-resources map to a set of one element, for example "user Joe".
-Collection of resources map to a set of 0 to N elements,
-for example "all users".</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_resource_representations">Resource representations</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The representation of a resource is a sequence of bytes associated
-with metadata.</p></div>
-<div class="paragraph"><p>The metadata comes as a list of key-value pairs, where the name
-corresponds to a standard that defines the value’s structure and
-semantics. With HTTP, the metadata comes in the form of request
-or response headers. The headers' structure and semantics are well
-defined in the HTTP standard. Metadata includes representation
-metadata, resource metadata and control data.</p></div>
-<div class="paragraph"><p>The representation metadata gives information about the
-representation, such as its media type, the date of last
-modification, or even a checksum.</p></div>
-<div class="paragraph"><p>Resource metadata could be link to related resources or
-information about additional representations of the resource.</p></div>
-<div class="paragraph"><p>Control data allows parameterizing the request or response.
-For example, we may only want the representation returned if
-it is more recent than the one we have in cache. Similarly,
-we may want to instruct the client about how it should cache
-the representation. This isn’t restricted to caching. We may,
-for example, want to store a new representation of a resource
-only if it wasn’t modified since we first retrieved it.</p></div>
-<div class="paragraph"><p>The data format of a representation is also known as the media
-type. Some media types are intended for direct rendering to the
-user, while others are intended for automated processing. The
-media type is a key component of the REST architecture.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_self_descriptive_messages">Self-descriptive messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Messages must be self-descriptive. That means that the data
-format of a representation must always come with its media
-type (and similarly requesting a resource involves choosing
-the media type of the representation returned). If you are
-sending HTML, then you must say it is HTML by sending the
-media type with the representation. In HTTP this is done
-using the content-type header.</p></div>
-<div class="paragraph"><p>The media type is often an IANA registered media type, like
-<code>text/html</code> or <code>image/png</code>, but does not need to be. Exactly
-two things are important for respecting this constraint: that
-the media type is well specified, and that the sender and
-recipient agree about what the media type refers to.</p></div>
-<div class="paragraph"><p>This means that you can create your own media types, like
-<code>application/x-mine</code>, and that as long as you write the
-specifications for it and that both endpoints agree about
-it then the constraint is respected.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hypermedia_as_the_engine_of_application_state">Hypermedia as the engine of application state</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The last constraint is generally where services that claim
-to be RESTful fail. Interactions with a server must be
-entirely driven by hypermedia. The client does not need
-any prior knowledge of the service in order to use it,
-other than an entry point and of course basic understanding
-of the media type of the representations, at the very least
-enough to find and identify hyperlinks and link relations.</p></div>
-<div class="paragraph"><p>To give a simple example, if your service only works with
-the <code>application/json</code> media type then this constraint
-cannot be respected (as there are no concept of links in
-JSON) and thus your service isn’t RESTful. This is the case
-for the majority of self-proclaimed REST services.</p></div>
-<div class="paragraph"><p>On the other hand if you create a JSON based media type
-that has a concept of links and link relations, then
-your service might be RESTful.</p></div>
-<div class="paragraph"><p>Respecting this constraint means that the entirety of the
-service becomes self-discoverable, not only the resources
-in it, but also the operations you can perform on it. This
-makes clients very thin as there is no need to implement
-anything specific to the service to operate on it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter will attempt to define the concepts behind REST +and explain what makes a service RESTful.</p></div> +<div class="paragraph"><p>REST is often confused with performing a distinct operation +depending on the HTTP method, while using more than the GET +and POST methods. That’s highly misguided at best.</p></div> +<div class="paragraph"><p>We will first attempt to define REST and will look at what +it means in the context of HTTP and the Web. +For a more in-depth explanation of REST, you can read +<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Roy T. Fielding’s dissertation</a> +as it does a great job explaining where it comes from and +what it achieves.</p></div> +<div class="sect1"> +<h2 id="_rest_architecture">REST architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>REST is a <strong>client-server</strong> architecture. The client and the server +both have a different set of concerns. The server stores and/or +manipulates information and makes it available to the user in +an efficient manner. The client takes that information and +displays it to the user and/or uses it to perform subsequent +requests for information. This separation of concerns allows both +the client and the server to evolve independently as it only +requires that the interface stays the same.</p></div> +<div class="paragraph"><p>REST is <strong>stateless</strong>. That means the communication between the +client and the server always contains all the information needed +to perform the request. There is no session state in the server, +it is kept entirely on the client’s side. If access to a resource +requires authentication, then the client needs to authenticate +itself with every request.</p></div> +<div class="paragraph"><p>REST is <strong>cacheable</strong>. The client, the server and any intermediary +components can all cache resources in order to improve performance.</p></div> +<div class="paragraph"><p>REST provides a <strong>uniform interface</strong> between components. This +simplifies the architecture, as all components follow the same +rules to speak to one another. It also makes it easier to understand +the interactions between the different components of the system. +A number of constraints are required to achieve this. They are +covered in the rest of the chapter.</p></div> +<div class="paragraph"><p>REST is a <strong>layered system</strong>. Individual components cannot see +beyond the immediate layer with which they are interacting. This +means that a client connecting to an intermediate component, like +a proxy, has no knowledge of what lies beyond. This allows +components to be independent and thus easily replaceable or +extendable.</p></div> +<div class="paragraph"><p>REST optionally provides <strong>code on demand</strong>. Code may be downloaded +to extend client functionality. This is optional however because +the client may not be able to download or run this code, and so +a REST component cannot rely on it being executed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_resources_and_resource_identifiers">Resources and resource identifiers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A resource is an abstract concept. In a REST system, any information +that can be named may be a resource. This includes documents, images, +a collection of resources and any other information. Any information +that can be the target of an hypertext link can be a resource.</p></div> +<div class="paragraph"><p>A resource is a conceptual mapping to a set of entities. The set of +entities evolves over time; a resource doesn’t. For example, a resource +can map to "users who have logged in this past month" and another +to "all users". At some point in time they may map to the same set of +entities, because all users logged in this past month. But they are +still different resources. Similarly, if nobody logged in recently, +then the first resource may map to the empty set. This resource exists +regardless of the information it maps to.</p></div> +<div class="paragraph"><p>Resources are identified by uniform resource identifiers, also known +as URIs. Sometimes internationalized resource identifiers, or IRIs, +may also be used, but these can be directly translated into a URI.</p></div> +<div class="paragraph"><p>In practice we will identify two kinds of resources. Individual +resources map to a set of one element, for example "user Joe". +Collection of resources map to a set of 0 to N elements, +for example "all users".</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_resource_representations">Resource representations</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The representation of a resource is a sequence of bytes associated +with metadata.</p></div> +<div class="paragraph"><p>The metadata comes as a list of key-value pairs, where the name +corresponds to a standard that defines the value’s structure and +semantics. With HTTP, the metadata comes in the form of request +or response headers. The headers' structure and semantics are well +defined in the HTTP standard. Metadata includes representation +metadata, resource metadata and control data.</p></div> +<div class="paragraph"><p>The representation metadata gives information about the +representation, such as its media type, the date of last +modification, or even a checksum.</p></div> +<div class="paragraph"><p>Resource metadata could be link to related resources or +information about additional representations of the resource.</p></div> +<div class="paragraph"><p>Control data allows parameterizing the request or response. +For example, we may only want the representation returned if +it is more recent than the one we have in cache. Similarly, +we may want to instruct the client about how it should cache +the representation. This isn’t restricted to caching. We may, +for example, want to store a new representation of a resource +only if it wasn’t modified since we first retrieved it.</p></div> +<div class="paragraph"><p>The data format of a representation is also known as the media +type. Some media types are intended for direct rendering to the +user, while others are intended for automated processing. The +media type is a key component of the REST architecture.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_self_descriptive_messages">Self-descriptive messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Messages must be self-descriptive. That means that the data +format of a representation must always come with its media +type (and similarly requesting a resource involves choosing +the media type of the representation returned). If you are +sending HTML, then you must say it is HTML by sending the +media type with the representation. In HTTP this is done +using the content-type header.</p></div> +<div class="paragraph"><p>The media type is often an IANA registered media type, like +<code>text/html</code> or <code>image/png</code>, but does not need to be. Exactly +two things are important for respecting this constraint: that +the media type is well specified, and that the sender and +recipient agree about what the media type refers to.</p></div> +<div class="paragraph"><p>This means that you can create your own media types, like +<code>application/x-mine</code>, and that as long as you write the +specifications for it and that both endpoints agree about +it then the constraint is respected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hypermedia_as_the_engine_of_application_state">Hypermedia as the engine of application state</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The last constraint is generally where services that claim +to be RESTful fail. Interactions with a server must be +entirely driven by hypermedia. The client does not need +any prior knowledge of the service in order to use it, +other than an entry point and of course basic understanding +of the media type of the representations, at the very least +enough to find and identify hyperlinks and link relations.</p></div> +<div class="paragraph"><p>To give a simple example, if your service only works with +the <code>application/json</code> media type then this constraint +cannot be respected (as there are no concept of links in +JSON) and thus your service isn’t RESTful. This is the case +for the majority of self-proclaimed REST services.</p></div> +<div class="paragraph"><p>On the other hand if you create a JSON based media type +that has a concept of links and link relations, then +your service might be RESTful.</p></div> +<div class="paragraph"><p>Respecting this constraint means that the entirety of the +service becomes self-discoverable, not only the resources +in it, but also the operations you can perform on it. This +makes clients very thin as there is no need to implement +anything specific to the service to operate on it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_put_post_patch.png b/docs/en/cowboy/2.0/guide/rest_put_post_patch.png Binary files differindex 4afca9e9..176650e9 100644 --- a/docs/en/cowboy/2.0/guide/rest_put_post_patch.png +++ b/docs/en/cowboy/2.0/guide/rest_put_post_patch.png diff --git a/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg b/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg index 263cc942..06d55052 100644 --- a/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg +++ b/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg @@ -15,7 +15,7 @@ height="1052.3622" id="svg2" version="1.1" - inkscape:version="0.48.4 r9939" + inkscape:version="0.92.1 r" sodipodi:docname="rest_put_post_patch.svg" inkscape:export-filename="/home/essen/Dropbox/Public/drawing.png" inkscape:export-xdpi="90" @@ -64,16 +64,16 @@ borderopacity="1.0" inkscape:pageopacity="1" inkscape:pageshadow="2" - inkscape:zoom="2" - inkscape:cx="299.56028" - inkscape:cy="-395.99137" + inkscape:zoom="0.70710678" + inkscape:cx="201.51415" + inkscape:cy="-214.71801" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" - inkscape:window-width="2560" - inkscape:window-height="1402" + inkscape:window-width="1920" + inkscape:window-height="1043" inkscape:window-x="0" - inkscape:window-y="38" + inkscape:window-y="0" inkscape:window-maximized="1" inkscape:snap-global="true" showguides="true"> @@ -255,65 +255,65 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="-58.692513" y="114.39204" - id="text5371" - sodipodi:linespacing="125%"><tspan + id="text5371"><tspan sodipodi:role="line" id="tspan5373" x="-58.692513" - y="114.39204">some text</tspan></text> + y="114.39204" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-58.692513" y="53.112247" - id="text5371-2" - sodipodi:linespacing="125%"><tspan + id="text5371-2"><tspan sodipodi:role="line" id="tspan5373-6" x="-58.692513" - y="53.112247">some text</tspan></text> + y="53.112247" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="-58.692513" y="236.95154" - id="text5371-4" - sodipodi:linespacing="125%"><tspan + id="text5371-4"><tspan sodipodi:role="line" id="tspan5373-9" x="-58.692513" - y="236.95154">some text</tspan></text> + y="236.95154" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="313.14185" y="50.482433" id="text5371-4-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="313.14185" y="50.482433" - id="tspan17171">conneg</tspan></text> + id="tspan17171" + style="font-size:16px;line-height:1.25;font-family:sans-serif">conneg</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="312.52466" y="134.49161" id="text5371-2-95" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-80" x="312.52466" - y="134.49161">resource_exists</tspan></text> + y="134.49161" + style="font-size:16px;line-height:1.25;font-family:sans-serif">resource_exists</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-2" @@ -324,18 +324,18 @@ rx="15" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="205.83722" y="175.92931" id="text5371-2-391" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63" x="205.83722" - y="175.92931">true</tspan></text> + y="175.92931" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0,-1,1,0,-586.85324,629.53436)" id="g5650-2"> @@ -364,18 +364,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="401.26678" y="176.39024" id="text5371-4-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-0" x="401.26678" - y="176.39024">false</tspan></text> + y="176.39024" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(517.41793,-144.94975)" id="g5650-2-2"> @@ -415,19 +415,19 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-544.69421" y="-354.17184" id="text5371-2-3-0-7" - sodipodi:linespacing="125%" - transform="matrix(0,-1,1,0,0,0)" + transform="rotate(-90)" inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3-9" x="-544.69421" - y="-354.17184">middlewares</tspan></text> + y="-354.17184" + style="font-size:16px;line-height:1.25;font-family:sans-serif">middlewares</tspan></text> <g transform="matrix(0,-1,1,0,-508.93096,565.23553)" id="g5650-2-0-4" @@ -461,18 +461,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="496.12921" y="255.81152" id="text5371-4-4-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6" x="496.12921" - y="255.81152">true</tspan></text> + y="255.81152" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0.70710678,0.70710678,-0.70710678,0.70710678,501.47379,-62.310424)" id="g5650-9-9" @@ -577,18 +577,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="171.92052" y="216.5154" id="text5371-4-0-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="171.92052" y="216.5154" - id="tspan17171-6">cond</tspan></text> + id="tspan17171-6" + style="font-size:16px;line-height:1.25;font-family:sans-serif">cond</tspan></text> <g transform="matrix(0,-1,-1,0,983.2611,313.28465)" id="g5650-2-0-4-3-8" @@ -633,32 +633,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="216.51535" id="text5371-2-32-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-8" x="459.47131" - y="216.51535">has if-match?</tspan></text> + y="216.51535" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has if-match?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="609.12769" y="296.02957" id="text5371-2-391-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7" x="609.12769" - y="296.02957">false</tspan></text> + y="296.02957" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(517.41793,13.785058)" id="g5650-0-6" @@ -701,32 +701,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="374.91498" id="text5371-2-32-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-1" x="459.47131" - y="374.91498">method is POST/PATCH?</tspan></text> + y="374.91498" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is POST/PATCH?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.69171" y="414.84009" id="text5371-2-8-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4" x="479.69171" - y="414.84009">true</tspan></text> + y="414.84009" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="translate(517.41793,490.80719)" id="g5650-0-6-0" @@ -862,18 +862,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="852.62952" id="text5371-2-74-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2" x="459.47131" - y="852.62952">method is POST?</tspan></text> + y="852.62952" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is POST?</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1" @@ -887,18 +887,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.97131" y="294.47879" id="text5371-43" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3" x="459.97131" - y="294.47879">412 precondition failed</tspan></text> + y="294.47879" + style="font-size:16px;line-height:1.25;font-family:sans-serif">412 precondition failed</tspan></text> <g transform="translate(2.6196148,3.2328831)" id="g5650-2-2-6"> @@ -993,18 +993,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.63538" y="453.2847" id="text5371-2-32-8-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-1-2" x="459.63538" - y="453.2847">previously_existed</tspan></text> + y="453.2847" + style="font-size:16px;line-height:1.25;font-family:sans-serif">previously_existed</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-5" @@ -1044,32 +1044,32 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="171.97131" y="614.22986" id="text5371-43-2-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-74" x="171.97131" - y="614.22986">404 not found</tspan></text> + y="614.22986" + style="font-size:16px;line-height:1.25;font-family:sans-serif">404 not found</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="296.84631" y="433.29703" id="text5371-2-8-9-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-8" x="296.84631" - y="433.29703">false</tspan></text> + y="433.29703" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(516.00372,173.10383)" id="g5650-2-2-17-8"> @@ -1129,32 +1129,32 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="500.12921" y="574.2605" id="text5371-4-4-9-3-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-8" x="500.12921" - y="574.2605">true*</tspan></text> + y="574.2605" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="607.7135" y="610.86951" id="text5371-2-391-5-5-1-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-5" x="607.7135" - y="610.86951">false</tspan></text> + y="610.86951" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-29" @@ -1168,18 +1168,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.26428" y="612.67908" id="text5371-43-2-9-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-5" x="459.26428" - y="612.67908">301 moved permanently</tspan></text> + y="612.67908" + style="font-size:16px;line-height:1.25;font-family:sans-serif">301 moved permanently</tspan></text> <g transform="translate(517.41793,332.05687)" id="g5650-2-2-65-2"> @@ -1250,46 +1250,46 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.14709" y="691.82751" id="text5371-2-74-0-7-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-9" x="459.14709" - y="691.82751">moved_temporarily</tspan></text> + y="691.82751" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_temporarily</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="500.12921" y="733.21747" id="text5371-4-4-9-3-2-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-6-6" x="500.12921" - y="733.21747">true*</tspan></text> + y="733.21747" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="607.7135" y="769.89801" id="text5371-2-391-5-5-1-0-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-2-8" x="607.7135" - y="769.89801">false</tspan></text> + y="769.89801" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-1" @@ -1303,18 +1303,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.26428" y="771.56445" id="text5371-43-2-9-7-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-9" x="459.26428" - y="771.56445">307 moved temporarily</tspan></text> + y="771.56445" + style="font-size:16px;line-height:1.25;font-family:sans-serif">307 moved temporarily</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-4-1" @@ -1328,18 +1328,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="604.32263" y="1242.303" id="text5371-43-2-9-7-3-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-7-5" x="604.32263" - y="1242.303">400 bad request</tspan></text> + y="1242.303" + style="font-size:16px;line-height:1.25;font-family:sans-serif">400 bad request</tspan></text> <g transform="matrix(-0.34202014,-0.93969262,0.93969262,-0.34202014,-311.11659,1246.6148)" id="g5650-2-0-4-0" @@ -1372,18 +1372,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="120.08566" y="891.92566" id="text5371-2-8-9-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-5" x="120.08566" - y="891.92566">true</tspan></text> + y="891.92566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0,-1,-1,0,699.22962,550.33236)" id="g5650-2-0-4-5" @@ -1428,18 +1428,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="167.39459" y="532.79895" id="text5371-2-74-0-7-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-94" x="167.39459" - y="532.79895">allow_missing_post</tspan></text> + y="532.79895" + style="font-size:16px;line-height:1.25;font-family:sans-serif">allow_missing_post</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-8-9-5" @@ -1453,32 +1453,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.2144" y="455.37643" id="text5371-2-74-0-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-6" x="175.2144" - y="455.37643">method is POST?</tspan></text> + y="455.37643" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is POST?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.35022" y="930.3703" id="text5371-2-74-0-7-1-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-94-5" x="459.35022" - y="930.3703">allow_missing_post</tspan></text> + y="930.3703" + style="font-size:16px;line-height:1.25;font-family:sans-serif">allow_missing_post</tspan></text> <g transform="translate(229.41793,490.95885)" id="g5650-0-6-9" @@ -1521,18 +1521,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="166.63885" y="852.62952" id="text5371-2-74-0-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7" x="166.63885" - y="852.62952">method is PUT?</tspan></text> + y="852.62952" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is PUT?</tspan></text> <g transform="translate(229.41793,571.07045)" id="g5650-2-2-65-9"> @@ -1602,32 +1602,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="166.24431" y="930.3703" id="text5371-2-74-0-7-15" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-2" x="166.24431" - y="930.3703">is_conflict</tspan></text> + y="930.3703" + style="font-size:16px;line-height:1.25;font-family:sans-serif">is_conflict</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="136.52316" y="971.55994" id="text5371-4-4-9-3-2-08" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-6-0" x="136.52316" - y="971.55994">true</tspan></text> + y="971.55994" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-7" @@ -1641,18 +1641,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="171.44006" y="1011.8981" id="text5371-43-2-9-7-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-0" x="171.44006" - y="1011.8981">409 conflict</tspan></text> + y="1011.8981" + style="font-size:16px;line-height:1.25;font-family:sans-serif">409 conflict</tspan></text> <g transform="translate(370.63925,803.79161)" id="g5650-93-7" @@ -1695,18 +1695,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="313.14185" y="1164.0962" id="text5371-2-74-0-7-41" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-3" x="313.14185" - y="1164.0962">content_types_accepted</tspan></text> + y="1164.0962" + style="font-size:16px;line-height:1.25;font-family:sans-serif">content_types_accepted</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-4-9" @@ -1720,18 +1720,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="313.21997" y="1242.2975" id="text5371-2-3-0-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3-1" x="313.21997" - y="1242.2975">AcceptResource</tspan></text> + y="1242.2975" + style="font-size:16px;line-height:1.25;font-family:sans-serif">AcceptCallback</tspan></text> <g transform="translate(233.45629,961.91953)" id="g5650-6-4-8-7" @@ -1804,18 +1804,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.50966" y="1323.8022" id="text5371-2-74-0-1-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4" x="175.50966" - y="1323.8022">new resource?</tspan></text> + y="1323.8022" + style="font-size:16px;line-height:1.25;font-family:sans-serif">new resource?</tspan></text> <g transform="translate(517.41793,962.60627)" id="g5650-6-4-8" @@ -1889,18 +1889,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="1323.8022" id="text5371-2-74-0-1-3-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4-8" x="459.47131" - y="1323.8022">new resource?</tspan></text> + y="1323.8022" + style="font-size:16px;line-height:1.25;font-family:sans-serif">new resource?</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7" @@ -1914,18 +1914,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.776" y="1403.5779" id="text5371-43-3-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9" x="459.776" - y="1403.5779">201 created</tspan></text> + y="1403.5779" + style="font-size:16px;line-height:1.25;font-family:sans-serif">201 created</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7-4" @@ -1939,18 +1939,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.03381" y="1483.2128" id="text5371-43-3-2-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9-2" x="459.03381" - y="1483.2128">303 see other</tspan></text> + y="1483.2128" + style="font-size:16px;line-height:1.25;font-family:sans-serif">303 see other</tspan></text> <g transform="matrix(0,1,1,0,-67.245042,1455.155)" id="g5650-2-2-6-6-7-9-1"> @@ -2019,18 +2019,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.50966" y="1401.7865" id="text5371-2-74-0-1-3-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4-9" x="175.50966" - y="1401.7865">has resp location?</tspan></text> + y="1401.7865" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has resp location?</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7-4-7" @@ -2110,18 +2110,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.50966" y="1561.2965" id="text5371-2-74-0-1-3-7-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4-9-5" x="175.50966" - y="1561.2965">has resp body?</tspan></text> + y="1561.2965" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has resp body?</tspan></text> <g transform="translate(517.41793,1201.395)" id="g5650-6-4" @@ -2195,32 +2195,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.30334" y="1561.0739" id="text5371-2-9-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-8-6" x="459.30334" - y="1561.0739">multiple_choices</tspan></text> + y="1561.0739" + style="font-size:16px;line-height:1.25;font-family:sans-serif">multiple_choices</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.75421" y="1602.6646" id="text5371-2-8-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7" x="479.75421" - y="1602.6646">false</tspan></text> + y="1602.6646" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-1-0" @@ -2234,18 +2234,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.42053" y="1720.566" id="text5371-43-5-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-62-9" x="459.42053" - y="1720.566">300 multiple choices</tspan></text> + y="1720.566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">300 multiple choices</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-3" @@ -2259,46 +2259,46 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="458.88538" y="1642.3412" id="text5371-43-3-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-3" x="458.88538" - y="1642.3412">200 OK</tspan></text> + y="1642.3412" + style="font-size:16px;line-height:1.25;font-family:sans-serif">200 OK</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="171.24475" y="1642.3412" id="text5371-43-3-2-6-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9-2-0" x="171.24475" - y="1642.3412">204 no content</tspan></text> + y="1642.3412" + style="font-size:16px;line-height:1.25;font-family:sans-serif">204 no content</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.69171" y="891.92566" id="text5371-2-8-9-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-1" x="479.69171" - y="891.92566">true</tspan></text> + y="891.92566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g id="g5650-4-8" transform="matrix(0.5,0.8660254,-0.8660254,0.5,204.7918,279.30499)"> @@ -2327,18 +2327,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="496.12921" y="494.3544" id="text5371-4-4-9-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8" x="496.12921" - y="494.3544">true</tspan></text> + y="494.3544" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-8-9-1-3-4-8" @@ -2352,18 +2352,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.14709" y="532.79895" id="text5371-2-74-0-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-9" x="459.14709" - y="532.79895">moved_permanently</tspan></text> + y="532.79895" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_permanently</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7-9" @@ -2377,102 +2377,102 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.67053" y="1010.2067" id="text5371-43-3-2-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9-5" x="459.67053" - y="1010.2067">410 gone</tspan></text> + y="1010.2067" + style="font-size:16px;line-height:1.25;font-family:sans-serif">410 gone</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="260.04547" y="494.97446" id="text5371-4-4-9-1-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-2" x="260.04547" - y="494.97446">false</tspan></text> + y="494.97446" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="120.08566" y="494.51349" id="text5371-2-8-9-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-55" x="120.08566" - y="494.51349">true</tspan></text> + y="494.51349" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="133.92941" y="574.40112" id="text5371-4-4-9-1-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0" x="133.92941" - y="574.40112">false</tspan></text> + y="574.40112" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="315.87756" y="828.86047" id="text5371-4-4-9-1-1-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1" x="315.87756" - y="828.86047">false</tspan></text> + y="828.86047" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="498.78546" y="972.02087" id="text5371-4-4-9-1-1-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-2" x="498.78546" - y="972.02087">false</tspan></text> + y="972.02087" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="458.9295" y="1217.7582" id="text5371-4-4-9-1-1-9-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2" x="458.9295" - y="1217.7582">false</tspan></text> + y="1217.7582" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="matrix(0,1,1,0,77.85132,1295.6715)" id="g5650-2-2-6-6-7"> @@ -2501,18 +2501,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="207.75119" y="1283.5576" id="text5371-2-391-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-4" x="207.75119" - y="1283.5576">true</tspan></text> + y="1283.5576" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0.70710678,0.70710678,-0.70710678,0.70710678,501.47379,1045.323)" id="g5650-9-9-1" @@ -2544,18 +2544,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:end;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:end;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:end;letter-spacing:0px;word-spacing:0px;text-anchor:end;fill:#6d8e41;fill-opacity:1;stroke:none" x="419.81369" y="1283.0615" id="text5371-2-391-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="419.81369" y="1283.0615" - id="tspan5794">true, URI*</tspan></text> + id="tspan5794" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true, URI*</tspan></text> <g transform="matrix(-0.70710678,0.70710678,0.70710678,0.70710678,124.04665,1045.323)" id="g5650-9-9-4" @@ -2587,158 +2587,158 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.69171" y="1363.2994" id="text5371-2-8-4-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5" x="479.69171" - y="1363.2994">true</tspan></text> + y="1363.2994" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="626.74475" y="1403.5779" id="text5371-4-4-9-1-1-9-1-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-0" x="626.74475" - y="1403.5779">false</tspan></text> + y="1403.5779" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="624.0885" y="1642.0209" id="text5371-4-4-9-1-1-9-1-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-3" x="624.0885" - y="1642.0209">true</tspan></text> + y="1642.0209" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="317.91525" y="1538.8624" id="text5371-4-4-9-1-1-9-1-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-1" x="317.91525" - y="1538.8624">true</tspan></text> + y="1538.8624" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="190.83659" y="1602.2036" id="text5371-2-8-4-3-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5-9" x="190.83659" - y="1602.2036">false</tspan></text> + y="1602.2036" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="190.83659" y="1363.1792" id="text5371-2-8-4-3-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5-0" x="190.83659" - y="1363.1792">true</tspan></text> + y="1363.1792" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="7.9966321" y="1443.395" id="text5371-4-4-9-1-1-9-1-4-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-0-6" x="7.9966321" - y="1443.395">false</tspan></text> + y="1443.395" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="317.86548" y="1379.0562" id="text5371-4-4-9-1-1-9-1-2-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-1-5" x="317.86548" - y="1379.0562">true</tspan></text> + y="1379.0562" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="190.83659" y="1482.6313" id="text5371-2-8-4-3-8-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5-0-8" x="190.83659" - y="1482.6313">false</tspan></text> + y="1482.6313" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="85.095001" y="891.92566" id="text5371-4-4-9-1-4-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-2-9" x="85.095001" - y="891.92566">false</tspan></text> + y="891.92566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="232.21094" y="971.55994" id="text5371-2-391-5-5-1-0-7-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-2-8-8" x="232.21094" - y="971.55994">false</tspan></text> + y="971.55994" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="matrix(0,-1,1,0,-359.02432,626.75367)" id="g5650-2-0-4-3-8-9-4" @@ -2781,18 +2781,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="536.26642" y="972.02087" id="text5371-2-8-9-1-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-1-4" x="536.26642" - y="972.02087">true</tspan></text> + y="972.02087" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0,-1,-1,0,347.71062,566.6496)" id="g5650-2-0-4-3-8-9-2-8" @@ -2826,31 +2826,31 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="322.92551" y="375.54388" id="text5371-4-6-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-0-8" x="322.92551" - y="375.54388">false</tspan></text> + y="375.54388" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="66.001251" y="574.40112" id="text5371-2-8-9-0-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-55-3" x="66.001251" - y="574.40112">true</tspan></text> + y="574.40112" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> </g> </svg> diff --git a/docs/en/cowboy/2.0/guide/routing/index.html b/docs/en/cowboy/2.0/guide/routing/index.html index f67532cd..24f5ca46 100644 --- a/docs/en/cowboy/2.0/guide/routing/index.html +++ b/docs/en/cowboy/2.0/guide/routing/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Routing</title> @@ -67,267 +67,270 @@ <h1 class="lined-header"><span>Routing</span></h1> -<div class="paragraph"><p>Cowboy does nothing by default.</p></div>
-<div class="paragraph"><p>To make Cowboy useful, you need to map URIs to Erlang modules that will
-handle the requests. This is called routing.</p></div>
-<div class="paragraph"><p>When Cowboy receives a request, it tries to match the requested host and
-path to the configured routes. When there’s a match, the route’s
-associated handler is executed.</p></div>
-<div class="paragraph"><p>Routes need to be compiled before they can be used by Cowboy.
-The result of the compilation is the dispatch rules.</p></div>
-<div class="sect1">
-<h2 id="_syntax">Syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The general structure for the routes is defined as follow.</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="color: #009900">Routes</span> <span style="color: #990000">=</span> [<span style="color: #009900">Host1</span>, <span style="color: #009900">Host2</span>, <span style="color: #990000">...</span> <span style="color: #009900">HostN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Each host contains matching rules for the host along with optional
-constraints, and a list of routes for the path component.</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="color: #009900">Host1</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span>
-<span style="color: #009900">Host2</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The list of routes for the path component is defined similar to the
-list of hosts.</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="color: #009900">PathsList</span> <span style="color: #990000">=</span> [<span style="color: #009900">Path1</span>, <span style="color: #009900">Path2</span>, <span style="color: #990000">...</span> <span style="color: #009900">PathN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, each path contains matching rules for the path along with
-optional constraints, and gives us the handler module to be used
-along with its initial state.</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="color: #009900">Path1</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span>
-<span style="color: #009900">Path2</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Continue reading to learn more about the match syntax and the optional
-constraints.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_match_syntax">Match syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The match syntax is used to associate host names and paths with their
-respective handlers.</p></div>
-<div class="paragraph"><p>The match syntax is the same for host and path with a few subtleties.
-Indeed, the segments separator is different, and the host is matched
-starting from the last segment going to the first. All examples will
-feature both host and path match rules and explain the differences
-when encountered.</p></div>
-<div class="paragraph"><p>Excluding special values that we will explain at the end of this section,
-the simplest match value is a host or a path. It can be given as either
-a <code>string()</code> or a <code>binary()</code>.</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="color: #009900">PathMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/"</span><span style="color: #990000">.</span>
-<span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
-
-<span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As you can see, all paths defined this way must start with a slash
-character. Note that these two paths are identical as far as routing
-is concerned.</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="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
-<span style="color: #009900">PathMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource/"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Hosts with and without a trailing dot are equivalent for routing.
-Similarly, hosts with and without a leading dot are also equivalent.</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="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org."</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">".cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It is possible to extract segments of the host and path and to store
-the values in the <code>Req</code> object for later use. We call these kind of
-values bindings.</p></div>
-<div class="paragraph"><p>The syntax for bindings is very simple. A segment that begins with
-the <code>:</code> character means that what follows until the end of the segment
-is the name of the binding in which the segment value will be stored.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/prices"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":subdomain.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If these two end up matching when routing, you will end up with two
-bindings defined, <code>subdomain</code> and <code>name</code>, each containing the
-segment value where they were defined. For example, the URL
-<code>http://test.example.org/hats/wild_cowboy_legendary/prices</code> will
-result in having the value <code>test</code> bound to the name <code>subdomain</code>
-and the value <code>wild_cowboy_legendary</code> bound to the name <code>name</code>.
-They can later be retrieved using <code>cowboy_req:binding/{2,3}</code>. The
-binding name must be given as an atom.</p></div>
-<div class="paragraph"><p>There is a special binding name you can use to mimic the underscore
-variable in Erlang. Any match against the <code>_</code> binding will succeed
-but the data will be discarded. This is especially useful for
-matching against many domain names in one go.</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="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"ninenines.:_"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Similarly, it is possible to have optional segments. Anything
-between brackets is optional.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/:number]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[www.]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also have imbricated optional segments.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/[:number]]"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can retrieve the rest of the host or path using <code>[...]</code>.
-In the case of hosts it will match anything before, in the case
-of paths anything after the previously matched segments. It is
-a special case of optional segments, in that it can have
-zero, one or many segments. You can then find the segments using
-<code>cowboy_req:host_info/1</code> and <code>cowboy_req:path_info/1</code> respectively.
-They will be represented as a list of segments.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[...]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[...]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If a binding appears twice in the routing rules, then the match
-will succeed only if they share the same value. This copies the
-Erlang pattern matching behavior.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/:name"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This is also true when an optional segment is present. In this
-case the two values must be identical only if the segment is
-available.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/[:name]"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If a binding is defined in both the host and path, then they must
-also share the same value.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/:user/[...]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":user.github.com"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, there are two special match values that can be used. The
-first is the atom <code>'_'</code> which will match any host or path.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The second is the special host match <code>"*"</code> which will match the
-wildcard path, generally used alongside the <code>OPTIONS</code> method.</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="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_constraints">Constraints</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>After the matching has completed, the resulting bindings can be tested
-against a set of constraints. Constraints are only tested when the
-binding is defined. They run in the order you defined them. The match
-will succeed only if they all succeed. If the match fails, then Cowboy
-tries the next route in the list.</p></div>
-<div class="paragraph"><p>The format used for constraints is the same as match functions in
-<code>cowboy_req</code>: they are provided as a list of fields which may have
-one or more constraints. While the router accepts the same format,
-it will skip fields with no constraints and will also ignore default
-values, if any.</p></div>
-<div class="paragraph"><p>Read more about <a href="../constraints">constraints</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_compilation">Compilation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The routes must be compiled before Cowboy can use them. The compilation
-step normalizes the routes to simplify the code and speed up the
-execution, but the routes are still looked up one by one in the end.
-Faster compilation strategies could be to compile the routes directly
-to Erlang code, but would require heavier dependencies.</p></div>
-<div class="paragraph"><p>To compile routes, just call the appropriate function:</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="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- <span style="font-style: italic"><span style="color: #9A1900">%% {HostMatch, list({PathMatch, Handler, InitialState})}</span></span>
- {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF6600">'_'</span>, <span style="color: #FF6600">my_handler</span>, #{}}]}
-]),
-<span style="font-style: italic"><span style="color: #9A1900">%% Name, NbAcceptors, TransOpts, ProtoOpts</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>,
- [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
- #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}}
-)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_live_update">Live update</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can use the <code>cowboy:set_env/3</code> function for updating the dispatch
-list used by routing. This will apply to all new connections accepted
-by the listener:</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="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>(<span style="color: #009900">Routes</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that you need to compile the routes again before updating.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy does nothing by default.</p></div> +<div class="paragraph"><p>To make Cowboy useful, you need to map URIs to Erlang modules that will +handle the requests. This is called routing.</p></div> +<div class="paragraph"><p>When Cowboy receives a request, it tries to match the requested host and +path to the configured routes. When there’s a match, the route’s +associated handler is executed.</p></div> +<div class="paragraph"><p>Routes need to be compiled before they can be used by Cowboy. +The result of the compilation is the dispatch rules.</p></div> +<div class="sect1"> +<h2 id="_syntax">Syntax</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The general structure for the routes is defined as follow.</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="color: #009900">Routes</span> <span style="color: #990000">=</span> [<span style="color: #009900">Host1</span>, <span style="color: #009900">Host2</span>, <span style="color: #990000">...</span> <span style="color: #009900">HostN</span>]<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Each host contains matching rules for the host along with optional +constraints, and a list of routes for the path component.</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="color: #009900">Host1</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span> +<span style="color: #009900">Host2</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The list of routes for the path component is defined similar to the +list of hosts.</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="color: #009900">PathsList</span> <span style="color: #990000">=</span> [<span style="color: #009900">Path1</span>, <span style="color: #009900">Path2</span>, <span style="color: #990000">...</span> <span style="color: #009900">PathN</span>]<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Finally, each path contains matching rules for the path along with +optional constraints, and gives us the handler module to be used +along with its initial state.</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="color: #009900">Path1</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span> +<span style="color: #009900">Path2</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Continue reading to learn more about the match syntax and the optional +constraints.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_match_syntax">Match syntax</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The match syntax is used to associate host names and paths with their +respective handlers.</p></div> +<div class="paragraph"><p>The match syntax is the same for host and path with a few subtleties. +Indeed, the segments separator is different, and the host is matched +starting from the last segment going to the first. All examples will +feature both host and path match rules and explain the differences +when encountered.</p></div> +<div class="paragraph"><p>Excluding special values that we will explain at the end of this section, +the simplest match value is a host or a path. It can be given as either +a <code>string()</code> or a <code>binary()</code>.</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="color: #009900">PathMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/"</span><span style="color: #990000">.</span> +<span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span> + +<span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>As you can see, all paths defined this way must start with a slash +character. Note that these two paths are identical as far as routing +is concerned.</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="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span> +<span style="color: #009900">PathMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource/"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Hosts with and without a trailing dot are equivalent for routing. +Similarly, hosts with and without a leading dot are also equivalent.</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="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org."</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">".cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It is possible to extract segments of the host and path and to store +the values in the <code>Req</code> object for later use. We call these kind of +values bindings.</p></div> +<div class="paragraph"><p>The syntax for bindings is very simple. A segment that begins with +the <code>:</code> character means that what follows until the end of the segment +is the name of the binding in which the segment value will be stored.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/prices"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":subdomain.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If these two end up matching when routing, you will end up with two +bindings defined, <code>subdomain</code> and <code>name</code>, each containing the +segment value where they were defined. For example, the URL +<code>http://test.example.org/hats/wild_cowboy_legendary/prices</code> will +result in having the value <code>test</code> bound to the name <code>subdomain</code> +and the value <code>wild_cowboy_legendary</code> bound to the name <code>name</code>. +They can later be retrieved using <code>cowboy_req:binding/{2,3}</code>. The +binding name must be given as an atom.</p></div> +<div class="paragraph"><p>There is a special binding name you can use to mimic the underscore +variable in Erlang. Any match against the <code>_</code> binding will succeed +but the data will be discarded. This is especially useful for +matching against many domain names in one go.</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="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"ninenines.:_"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Similarly, it is possible to have optional segments. Anything +between brackets is optional.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/:number]"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[www.]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can also have imbricated optional segments.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/[:number]]"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can retrieve the rest of the host or path using <code>[...]</code>. +In the case of hosts it will match anything before, in the case +of paths anything after the previously matched segments. It is +a special case of optional segments, in that it can have +zero, one or many segments. You can then find the segments using +<code>cowboy_req:host_info/1</code> and <code>cowboy_req:path_info/1</code> respectively. +They will be represented as a list of segments.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[...]"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[...]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If a binding appears twice in the routing rules, then the match +will succeed only if they share the same value. This copies the +Erlang pattern matching behavior.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/:name"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This is also true when an optional segment is present. In this +case the two values must be identical only if the segment is +available.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/[:name]"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If a binding is defined in both the host and path, then they must +also share the same value.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/:user/[...]"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":user.github.com"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Finally, there are two special match values that can be used. The +first is the atom <code>'_'</code> which will match any host or path.</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="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The second is the special host match <code>"*"</code> which will match the +wildcard path, generally used alongside the <code>OPTIONS</code> method.</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="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_constraints">Constraints</h2> +<div class="sectionbody"> +<div class="paragraph"><p>After the matching has completed, the resulting bindings can be tested +against a set of constraints. Constraints are only tested when the +binding is defined. They run in the order you defined them. The match +will succeed only if they all succeed. If the match fails, then Cowboy +tries the next route in the list.</p></div> +<div class="paragraph"><p>The format used for constraints is the same as match functions in +<code>cowboy_req</code>: they are provided as a list of fields which may have +one or more constraints. While the router accepts the same format, +it will skip fields with no constraints and will also ignore default +values, if any.</p></div> +<div class="paragraph"><p>Read more about <a href="../constraints">constraints</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_compilation">Compilation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The routes must be compiled before Cowboy can use them. The compilation +step normalizes the routes to simplify the code and speed up the +execution, but the routes are still looked up one by one in the end. +Faster compilation strategies could be to compile the routes directly +to Erlang code, but would require heavier dependencies.</p></div> +<div class="paragraph"><p>To compile routes, just call the appropriate function:</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="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + <span style="font-style: italic"><span style="color: #9A1900">%% {HostMatch, list({PathMatch, Handler, InitialState})}</span></span> + {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF6600">'_'</span>, <span style="color: #FF6600">my_handler</span>, #{}}]} +]), +<span style="font-style: italic"><span style="color: #9A1900">%% Name, NbAcceptors, TransOpts, ProtoOpts</span></span> +<span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>, + [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], + #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}} +)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_live_update">Live update</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can use the <code>cowboy:set_env/3</code> function for updating the dispatch +list used by routing. This will apply to all new connections accepted +by the listener:</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="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>(<span style="color: #009900">Routes</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that you need to compile the routes again before updating.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/specs.asciidoc b/docs/en/cowboy/2.0/guide/specs.asciidoc index db4abe45..ec101fbd 100644 --- a/docs/en/cowboy/2.0/guide/specs.asciidoc +++ b/docs/en/cowboy/2.0/guide/specs.asciidoc @@ -44,7 +44,6 @@ for or related to HTTP. * https://tools.ietf.org/html/rfc5789[RFC 5789]: PATCH Method for HTTP * https://tools.ietf.org/html/rfc5843[RFC 5843]: Additional Hash Algorithms for HTTP Instance Digests * https://tools.ietf.org/html/rfc5861[RFC 5861]: HTTP Cache-Control Extensions for Stale Content -* https://tools.ietf.org/html/rfc5987[RFC 5987]: Character Set and Language Encoding for HTTP Header Field Parameters * https://tools.ietf.org/html/rfc5988[RFC 5988]: Web Linking * https://tools.ietf.org/html/rfc6265[RFC 6265]: HTTP State Management Mechanism * https://tools.ietf.org/html/rfc6266[RFC 6266]: Use of the Content-Disposition Header Field @@ -83,7 +82,9 @@ for or related to HTTP. * https://tools.ietf.org/html/rfc7936[RFC 7936]: Clarifying Registry Procedures for the WebSocket Subprotocol Name Registry * https://tools.ietf.org/html/rfc8053[RFC 8053]: HTTP Authentication Extensions for Interactive Clients * https://tools.ietf.org/html/rfc8164[RFC 8164]: Opportunistic Security for HTTP/2 +* https://tools.ietf.org/html/rfc8187[RFC 8187]: Indicating Character Encoding and Language for HTTP Header Field Parameters * https://tools.ietf.org/html/rfc8188[RFC 8188]: Encrypted Content-Encoding for HTTP +* https://tools.ietf.org/html/rfc8246[RFC 8246]: HTTP Immutable Responses * https://www.w3.org/TR/webmention/[Webmention]: Webmention ==== Upcoming diff --git a/docs/en/cowboy/2.0/guide/specs/index.html b/docs/en/cowboy/2.0/guide/specs/index.html index be0d89be..b0511164 100644 --- a/docs/en/cowboy/2.0/guide/specs/index.html +++ b/docs/en/cowboy/2.0/guide/specs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: HTTP and other specifications</title> @@ -67,840 +67,848 @@ <h1 class="lined-header"><span>HTTP and other specifications</span></h1> -<div class="paragraph"><p>This chapter intends to list all the specification documents
-for or related to HTTP.</p></div>
-<div class="sect1">
-<h2 id="_http">HTTP</h2>
-<div class="sectionbody">
-<div class="sect3">
-<h4 id="_iana_registries">IANA Registries</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-methods/http-methods.xhtml">HTTP Method Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">HTTP Status Code Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/message-headers/message-headers.xhtml">Message Headers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-parameters/http-parameters.xhtml">HTTP Parameters</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-alt-svc-parameters/http-alt-svc-parameters.xhtml">HTTP Alt-Svc Parameter Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml">HTTP Authentication Scheme Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml">HTTP Cache Directive Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml">HTTP Digest Algorithm Values</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/hoba-device-identifiers/hoba-device-identifiers.xhtml">HTTP Origin-Bound Authentication Device Identifier Types</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-upgrade-tokens/http-upgrade-tokens.xhtml">HTTP Upgrade Token Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-warn-codes/http-warn-codes.xhtml">HTTP Warn Codes</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml">HTTP/2 Parameters</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.ietf.org/assignments/websocket/websocket.xml">WebSocket Protocol Registries</a>
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_current">Current</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="http://www.w3.org/TR/cors/">CORS</a>: Cross-Origin Resource Sharing
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/CSP2/">CSP2</a>: Content Security Policy Level 2
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/tracking-dnt/">DNT</a>: Tracking Preference Expression (DNT)
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/eventsource/">eventsource</a>: Server-Sent Events
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/html4/interact/forms.html#h-17.13.4">Form content types</a>: Form content types
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/preload/">Preload</a>: Preload
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">REST</a>: Fielding’s Dissertation
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc1945">RFC 1945</a>: HTTP/1.0
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc1951">RFC 1951</a>: DEFLATE Compressed Data Format Specification version 1.3
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc1952">RFC 1952</a>: GZIP file format specification version 4.3
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2046#section-5.1">RFC 2046</a>: Multipart media type (in MIME Part Two: Media Types)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2295">RFC 2295</a>: Transparent Content Negotiation in HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2296">RFC 2296</a>: HTTP Remote Variant Selection Algorithm: RVSA/1.0
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2817">RFC 2817</a>: Upgrading to TLS Within HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2818">RFC 2818</a>: HTTP Over TLS
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3230">RFC 3230</a>: Instance Digests in HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4559">RFC 4559</a>: SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5789">RFC 5789</a>: PATCH Method for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5843">RFC 5843</a>: Additional Hash Algorithms for HTTP Instance Digests
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5861">RFC 5861</a>: HTTP Cache-Control Extensions for Stale Content
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5987">RFC 5987</a>: Character Set and Language Encoding for HTTP Header Field Parameters
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5988">RFC 5988</a>: Web Linking
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6265">RFC 6265</a>: HTTP State Management Mechanism
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6266">RFC 6266</a>: Use of the Content-Disposition Header Field
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6454">RFC 6454</a>: The Web Origin Concept
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6455">RFC 6455</a>: The WebSocket Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6585">RFC 6585</a>: Additional HTTP Status Codes
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6750">RFC 6750</a>: The OAuth 2.0 Authorization Framework: Bearer Token Usage
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6797">RFC 6797</a>: HTTP Strict Transport Security (HSTS)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6903">RFC 6903</a>: Additional Link Relation Types
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7034">RFC 7034</a>: HTTP Header Field X-Frame-Options
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7089">RFC 7089</a>: Time-Based Access to Resource States: Memento
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7230">RFC 7230</a>: HTTP/1.1 Message Syntax and Routing
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7231">RFC 7231</a>: HTTP/1.1 Semantics and Content
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a>: HTTP/1.1 Conditional Requests
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7233">RFC 7233</a>: HTTP/1.1 Range Requests
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7234">RFC 7234</a>: HTTP/1.1 Caching
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7235">RFC 7235</a>: HTTP/1.1 Authentication
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>: Forwarded HTTP Extension
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7240">RFC 7240</a>: Prefer Header for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7469">RFC 7469</a>: Public Key Pinning Extension for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7486">RFC 7486</a>: HTTP Origin-Bound Authentication (HOBA)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7538">RFC 7538</a>: HTTP Status Code 308 (Permanent Redirect)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7540">RFC 7540</a>: Hypertext Transfer Protocol Version 2 (HTTP/2)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7541">RFC 7541</a>: HPACK: Header Compression for HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7578">RFC 7578</a>: Returning Values from Forms: multipart/form-data
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7615">RFC 7615</a>: HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7616">RFC 7616</a>: HTTP Digest Access Authentication
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7617">RFC 7617</a>: The <em>Basic</em> HTTP Authentication Scheme
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7639">RFC 7639</a>: The ALPN HTTP Header Field
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7692">RFC 7692</a>: Compression Extensions for WebSocket
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7694">RFC 7694</a>: HTTP Client-Initiated Content-Encoding
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7725">RFC 7725</a>: An HTTP Status Code to Report Legal Obstacles
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7804">RFC 7804</a>: Salted Challenge Response HTTP Authentication Mechanism
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7838">RFC 7838</a>: HTTP Alternative Services
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7932">RFC 7932</a>: Brotli Compressed Data Format
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7936">RFC 7936</a>: Clarifying Registry Procedures for the WebSocket Subprotocol Name Registry
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8053">RFC 8053</a>: HTTP Authentication Extensions for Interactive Clients
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8164">RFC 8164</a>: Opportunistic Security for HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8188">RFC 8188</a>: Encrypted Content-Encoding for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/webmention/">Webmention</a>: Webmention
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_upcoming">Upcoming</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://www.w3.org/TR/csp-cookies/">Content Security Policy: Cookie Controls</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/csp-embedded-enforcement/">Content Security Policy: Embedded Enforcement</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/CSP3/">Content Security Policy Level 3</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/csp-pinning/">Content Security Policy Pinning</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/referrer-policy/">Referrer Policy</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/UISecurity/">User Interface Security Directives for Content Security Policy</a>
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_informative">Informative</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="http://www.w3.org/TR/webarch/">Architecture of the World Wide Web</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2936">RFC 2936</a>: HTTP MIME Type Handler Detection
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2964">RFC 2964</a>: Use of HTTP State Management
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3143">RFC 3143</a>: Known HTTP Proxy/Caching Problems
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6202">RFC 6202</a>: Known Issues and Best Practices for the Use of Long Polling and Streaming in Bidirectional HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6838">RFC 6838</a>: Media Type Specifications and Registration Procedures
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7478">RFC 7478</a>: Web Real-Time Communication Use Cases and Requirements
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_related">Related</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="http://www.w3.org/TR/app-uri/">app: URL Scheme</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/beacon/">Beacon</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/FileAPI/">File API</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8030">Generic Event Delivery Using HTTP Push</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/capability-urls/">Good Practices for Capability URLs</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://html.spec.whatwg.org/multipage/">HTML Living Standard</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://developers.whatwg.org/">HTML Living Standard for Web developers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/html401/">HTML4.01</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/html5/">HTML5</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/html51/">HTML5.1</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/html52/">HTML5.2</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/media-frags/">Media Fragments URI 1.0</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6690">RFC 6690</a>: Constrained RESTful Environments (CoRE) Link Format
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7807">RFC 7807</a>: Problem Details for HTTP APIs
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6906">RFC 6906</a>: The <em>profile</em> Link Relation Type
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/SRI/">Subresource Integrity</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/tracking-compliance/">Tracking Compliance and Scope</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/media-frags-reqs/">Use cases and requirements for Media Fragments</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/webrtc/">WebRTC 1.0: Real-time Communication Between Browsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/websockets/">Websocket API</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/XMLHttpRequest/">XMLHttpRequest Level 1</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://xhr.spec.whatwg.org/">XMLHttpRequest Living Standard</a>
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_seemingly_obsolete">Seemingly obsolete</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2227">RFC 2227</a>: Simple Hit-Metering and Usage-Limiting for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2310">RFC 2310</a>: The Safe Response Header Field
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2324">RFC 2324</a>: Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2660">RFC 2660</a>: The Secure HyperText Transfer Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2774">RFC 2774</a>: An HTTP Extension Framework
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2965">RFC 2965</a>: HTTP State Management Mechanism (Cookie2)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3229">RFC 3229</a>: Delta encoding in HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7168">RFC 7168</a>: The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA)
-</p>
-</li>
-<li>
-<p>
-<a href="http://dev.chromium.org/spdy/spdy-protocol">SPDY</a>: SPDY Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/draft-tyoshino-hybi-websocket-perframe-deflate-06">x-webkit-deflate-frame</a>: Deprecated Websocket compression
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_url">URL</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>: URI Generic Syntax
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>: URI Template
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6874">RFC 6874</a>: Representing IPv6 Zone Identifiers in Address Literals and URIs
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7320">RFC 7320</a>: URI Design and Ownership
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/url-1/">URL</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://url.spec.whatwg.org/">URL Living Standard</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_webdav">WebDAV</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3253">RFC 3253</a>: Versioning Extensions to WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3648">RFC 3648</a>: WebDAV Ordered Collections Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3744">RFC 3744</a>: WebDAV Access Control Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4316">RFC 4316</a>: Datatypes for WebDAV Properties
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4331">RFC 4331</a>: Quota and Size Properties for DAV Collections
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4437">RFC 4437</a>: WebDAV Redirect Reference Resources
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4709">RFC 4709</a>: Mounting WebDAV Servers
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4791">RFC 4791</a>: Calendaring Extensions to WebDAV (CalDAV)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4918">RFC 4918</a>: HTTP Extensions for WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5323">RFC 5323</a>: WebDAV SEARCH
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5397">RFC 5397</a>: WebDAV Current Principal Extension
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5689">RFC 5689</a>: Extended MKCOL for WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5842">RFC 5842</a>: Binding Extensions to WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5995">RFC 5995</a>: Using POST to Add Members to WebDAV Collections
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6352">RFC 6352</a>: CardDAV: vCard Extensions to WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6578">RFC 6578</a>: Collection Synchronization for WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6638">RFC 6638</a>: Scheduling Extensions to CalDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6764">RFC 6764</a>: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7809">RFC 7809</a>: Calendaring Extensions to WebDAV (CalDAV): Time Zones by Reference
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7953">RFC 7953</a>: Calendar Availability
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8144">RFC 8144</a>: Use of the Prefer Header Field in WebDAV
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_coap">CoAP</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7252">RFC 7252</a>: The Constrained Application Protocol (CoAP)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7390">RFC 7390</a>: Group Communication for CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7641">RFC 7641</a>: Observing Resources in CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7650">RFC 7650</a>: A CoAP Usage for REsource LOcation And Discovery (RELOAD)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7959">RFC 7959</a>: Block-Wise Transfers in CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7967">RFC 7967</a>: CoAP Option for No Server Response
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8075">RFC 8075</a>: Guidelines for Mapping Implementations: HTTP to CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8132">RFC 8132</a>: PATCH and FETCH Methods for CoAP
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter intends to list all the specification documents +for or related to HTTP.</p></div> +<div class="sect1"> +<h2 id="_http">HTTP</h2> +<div class="sectionbody"> +<div class="sect3"> +<h4 id="_iana_registries">IANA Registries</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="https://www.iana.org/assignments/http-methods/http-methods.xhtml">HTTP Method Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">HTTP Status Code Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/message-headers/message-headers.xhtml">Message Headers</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-parameters/http-parameters.xhtml">HTTP Parameters</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-alt-svc-parameters/http-alt-svc-parameters.xhtml">HTTP Alt-Svc Parameter Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml">HTTP Authentication Scheme Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml">HTTP Cache Directive Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml">HTTP Digest Algorithm Values</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/hoba-device-identifiers/hoba-device-identifiers.xhtml">HTTP Origin-Bound Authentication Device Identifier Types</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-upgrade-tokens/http-upgrade-tokens.xhtml">HTTP Upgrade Token Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-warn-codes/http-warn-codes.xhtml">HTTP Warn Codes</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml">HTTP/2 Parameters</a> +</p> +</li> +<li> +<p> +<a href="https://www.ietf.org/assignments/websocket/websocket.xml">WebSocket Protocol Registries</a> +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_current">Current</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="http://www.w3.org/TR/cors/">CORS</a>: Cross-Origin Resource Sharing +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/CSP2/">CSP2</a>: Content Security Policy Level 2 +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/tracking-dnt/">DNT</a>: Tracking Preference Expression (DNT) +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/eventsource/">eventsource</a>: Server-Sent Events +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/html4/interact/forms.html#h-17.13.4">Form content types</a>: Form content types +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/preload/">Preload</a>: Preload +</p> +</li> +<li> +<p> +<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">REST</a>: Fielding’s Dissertation +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc1945">RFC 1945</a>: HTTP/1.0 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc1951">RFC 1951</a>: DEFLATE Compressed Data Format Specification version 1.3 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc1952">RFC 1952</a>: GZIP file format specification version 4.3 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2046#section-5.1">RFC 2046</a>: Multipart media type (in MIME Part Two: Media Types) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2295">RFC 2295</a>: Transparent Content Negotiation in HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2296">RFC 2296</a>: HTTP Remote Variant Selection Algorithm: RVSA/1.0 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2817">RFC 2817</a>: Upgrading to TLS Within HTTP/1.1 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2818">RFC 2818</a>: HTTP Over TLS +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3230">RFC 3230</a>: Instance Digests in HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4559">RFC 4559</a>: SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5789">RFC 5789</a>: PATCH Method for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5843">RFC 5843</a>: Additional Hash Algorithms for HTTP Instance Digests +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5861">RFC 5861</a>: HTTP Cache-Control Extensions for Stale Content +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5988">RFC 5988</a>: Web Linking +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6265">RFC 6265</a>: HTTP State Management Mechanism +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6266">RFC 6266</a>: Use of the Content-Disposition Header Field +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6454">RFC 6454</a>: The Web Origin Concept +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6455">RFC 6455</a>: The WebSocket Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6585">RFC 6585</a>: Additional HTTP Status Codes +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6750">RFC 6750</a>: The OAuth 2.0 Authorization Framework: Bearer Token Usage +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6797">RFC 6797</a>: HTTP Strict Transport Security (HSTS) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6903">RFC 6903</a>: Additional Link Relation Types +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7034">RFC 7034</a>: HTTP Header Field X-Frame-Options +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7089">RFC 7089</a>: Time-Based Access to Resource States: Memento +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7230">RFC 7230</a>: HTTP/1.1 Message Syntax and Routing +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7231">RFC 7231</a>: HTTP/1.1 Semantics and Content +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a>: HTTP/1.1 Conditional Requests +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7233">RFC 7233</a>: HTTP/1.1 Range Requests +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7234">RFC 7234</a>: HTTP/1.1 Caching +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7235">RFC 7235</a>: HTTP/1.1 Authentication +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>: Forwarded HTTP Extension +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7240">RFC 7240</a>: Prefer Header for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7469">RFC 7469</a>: Public Key Pinning Extension for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7486">RFC 7486</a>: HTTP Origin-Bound Authentication (HOBA) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7538">RFC 7538</a>: HTTP Status Code 308 (Permanent Redirect) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7540">RFC 7540</a>: Hypertext Transfer Protocol Version 2 (HTTP/2) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7541">RFC 7541</a>: HPACK: Header Compression for HTTP/2 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7578">RFC 7578</a>: Returning Values from Forms: multipart/form-data +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7615">RFC 7615</a>: HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7616">RFC 7616</a>: HTTP Digest Access Authentication +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7617">RFC 7617</a>: The <em>Basic</em> HTTP Authentication Scheme +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7639">RFC 7639</a>: The ALPN HTTP Header Field +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7692">RFC 7692</a>: Compression Extensions for WebSocket +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7694">RFC 7694</a>: HTTP Client-Initiated Content-Encoding +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7725">RFC 7725</a>: An HTTP Status Code to Report Legal Obstacles +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7804">RFC 7804</a>: Salted Challenge Response HTTP Authentication Mechanism +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7838">RFC 7838</a>: HTTP Alternative Services +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7932">RFC 7932</a>: Brotli Compressed Data Format +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7936">RFC 7936</a>: Clarifying Registry Procedures for the WebSocket Subprotocol Name Registry +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8053">RFC 8053</a>: HTTP Authentication Extensions for Interactive Clients +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8164">RFC 8164</a>: Opportunistic Security for HTTP/2 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8187">RFC 8187</a>: Indicating Character Encoding and Language for HTTP Header Field Parameters +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8188">RFC 8188</a>: Encrypted Content-Encoding for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8246">RFC 8246</a>: HTTP Immutable Responses +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/webmention/">Webmention</a>: Webmention +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_upcoming">Upcoming</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="https://www.w3.org/TR/csp-cookies/">Content Security Policy: Cookie Controls</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/csp-embedded-enforcement/">Content Security Policy: Embedded Enforcement</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/CSP3/">Content Security Policy Level 3</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/csp-pinning/">Content Security Policy Pinning</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/referrer-policy/">Referrer Policy</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/UISecurity/">User Interface Security Directives for Content Security Policy</a> +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_informative">Informative</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="http://www.w3.org/TR/webarch/">Architecture of the World Wide Web</a> +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2936">RFC 2936</a>: HTTP MIME Type Handler Detection +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2964">RFC 2964</a>: Use of HTTP State Management +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3143">RFC 3143</a>: Known HTTP Proxy/Caching Problems +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6202">RFC 6202</a>: Known Issues and Best Practices for the Use of Long Polling and Streaming in Bidirectional HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6838">RFC 6838</a>: Media Type Specifications and Registration Procedures +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7478">RFC 7478</a>: Web Real-Time Communication Use Cases and Requirements +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_related">Related</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="http://www.w3.org/TR/app-uri/">app: URL Scheme</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/beacon/">Beacon</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/FileAPI/">File API</a> +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8030">Generic Event Delivery Using HTTP Push</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/capability-urls/">Good Practices for Capability URLs</a> +</p> +</li> +<li> +<p> +<a href="https://html.spec.whatwg.org/multipage/">HTML Living Standard</a> +</p> +</li> +<li> +<p> +<a href="https://developers.whatwg.org/">HTML Living Standard for Web developers</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/html401/">HTML4.01</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/html5/">HTML5</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/html51/">HTML5.1</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/html52/">HTML5.2</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/media-frags/">Media Fragments URI 1.0</a> +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6690">RFC 6690</a>: Constrained RESTful Environments (CoRE) Link Format +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7807">RFC 7807</a>: Problem Details for HTTP APIs +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6906">RFC 6906</a>: The <em>profile</em> Link Relation Type +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/SRI/">Subresource Integrity</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/tracking-compliance/">Tracking Compliance and Scope</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/media-frags-reqs/">Use cases and requirements for Media Fragments</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/webrtc/">WebRTC 1.0: Real-time Communication Between Browsers</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/websockets/">Websocket API</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/XMLHttpRequest/">XMLHttpRequest Level 1</a> +</p> +</li> +<li> +<p> +<a href="https://xhr.spec.whatwg.org/">XMLHttpRequest Living Standard</a> +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_seemingly_obsolete">Seemingly obsolete</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2227">RFC 2227</a>: Simple Hit-Metering and Usage-Limiting for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2310">RFC 2310</a>: The Safe Response Header Field +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2324">RFC 2324</a>: Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2660">RFC 2660</a>: The Secure HyperText Transfer Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2774">RFC 2774</a>: An HTTP Extension Framework +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2965">RFC 2965</a>: HTTP State Management Mechanism (Cookie2) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3229">RFC 3229</a>: Delta encoding in HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7168">RFC 7168</a>: The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA) +</p> +</li> +<li> +<p> +<a href="http://dev.chromium.org/spdy/spdy-protocol">SPDY</a>: SPDY Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/draft-tyoshino-hybi-websocket-perframe-deflate-06">x-webkit-deflate-frame</a>: Deprecated Websocket compression +</p> +</li> +</ul></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_url">URL</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>: URI Generic Syntax +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>: URI Template +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6874">RFC 6874</a>: Representing IPv6 Zone Identifiers in Address Literals and URIs +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7320">RFC 7320</a>: URI Design and Ownership +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/url-1/">URL</a> +</p> +</li> +<li> +<p> +<a href="https://url.spec.whatwg.org/">URL Living Standard</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_webdav">WebDAV</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3253">RFC 3253</a>: Versioning Extensions to WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3648">RFC 3648</a>: WebDAV Ordered Collections Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3744">RFC 3744</a>: WebDAV Access Control Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4316">RFC 4316</a>: Datatypes for WebDAV Properties +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4331">RFC 4331</a>: Quota and Size Properties for DAV Collections +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4437">RFC 4437</a>: WebDAV Redirect Reference Resources +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4709">RFC 4709</a>: Mounting WebDAV Servers +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4791">RFC 4791</a>: Calendaring Extensions to WebDAV (CalDAV) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4918">RFC 4918</a>: HTTP Extensions for WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5323">RFC 5323</a>: WebDAV SEARCH +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5397">RFC 5397</a>: WebDAV Current Principal Extension +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5689">RFC 5689</a>: Extended MKCOL for WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5842">RFC 5842</a>: Binding Extensions to WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5995">RFC 5995</a>: Using POST to Add Members to WebDAV Collections +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6352">RFC 6352</a>: CardDAV: vCard Extensions to WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6578">RFC 6578</a>: Collection Synchronization for WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6638">RFC 6638</a>: Scheduling Extensions to CalDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6764">RFC 6764</a>: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7809">RFC 7809</a>: Calendaring Extensions to WebDAV (CalDAV): Time Zones by Reference +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7953">RFC 7953</a>: Calendar Availability +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8144">RFC 8144</a>: Use of the Prefer Header Field in WebDAV +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_coap">CoAP</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7252">RFC 7252</a>: The Constrained Application Protocol (CoAP) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7390">RFC 7390</a>: Group Communication for CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7641">RFC 7641</a>: Observing Resources in CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7650">RFC 7650</a>: A CoAP Usage for REsource LOcation And Discovery (RELOAD) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7959">RFC 7959</a>: Block-Wise Transfers in CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7967">RFC 7967</a>: CoAP Option for No Server Response +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8075">RFC 8075</a>: Guidelines for Mapping Implementations: HTTP to CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8132">RFC 8132</a>: PATCH and FETCH Methods for CoAP +</p> +</li> +</ul></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/static_files/index.html b/docs/en/cowboy/2.0/guide/static_files/index.html index 2509348f..f7a5c7f9 100644 --- a/docs/en/cowboy/2.0/guide/static_files/index.html +++ b/docs/en/cowboy/2.0/guide/static_files/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Static files</title> @@ -67,179 +67,182 @@ <h1 class="lined-header"><span>Static files</span></h1> -<div class="paragraph"><p>Cowboy comes with a ready to use handler for serving static
-files. It is provided as a convenience for serving files
-during development.</p></div>
-<div class="paragraph"><p>For systems in production, consider using one of the many
-Content Distribution Network (CDN) available on the market,
-as they are the best solution for serving files.</p></div>
-<div class="paragraph"><p>The static handler can serve either one file or all files
-from a given directory. The etag generation and mime types
-can be configured.</p></div>
-<div class="sect1">
-<h2 id="_serve_one_file">Serve one file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can use the static handler to serve one specific file
-from an application’s private directory. This is particularly
-useful to serve an <em>index.html</em> file when the client requests
-the <code>/</code> path, for example. The path configured is relative
-to the given application’s private directory.</p></div>
-<div class="paragraph"><p>The following rule will serve the file <em>static/index.html</em>
-from the application <code>my_app</code>'s priv directory whenever the
-path <code>/</code> is accessed:</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="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>}}</tt></pre></div></div>
-<div class="paragraph"><p>You can also specify the absolute path to a file, or the
-path to the file relative to the current directory:</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="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">file</span>, <span style="color: #FF0000">"/var/www/index.html"</span>}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_serve_all_files_from_a_directory">Serve all files from a directory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can also use the static handler to serve all files that
-can be found in the configured directory. The handler will
-use the <code>path_info</code> information to resolve the file location,
-which means that your route must end with a <code>[...]</code> pattern
-for it to work. All files are served, including the ones that
-may be found in subfolders.</p></div>
-<div class="paragraph"><p>You can specify the directory relative to an application’s
-private directory.</p></div>
-<div class="paragraph"><p>The following rule will serve any file found in the application
-<code>my_app</code>'s priv directory inside the <code>static/assets</code> folder
-whenever the requested path begins with <code>/assets/</code>:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>}}</tt></pre></div></div>
-<div class="paragraph"><p>You can also specify the absolute path to the directory or
-set it relative to the current directory:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">dir</span>, <span style="color: #FF0000">"/var/www/assets"</span>}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customize_the_mimetype_detection">Customize the mimetype detection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, Cowboy will attempt to recognize the mimetype
-of your static files by looking at the extension.</p></div>
-<div class="paragraph"><p>You can override the function that figures out the mimetype
-of the static files. It can be useful when Cowboy is missing
-a mimetype you need to handle, or when you want to reduce
-the list to make lookups faster. You can also give a
-hard-coded mimetype that will be used unconditionally.</p></div>
-<div class="paragraph"><p>Cowboy comes with two functions built-in. The default
-function only handles common file types used when building
-Web applications. The other function is an extensive list
-of hundreds of mimetypes that should cover almost any need
-you may have. You can of course create your own function.</p></div>
-<div class="paragraph"><p>To use the default function, you should not have to configure
-anything, as it is the default. If you insist, though, the
-following will do the job:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">web</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>As you can see, there is an optional field that may contain
-a list of less used options, like mimetypes or etag. All option
-types have this optional field.</p></div>
-<div class="paragraph"><p>To use the function that will detect almost any mimetype,
-the following configuration will do:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">all</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>You probably noticed the pattern by now. The configuration
-expects a module and a function name, so you can use any
-of your own functions instead:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>The function that performs the mimetype detection receives
-a single argument that is the path to the file on disk. It
-is recommended to return the mimetype in tuple form, although
-a binary string is also allowed (but will require extra
-processing). If the function can’t figure out the mimetype,
-then it should return <code>{<<"application">>, <<"octet-stream">>, []}</code>.</p></div>
-<div class="paragraph"><p>When the static handler fails to find the extension,
-it will send the file as <code>application/octet-stream</code>.
-A browser receiving such file will attempt to download it
-directly to disk.</p></div>
-<div class="paragraph"><p>Finally, the mimetype can be hard-coded for all files.
-This is especially useful in combination with the <code>file</code>
-and <code>priv_file</code> options as it avoids needless computation:</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="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>,
- [{<span style="color: #FF6600">mimetypes</span>, {<span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"html"</span><span style="color: #990000">>></span>, []}}]}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generate_an_etag">Generate an etag</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, the static handler will generate an etag header
-value based on the size and modified time. This solution
-can not be applied to all systems though. It would perform
-rather poorly over a cluster of nodes, for example, as the
-file metadata will vary from server to server, giving a
-different etag on each server.</p></div>
-<div class="paragraph"><p>You can however change the way the etag is calculated:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">etag</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>This function will receive three arguments: the path to the
-file on disk, the size of the file and the last modification
-time. In a distributed setup, you would typically use the
-file path to retrieve an etag value that is identical across
-all your servers.</p></div>
-<div class="paragraph"><p>You can also completely disable etag handling:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}]}}</tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy comes with a ready to use handler for serving static +files. It is provided as a convenience for serving files +during development.</p></div> +<div class="paragraph"><p>For systems in production, consider using one of the many +Content Distribution Network (CDN) available on the market, +as they are the best solution for serving files.</p></div> +<div class="paragraph"><p>The static handler can serve either one file or all files +from a given directory. The etag generation and mime types +can be configured.</p></div> +<div class="sect1"> +<h2 id="_serve_one_file">Serve one file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can use the static handler to serve one specific file +from an application’s private directory. This is particularly +useful to serve an <em>index.html</em> file when the client requests +the <code>/</code> path, for example. The path configured is relative +to the given application’s private directory.</p></div> +<div class="paragraph"><p>The following rule will serve the file <em>static/index.html</em> +from the application <code>my_app</code>'s priv directory whenever the +path <code>/</code> is accessed:</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="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>}}</tt></pre></div></div> +<div class="paragraph"><p>You can also specify the absolute path to a file, or the +path to the file relative to the current directory:</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="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">file</span>, <span style="color: #FF0000">"/var/www/index.html"</span>}}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_serve_all_files_from_a_directory">Serve all files from a directory</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can also use the static handler to serve all files that +can be found in the configured directory. The handler will +use the <code>path_info</code> information to resolve the file location, +which means that your route must end with a <code>[...]</code> pattern +for it to work. All files are served, including the ones that +may be found in subfolders.</p></div> +<div class="paragraph"><p>You can specify the directory relative to an application’s +private directory.</p></div> +<div class="paragraph"><p>The following rule will serve any file found in the application +<code>my_app</code>'s priv directory inside the <code>static/assets</code> folder +whenever the requested path begins with <code>/assets/</code>:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>}}</tt></pre></div></div> +<div class="paragraph"><p>You can also specify the absolute path to the directory or +set it relative to the current directory:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">dir</span>, <span style="color: #FF0000">"/var/www/assets"</span>}}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customize_the_mimetype_detection">Customize the mimetype detection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default, Cowboy will attempt to recognize the mimetype +of your static files by looking at the extension.</p></div> +<div class="paragraph"><p>You can override the function that figures out the mimetype +of the static files. It can be useful when Cowboy is missing +a mimetype you need to handle, or when you want to reduce +the list to make lookups faster. You can also give a +hard-coded mimetype that will be used unconditionally.</p></div> +<div class="paragraph"><p>Cowboy comes with two functions built-in. The default +function only handles common file types used when building +Web applications. The other function is an extensive list +of hundreds of mimetypes that should cover almost any need +you may have. You can of course create your own function.</p></div> +<div class="paragraph"><p>To use the default function, you should not have to configure +anything, as it is the default. If you insist, though, the +following will do the job:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">web</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>As you can see, there is an optional field that may contain +a list of less used options, like mimetypes or etag. All option +types have this optional field.</p></div> +<div class="paragraph"><p>To use the function that will detect almost any mimetype, +the following configuration will do:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">all</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>You probably noticed the pattern by now. The configuration +expects a module and a function name, so you can use any +of your own functions instead:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>The function that performs the mimetype detection receives +a single argument that is the path to the file on disk. It +is recommended to return the mimetype in tuple form, although +a binary string is also allowed (but will require extra +processing). If the function can’t figure out the mimetype, +then it should return <code>{<<"application">>, <<"octet-stream">>, []}</code>.</p></div> +<div class="paragraph"><p>When the static handler fails to find the extension, +it will send the file as <code>application/octet-stream</code>. +A browser receiving such file will attempt to download it +directly to disk.</p></div> +<div class="paragraph"><p>Finally, the mimetype can be hard-coded for all files. +This is especially useful in combination with the <code>file</code> +and <code>priv_file</code> options as it avoids needless computation:</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="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>, + [{<span style="color: #FF6600">mimetypes</span>, {<span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"html"</span><span style="color: #990000">>></span>, []}}]}}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generate_an_etag">Generate an etag</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default, the static handler will generate an etag header +value based on the size and modified time. This solution +can not be applied to all systems though. It would perform +rather poorly over a cluster of nodes, for example, as the +file metadata will vary from server to server, giving a +different etag on each server.</p></div> +<div class="paragraph"><p>You can however change the way the etag is calculated:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">etag</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>This function will receive three arguments: the path to the +file on disk, the size of the file and the last modification +time. In a distributed setup, you would typically use the +file path to retrieve an etag value that is identical across +all your servers.</p></div> +<div class="paragraph"><p>You can also completely disable etag handling:</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="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}]}}</tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/streams/index.html b/docs/en/cowboy/2.0/guide/streams/index.html index 4641b9b1..e7c82dd1 100644 --- a/docs/en/cowboy/2.0/guide/streams/index.html +++ b/docs/en/cowboy/2.0/guide/streams/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Streams</title> @@ -67,67 +67,70 @@ <h1 class="lined-header"><span>Streams</span></h1> -<div class="paragraph"><p>A stream is the set of messages that form an HTTP
-request/response pair.</p></div>
-<div class="paragraph"><p>The term stream comes from HTTP/2. In Cowboy, it is
-also used when talking about HTTP/1.1 or HTTP/1.0.
-It should not be confused with streaming the request
-or response body.</p></div>
-<div class="paragraph"><p>All versions of HTTP allow clients to initiate
-streams. HTTP/2 is the only one also allowing servers,
-through its server push feature. Both client and
-server-initiated streams go through the same process
-in Cowboy.</p></div>
-<div class="sect1">
-<h2 id="_stream_handlers">Stream handlers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Stream handlers must implement five different callbacks.
-Four of them are directly related; one is special.</p></div>
-<div class="paragraph"><p>All callbacks receives the stream ID as first argument.</p></div>
-<div class="paragraph"><p>Most of them can return a list of commands to be executed
-by Cowboy. When callbacks are chained, it is possible to
-intercept and modify these commands. This can be useful
-for modifying responses for example.</p></div>
-<div class="paragraph"><p>The <code>init/3</code> callback is invoked when a new request
-comes in. It receives the Req object and the protocol options
-for this listener.</p></div>
-<div class="paragraph"><p>The <code>data/4</code> callback is invoked when data from the request
-body is received. It receives both this data and a flag
-indicating whether more is to be expected.</p></div>
-<div class="paragraph"><p>The <code>info/3</code> callback is invoked when an Erlang message is
-received for this stream. They will typically be messages
-sent by the request process.</p></div>
-<div class="paragraph"><p>Finally the <code>terminate/3</code> callback is invoked with the
-terminate reason for the stream. The return value is ignored.
-Note that as with all terminate callbacks in Erlang, there
-is no strong guarantee that it will be called.</p></div>
-<div class="paragraph"><p>The special callback <code>early_error/5</code> is called when an error
-occurs before the request headers were fully received and
-Cowboy is sending a response. It receives the partial Req
-object, the error reason, the protocol options and the response
-Cowboy will send. This response must be returned, possibly
-modified.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_built_in_handlers">Built-in handlers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy comes with two handlers.</p></div>
-<div class="paragraph"><p><code>cowboy_stream_h</code> is the default stream handler.
-It is the core of much of the functionality of Cowboy.
-All chains of stream handlers should call it last.</p></div>
-<div class="paragraph"><p><code>cowboy_compress_h</code> will automatically compress
-responses when possible. It is not enabled by default.
-It is a good example for writing your own handlers
-that will modify responses.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A stream is the set of messages that form an HTTP +request/response pair.</p></div> +<div class="paragraph"><p>The term stream comes from HTTP/2. In Cowboy, it is +also used when talking about HTTP/1.1 or HTTP/1.0. +It should not be confused with streaming the request +or response body.</p></div> +<div class="paragraph"><p>All versions of HTTP allow clients to initiate +streams. HTTP/2 is the only one also allowing servers, +through its server push feature. Both client and +server-initiated streams go through the same process +in Cowboy.</p></div> +<div class="sect1"> +<h2 id="_stream_handlers">Stream handlers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Stream handlers must implement five different callbacks. +Four of them are directly related; one is special.</p></div> +<div class="paragraph"><p>All callbacks receives the stream ID as first argument.</p></div> +<div class="paragraph"><p>Most of them can return a list of commands to be executed +by Cowboy. When callbacks are chained, it is possible to +intercept and modify these commands. This can be useful +for modifying responses for example.</p></div> +<div class="paragraph"><p>The <code>init/3</code> callback is invoked when a new request +comes in. It receives the Req object and the protocol options +for this listener.</p></div> +<div class="paragraph"><p>The <code>data/4</code> callback is invoked when data from the request +body is received. It receives both this data and a flag +indicating whether more is to be expected.</p></div> +<div class="paragraph"><p>The <code>info/3</code> callback is invoked when an Erlang message is +received for this stream. They will typically be messages +sent by the request process.</p></div> +<div class="paragraph"><p>Finally the <code>terminate/3</code> callback is invoked with the +terminate reason for the stream. The return value is ignored. +Note that as with all terminate callbacks in Erlang, there +is no strong guarantee that it will be called.</p></div> +<div class="paragraph"><p>The special callback <code>early_error/5</code> is called when an error +occurs before the request headers were fully received and +Cowboy is sending a response. It receives the partial Req +object, the error reason, the protocol options and the response +Cowboy will send. This response must be returned, possibly +modified.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_built_in_handlers">Built-in handlers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy comes with two handlers.</p></div> +<div class="paragraph"><p><code>cowboy_stream_h</code> is the default stream handler. +It is the core of much of the functionality of Cowboy. +All chains of stream handlers should call it last.</p></div> +<div class="paragraph"><p><code>cowboy_compress_h</code> will automatically compress +responses when possible. It is not enabled by default. +It is a good example for writing your own handlers +that will modify responses.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc index 61a523b0..84dfb9bc 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc @@ -151,7 +151,9 @@ websocket_info(_Info, State) -> === Sending frames -// @todo So yeah, reply makes no sense. Maybe change it to send. Sigh. +// @todo This will be deprecated and eventually replaced with a +// {Commands, State} interface that allows providing more +// functionality easily. All `websocket_` callbacks share return values. They may send zero, one or many frames to the client. @@ -222,8 +224,6 @@ init(Req, State) -> This value cannot be changed once it is set. It defaults to `60000`. -// @todo Perhaps the default should be changed. - === Saving memory The Websocket connection process can be set to hibernate diff --git a/docs/en/cowboy/2.0/guide/ws_handlers/index.html b/docs/en/cowboy/2.0/guide/ws_handlers/index.html index 7ec685bf..334bb049 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/ws_handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Websocket handlers</title> @@ -67,276 +67,279 @@ <h1 class="lined-header"><span>Websocket handlers</span></h1> -<div class="paragraph"><p>Websocket handlers provide an interface for upgrading HTTP/1.1
-connections to Websocket and sending or receiving frames on
-the Websocket connection.</p></div>
-<div class="paragraph"><p>As Websocket connections are established through the HTTP/1.1
-upgrade mechanism, Websocket handlers need to be able to first
-receive the HTTP request for the upgrade, before switching to
-Websocket and taking over the connection. They can then receive
-or send Websocket frames, handle incoming Erlang messages or
-close the connection.</p></div>
-<div class="sect1">
-<h2 id="_upgrade">Upgrade</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>init/2</code> callback is called when the request is received.
-To establish a Websocket connection, you must switch to the
-<code>cowboy_websocket</code> module:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy will perform the Websocket handshake immediately. Note
-that the handshake will fail if the client did not request an
-upgrade to Websocket.</p></div>
-<div class="paragraph"><p>The Req object becomes unavailable after this function returns.
-Any information required for proper execution of the Websocket
-handler must be saved in the state.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_subprotocol">Subprotocol</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The client may provide a list of Websocket subprotocols it
-supports in the sec-websocket-protocol header. The server <strong>must</strong>
-select one of them and send it back to the client or the
-handshake will fail.</p></div>
-<div class="paragraph"><p>For example, a client could understand both STOMP and MQTT over
-Websocket, and provide the header:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>sec-websocket-protocol: v12.stomp, mqtt</code></pre>
-</div></div>
-<div class="paragraph"><p>If the server only understands MQTT it can return:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>sec-websocket-protocol: mqtt</code></pre>
-</div></div>
-<div class="paragraph"><p>This selection must be done in <code>init/2</code>. An example usage could
-be:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</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">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #000080">undefined</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
- <span style="color: #009900">Subprotocols</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">lists:keymember</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Subprotocols</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #000080">true</span> <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>,
- <span style="color: #990000"><<</span><span style="color: #FF0000">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>};
- <span style="color: #000080">false</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></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="_post_upgrade_initialization">Post-upgrade initialization</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy has separate processes for handling the connection
-and requests. Because Websocket takes over the connection,
-the Websocket protocol handling occurs in a different
-process than the request handling.</p></div>
-<div class="paragraph"><p>This is reflected in the different callbacks Websocket
-handlers have. The <code>init/2</code> callback is called from the
-temporary request process and the <code>websocket_</code> callbacks
-from the connection process.</p></div>
-<div class="paragraph"><p>This means that some initialization cannot be done from
-<code>init/2</code>. Anything that would require the current pid,
-or be tied to the current pid, will not work as intended.
-The optional <code>websocket_init/1</code> can be used instead:</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: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">erlang:start_timer</span></span>(<span style="color: #993399">1000</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>(), <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All Websocket callbacks share the same return values. This
-means that we can send frames to the client right after
-the upgrade:</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: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_receiving_frames">Receiving frames</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will call <code>websocket_handle/2</code> whenever a text, binary,
-ping or pong frame arrives from the client.</p></div>
-<div class="paragraph"><p>The handler can handle or ignore the frames. It can also
-send frames back to the client or stop the connection.</p></div>
-<div class="paragraph"><p>The following snippet echoes back any text frame received and
-ignores all others:</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: #000000">websocket_handle</span></span>(<span style="color: #009900">Frame</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">text</span>, <span style="color: #990000">_</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, <span style="color: #009900">Frame</span>, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that ping and pong frames require no action from the
-handler as Cowboy will automatically reply to ping frames.
-They are provided for informative purposes only.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_receiving_erlang_messages">Receiving Erlang messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will call <code>websocket_info/2</code> whenever an Erlang message
-arrives.</p></div>
-<div class="paragraph"><p>The handler can handle or ignore the messages. It can also
-send frames to the client or stop the connection.</p></div>
-<div class="paragraph"><p>The following snippet forwards log messages to the client
-and ignores all others:</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: #000000">websocket_info</span></span>({<span style="font-weight: bold"><span style="color: #000080">log</span></span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_frames">Sending frames</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All <code>websocket_</code> callbacks share return values. They may
-send zero, one or many frames to the client.</p></div>
-<div class="paragraph"><p>To send nothing, just return an ok tuple:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To send one frame, return a reply tuple with the frame to send:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can send frames of any type: text, binary, ping, pong
-or close frames.</p></div>
-<div class="paragraph"><p>To send many frames at once, return a reply tuple with the
-list of frames to send:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, [
- {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello"</span>},
- {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"world!"</span><span style="color: #990000">>></span>},
- {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #990000"><<</span><span style="color: #993399">0</span><span style="color: #990000">:</span><span style="color: #993399">8000</span><span style="color: #990000">>></span>}
- ], <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>They are sent in the given order.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_keeping_the_connection_alive">Keeping the connection alive</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will automatically respond to ping frames sent by
-the client. They are still forwarded to the handler for
-informative purposes, but no further action is required.</p></div>
-<div class="paragraph"><p>Cowboy does not send ping frames itself. The handler can
-do it if required. A better solution in most cases is to
-let the client handle pings. Doing it from the handler
-would imply having an additional timer per connection and
-this can be a considerable cost for servers that need to
-handle large numbers of connections.</p></div>
-<div class="paragraph"><p>Cowboy can be configured to close idle connections
-automatically. It is highly recommended to configure
-a timeout here, to avoid having processes linger longer
-than needed.</p></div>
-<div class="paragraph"><p>The <code>init/2</code> callback can set the timeout to be used
-for the connection. For example, this would make Cowboy
-close connections idle for more than 30 seconds:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, #{
- <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="color: #993399">30000</span>}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This value cannot be changed once it is set. It defaults to
-<code>60000</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_saving_memory">Saving memory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The Websocket connection process can be set to hibernate
-after the callback returns.</p></div>
-<div class="paragraph"><p>Simply add an <code>hibernate</code> field to the ok or reply tuples:</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: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It is highly recommended to write your handlers with
-hibernate enabled, as this allows to greatly reduce the
-memory usage. Do note however that an increase in the
-CPU usage or latency can be observed instead, in particular
-for the more busy connections.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_closing_the_connection">Closing the connection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The connection can be closed at any time, either by telling
-Cowboy to stop it or by sending a close frame.</p></div>
-<div class="paragraph"><p>To tell Cowboy to close the connection, use a stop tuple:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Sending a <code>close</code> frame will immediately initiate the closing
-of the Websocket connection. Note that when sending a list of
-frames that include a close frame, any frame found after the
-close frame will not be sent.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Websocket handlers provide an interface for upgrading HTTP/1.1 +connections to Websocket and sending or receiving frames on +the Websocket connection.</p></div> +<div class="paragraph"><p>As Websocket connections are established through the HTTP/1.1 +upgrade mechanism, Websocket handlers need to be able to first +receive the HTTP request for the upgrade, before switching to +Websocket and taking over the connection. They can then receive +or send Websocket frames, handle incoming Erlang messages or +close the connection.</p></div> +<div class="sect1"> +<h2 id="_upgrade">Upgrade</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>init/2</code> callback is called when the request is received. +To establish a Websocket connection, you must switch to the +<code>cowboy_websocket</code> module:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cowboy will perform the Websocket handshake immediately. Note +that the handshake will fail if the client did not request an +upgrade to Websocket.</p></div> +<div class="paragraph"><p>The Req object becomes unavailable after this function returns. +Any information required for proper execution of the Websocket +handler must be saved in the state.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_subprotocol">Subprotocol</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The client may provide a list of Websocket subprotocols it +supports in the sec-websocket-protocol header. The server <strong>must</strong> +select one of them and send it back to the client or the +handshake will fail.</p></div> +<div class="paragraph"><p>For example, a client could understand both STOMP and MQTT over +Websocket, and provide the header:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>sec-websocket-protocol: v12.stomp, mqtt</code></pre> +</div></div> +<div class="paragraph"><p>If the server only understands MQTT it can return:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>sec-websocket-protocol: mqtt</code></pre> +</div></div> +<div class="paragraph"><p>This selection must be done in <code>init/2</code>. An example usage could +be:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</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">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #000080">undefined</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}; + <span style="color: #009900">Subprotocols</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">lists:keymember</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Subprotocols</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #000080">true</span> <span style="color: #990000">-></span> + <span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, + <span style="color: #990000"><<</span><span style="color: #FF0000">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>), + {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>}; + <span style="color: #000080">false</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></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="_post_upgrade_initialization">Post-upgrade initialization</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy has separate processes for handling the connection +and requests. Because Websocket takes over the connection, +the Websocket protocol handling occurs in a different +process than the request handling.</p></div> +<div class="paragraph"><p>This is reflected in the different callbacks Websocket +handlers have. The <code>init/2</code> callback is called from the +temporary request process and the <code>websocket_</code> callbacks +from the connection process.</p></div> +<div class="paragraph"><p>This means that some initialization cannot be done from +<code>init/2</code>. Anything that would require the current pid, +or be tied to the current pid, will not work as intended. +The optional <code>websocket_init/1</code> can be used instead:</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: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">erlang:start_timer</span></span>(<span style="color: #993399">1000</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>(), <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All Websocket callbacks share the same return values. This +means that we can send frames to the client right after +the upgrade:</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: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_receiving_frames">Receiving frames</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will call <code>websocket_handle/2</code> whenever a text, binary, +ping or pong frame arrives from the client.</p></div> +<div class="paragraph"><p>The handler can handle or ignore the frames. It can also +send frames back to the client or stop the connection.</p></div> +<div class="paragraph"><p>The following snippet echoes back any text frame received and +ignores all others:</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: #000000">websocket_handle</span></span>(<span style="color: #009900">Frame</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">text</span>, <span style="color: #990000">_</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, <span style="color: #009900">Frame</span>, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that ping and pong frames require no action from the +handler as Cowboy will automatically reply to ping frames. +They are provided for informative purposes only.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_receiving_erlang_messages">Receiving Erlang messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will call <code>websocket_info/2</code> whenever an Erlang message +arrives.</p></div> +<div class="paragraph"><p>The handler can handle or ignore the messages. It can also +send frames to the client or stop the connection.</p></div> +<div class="paragraph"><p>The following snippet forwards log messages to the client +and ignores all others:</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: #000000">websocket_info</span></span>({<span style="font-weight: bold"><span style="color: #000080">log</span></span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_frames">Sending frames</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All <code>websocket_</code> callbacks share return values. They may +send zero, one or many frames to the client.</p></div> +<div class="paragraph"><p>To send nothing, just return an ok tuple:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To send one frame, return a reply tuple with the frame to send:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can send frames of any type: text, binary, ping, pong +or close frames.</p></div> +<div class="paragraph"><p>To send many frames at once, return a reply tuple with the +list of frames to send:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, [ + {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello"</span>}, + {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"world!"</span><span style="color: #990000">>></span>}, + {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #990000"><<</span><span style="color: #993399">0</span><span style="color: #990000">:</span><span style="color: #993399">8000</span><span style="color: #990000">>></span>} + ], <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>They are sent in the given order.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_keeping_the_connection_alive">Keeping the connection alive</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will automatically respond to ping frames sent by +the client. They are still forwarded to the handler for +informative purposes, but no further action is required.</p></div> +<div class="paragraph"><p>Cowboy does not send ping frames itself. The handler can +do it if required. A better solution in most cases is to +let the client handle pings. Doing it from the handler +would imply having an additional timer per connection and +this can be a considerable cost for servers that need to +handle large numbers of connections.</p></div> +<div class="paragraph"><p>Cowboy can be configured to close idle connections +automatically. It is highly recommended to configure +a timeout here, to avoid having processes linger longer +than needed.</p></div> +<div class="paragraph"><p>The <code>init/2</code> callback can set the timeout to be used +for the connection. For example, this would make Cowboy +close connections idle for more than 30 seconds:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, #{ + <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="color: #993399">30000</span>}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This value cannot be changed once it is set. It defaults to +<code>60000</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_saving_memory">Saving memory</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The Websocket connection process can be set to hibernate +after the callback returns.</p></div> +<div class="paragraph"><p>Simply add an <code>hibernate</code> field to the ok or reply tuples:</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: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It is highly recommended to write your handlers with +hibernate enabled, as this allows to greatly reduce the +memory usage. Do note however that an increase in the +CPU usage or latency can be observed instead, in particular +for the more busy connections.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_closing_the_connection">Closing the connection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The connection can be closed at any time, either by telling +Cowboy to stop it or by sending a close frame.</p></div> +<div class="paragraph"><p>To tell Cowboy to close the connection, use a stop tuple:</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: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Sending a <code>close</code> frame will immediately initiate the closing +of the Websocket connection. Note that when sending a list of +frames that include a close frame, any frame found after the +close frame will not be sent.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/ws_protocol/index.html b/docs/en/cowboy/2.0/guide/ws_protocol/index.html index 38b754b0..d70fe10d 100644 --- a/docs/en/cowboy/2.0/guide/ws_protocol/index.html +++ b/docs/en/cowboy/2.0/guide/ws_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The Websocket protocol</title> @@ -67,76 +67,79 @@ <h1 class="lined-header"><span>The Websocket protocol</span></h1> -<div class="paragraph"><p>This chapter explains what Websocket is and why it is
-a vital component of soft realtime Web applications.</p></div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket is an extension to HTTP that emulates plain TCP
-connections between the client, typically a Web browser,
-and the server. It uses the HTTP Upgrade mechanism to
-establish the connection.</p></div>
-<div class="paragraph"><p>Websocket connections are fully asynchronous, unlike
-HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the
-server can only initiate streams in response to requests).
-With Websocket, the client and the server can both send
-frames at any time without any restriction. It is closer
-to TCP than any of the HTTP protocols.</p></div>
-<div class="paragraph"><p>Websocket is an IETF standard. Cowboy supports the standard
-and all drafts that were previously implemented by browsers,
-excluding the initial flawed draft sometimes known as
-"version 0".</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_websocket_vs_http_2">Websocket vs HTTP/2</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>For a few years Websocket was the only way to have a
-bidirectional asynchronous connection with the server.
-This changed when HTTP/2 was introduced. While HTTP/2
-requires the client to first perform a request before
-the server can push data, this is only a minor restriction
-as the client can do so just as it connects.</p></div>
-<div class="paragraph"><p>Websocket was designed as a kind-of-TCP channel to a
-server. It only defines the framing and connection
-management and lets the developer implement a protocol
-on top of it. For example you could implement IRC over
-Websocket and use a Javascript IRC client to speak to
-the server.</p></div>
-<div class="paragraph"><p>HTTP/2 on the other hand is just an improvement over
-the HTTP/1.1 connection and request/response mechanism.
-It has the same semantics as HTTP/1.1.</p></div>
-<div class="paragraph"><p>If all you need is to access an HTTP API, then HTTP/2
-should be your first choice. On the other hand, if what
-you need is a different protocol, then you can use
-Websocket to implement it.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_implementation">Implementation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy implements Websocket as a protocol upgrade. Once the
-upgrade is performed from the <code>init/2</code> callback, Cowboy
-switches to Websocket. Please consult the next chapter for
-more information on initiating and handling Websocket
-connections.</p></div>
-<div class="paragraph"><p>The implementation of Websocket in Cowboy is validated using
-the Autobahn test suite, which is an extensive suite of tests
-covering all aspects of the protocol. Cowboy passes the
-suite with 100% success, including all optional tests.</p></div>
-<div class="paragraph"><p>Cowboy’s Websocket implementation also includes the
-permessage-deflate and x-webkit-deflate-frame compression
-extensions.</p></div>
-<div class="paragraph"><p>Cowboy will automatically use compression when the
-<code>compress</code> option is returned from the <code>init/2</code> function.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter explains what Websocket is and why it is +a vital component of soft realtime Web applications.</p></div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Websocket is an extension to HTTP that emulates plain TCP +connections between the client, typically a Web browser, +and the server. It uses the HTTP Upgrade mechanism to +establish the connection.</p></div> +<div class="paragraph"><p>Websocket connections are fully asynchronous, unlike +HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the +server can only initiate streams in response to requests). +With Websocket, the client and the server can both send +frames at any time without any restriction. It is closer +to TCP than any of the HTTP protocols.</p></div> +<div class="paragraph"><p>Websocket is an IETF standard. Cowboy supports the standard +and all drafts that were previously implemented by browsers, +excluding the initial flawed draft sometimes known as +"version 0".</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_websocket_vs_http_2">Websocket vs HTTP/2</h2> +<div class="sectionbody"> +<div class="paragraph"><p>For a few years Websocket was the only way to have a +bidirectional asynchronous connection with the server. +This changed when HTTP/2 was introduced. While HTTP/2 +requires the client to first perform a request before +the server can push data, this is only a minor restriction +as the client can do so just as it connects.</p></div> +<div class="paragraph"><p>Websocket was designed as a kind-of-TCP channel to a +server. It only defines the framing and connection +management and lets the developer implement a protocol +on top of it. For example you could implement IRC over +Websocket and use a Javascript IRC client to speak to +the server.</p></div> +<div class="paragraph"><p>HTTP/2 on the other hand is just an improvement over +the HTTP/1.1 connection and request/response mechanism. +It has the same semantics as HTTP/1.1.</p></div> +<div class="paragraph"><p>If all you need is to access an HTTP API, then HTTP/2 +should be your first choice. On the other hand, if what +you need is a different protocol, then you can use +Websocket to implement it.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_implementation">Implementation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy implements Websocket as a protocol upgrade. Once the +upgrade is performed from the <code>init/2</code> callback, Cowboy +switches to Websocket. Please consult the next chapter for +more information on initiating and handling Websocket +connections.</p></div> +<div class="paragraph"><p>The implementation of Websocket in Cowboy is validated using +the Autobahn test suite, which is an extensive suite of tests +covering all aspects of the protocol. Cowboy passes the +suite with 100% success, including all optional tests.</p></div> +<div class="paragraph"><p>Cowboy’s Websocket implementation also includes the +permessage-deflate and x-webkit-deflate-frame compression +extensions.</p></div> +<div class="paragraph"><p>Cowboy will automatically use compression when the +<code>compress</code> option is returned from the <code>init/2</code> function.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/index.html b/docs/en/cowboy/2.0/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/2.0/index.html +++ b/docs/en/cowboy/2.0/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html b/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html index 1381c03d..914b466c 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:set_env(3)</title> @@ -67,117 +67,117 @@ <h1 class="lined-header"><span>cowboy:set_env(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:set_env - Update a listener’s environment value</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">set_env</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(),
- <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>())
- <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span></tt></pre></div></div>
-<div class="paragraph"><p>Set or update an environment value for a previously started
-listener.</p></div>
-<div class="paragraph"><p>This is most useful for updating the routes dynamically,
-without having to restart the listener.</p></div>
-<div class="paragraph"><p>The new value will only be available to new connections.
-Pre-existing connections will still use the old value.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The name of the listener to update.
-</p>
-<div class="paragraph"><p>The name of the listener is the first argument given to the
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or
-<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div>
-</dd>
-<dt class="hdlist1">
-Key
-</dt>
-<dd>
-<p>
-The key in the environment map. Common keys include <code>dispatch</code>
-and <code>middlewares</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-Value
-</dt>
-<dd>
-<p>
-The new value.
-</p>
-<div class="paragraph"><p>The type of the value differs depending on the key.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div>
-<div class="paragraph"><p>An <code>exit:badarg</code> exception is thrown when the listener does
-not exist.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Update a listener’s routes</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- {<span style="color: #FF6600">'_'</span>, [
- {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []},
- {<span style="color: #FF0000">"/ws"</span>, <span style="color: #FF6600">websocket_h</span>, []}
- ]}
-]),
-
-<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../ranch.set_protocol_options">ranch:set_protocol_options(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:set_env - Update a listener’s environment value</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">set_env</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), + <span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), + <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()) + <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span></tt></pre></div></div> +<div class="paragraph"><p>Set or update an environment value for a previously started +listener.</p></div> +<div class="paragraph"><p>This is most useful for updating the routes dynamically, +without having to restart the listener.</p></div> +<div class="paragraph"><p>The new value will only be available to new connections. +Pre-existing connections will still use the old value.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The name of the listener to update. +</p> +<div class="paragraph"><p>The name of the listener is the first argument given to the +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or +<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div> +</dd> +<dt class="hdlist1"> +Key +</dt> +<dd> +<p> +The key in the environment map. Common keys include <code>dispatch</code> +and <code>middlewares</code>. +</p> +</dd> +<dt class="hdlist1"> +Value +</dt> +<dd> +<p> +The new value. +</p> +<div class="paragraph"><p>The type of the value differs depending on the key.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div> +<div class="paragraph"><p>An <code>exit:badarg</code> exception is thrown when the listener does +not exist.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Update a listener’s routes</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + {<span style="color: #FF6600">'_'</span>, [ + {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []}, + {<span style="color: #FF0000">"/ws"</span>, <span style="color: #FF6600">websocket_h</span>, []} + ]} +]), + +<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, +<a href="../ranch.set_protocol_options">ranch:set_protocol_options(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html b/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html index 81f53fd4..a544cc71 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:start_clear(3)</title> @@ -67,151 +67,148 @@ <h1 class="lined-header"><span>cowboy:start_clear(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:start_clear - Listen for connections using plain TCP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">start_clear</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_tcp:opts</span></span>(),
- <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>())
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Start listening for connections over a clear TCP channel.</p></div>
-<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener.
-HTTP/2 has two methods of establishing a connection over
-a clear TCP channel. Both the upgrade and the prior knowledge
-methods are supported.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The listener name is used to refer to this listener in
-future calls, for example when stopping it or when
-updating the routes defined.
-</p>
-<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough,
-for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div>
-</dd>
-<dt class="hdlist1">
-TransportOpts
-</dt>
-<dd>
-<p>
-The transport options are where the TCP options, including
-the listener’s port number, are defined. Transport options
-are provided as a list of keys and values, for example
-<code>[{port, 8080}]</code>.
-</p>
-<div class="paragraph"><p>The available options are documented in the
-<a href="../ranch_tcp">ranch_tcp(3)</a> manual.</p></div>
-</dd>
-<dt class="hdlist1">
-ProtocolOpts
-</dt>
-<dd>
-<p>
-The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-</p>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual;
-the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>;
-and the Websocket options in
-<a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of
-the top-level supervisor for the listener.</p></div>
-<div class="paragraph"><p>An error tuple is returned on error. The error reason may
-be any Erlang term.</p></div>
-<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port
-configured for Cowboy is already in use.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: HTTP/2 support added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_http/4</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Start a listener</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- {<span style="color: #FF6600">'_'</span>, [
- {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []}
- ]}
-]),
-
-{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">example</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}
-})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</span>,
-
-{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #009900">Name</span>, [], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}
-}),
-
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:start_clear - Listen for connections using plain TCP</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">start_clear</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), + <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_tcp:opts</span></span>(), + <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>()) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()} + | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Start listening for connections over a clear TCP channel.</p></div> +<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener. +HTTP/2 has two methods of establishing a connection over +a clear TCP channel. Both the upgrade and the prior knowledge +methods are supported.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The listener name is used to refer to this listener in +future calls, for example when stopping it or when +updating the routes defined. +</p> +<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough, +for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div> +</dd> +<dt class="hdlist1"> +TransportOpts +</dt> +<dd> +<p> +The transport options are where the TCP options, including +the listener’s port number, are defined. Transport options +are provided as a list of keys and values, for example +<code>[{port, 8080}]</code>. +</p> +<div class="paragraph"><p>The available options are documented in the +<a href="../ranch_tcp">ranch_tcp(3)</a> manual.</p></div> +</dd> +<dt class="hdlist1"> +ProtocolOpts +</dt> +<dd> +<p> +The protocol options are in a map containing all the options for +the different protocols that may be involved when connecting +to the listener, including HTTP/1.1 and HTTP/2. +</p> +<div class="paragraph"><p>The HTTP/1.1 options are documented in the +<a href="../cowboy_http">cowboy_http(3)</a> manual; +and the HTTP/2 options in +<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of +the top-level supervisor for the listener.</p></div> +<div class="paragraph"><p>An error tuple is returned on error. The error reason may +be any Erlang term.</p></div> +<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port +configured for Cowboy is already in use.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: HTTP/2 support added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_http/4</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Start a listener</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + {<span style="color: #FF6600">'_'</span>, [ + {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []} + ]} +]), + +{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">example</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], #{ + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>} +})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</span>, + +{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #009900">Name</span>, [], #{ + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>} +}), + +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, +<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>, +<a href="../ranch">ranch(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html b/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html index 47097caf..7b660e07 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:start_tls(3)</title> @@ -67,156 +67,153 @@ <h1 class="lined-header"><span>cowboy:start_tls(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:start_tls - Listen for connections using TLS</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">start_tls</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_ssl:opts</span></span>(),
- <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>())
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Start listening for connections over a secure TLS channel.</p></div>
-<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener.
-The ALPN TLS extension must be used to initiate an HTTP/2
-connection.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The listener name is used to refer to this listener in
-future calls, for example when stopping it or when
-updating the routes defined.
-</p>
-<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough,
-for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div>
-</dd>
-<dt class="hdlist1">
-TransportOpts
-</dt>
-<dd>
-<p>
-The transport options are where the TCP options, including
-the listener’s port number, are defined. They also contain
-the TLS options, like the server’s certificate. Transport options
-are provided as a list of keys and values, for example
-<code>[{port, 8443}, {certfile, "path/to/cert.pem"}]</code>.
-</p>
-<div class="paragraph"><p>The available options are documented in the
-<a href="../ranch_ssl">ranch_ssl(3)</a> manual.</p></div>
-</dd>
-<dt class="hdlist1">
-ProtocolOpts
-</dt>
-<dd>
-<p>
-The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-</p>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual;
-the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>;
-and the Websocket options in
-<a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of
-the top-level supervisor for the listener.</p></div>
-<div class="paragraph"><p>An error tuple is returned on error. The error reason may
-be any Erlang term.</p></div>
-<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port
-configured for Cowboy is already in use.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: HTTP/2 support added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_https/4</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Start a listener</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- {<span style="color: #FF6600">'_'</span>, [
- {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []}
- ]}
-]),
-
-{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_tls</span></span>(<span style="color: #FF6600">example</span>, [
- {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>},
- {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</span>}
-], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}
-})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</span>,
-
-{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_tls</span></span>(<span style="color: #009900">Name</span>, [
- {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</span>}
-], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}
-}),
-
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:start_tls - Listen for connections using TLS</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">start_tls</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), + <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_ssl:opts</span></span>(), + <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>()) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()} + | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Start listening for connections over a secure TLS channel.</p></div> +<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener. +The ALPN TLS extension must be used to initiate an HTTP/2 +connection.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The listener name is used to refer to this listener in +future calls, for example when stopping it or when +updating the routes defined. +</p> +<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough, +for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div> +</dd> +<dt class="hdlist1"> +TransportOpts +</dt> +<dd> +<p> +The transport options are where the TCP options, including +the listener’s port number, are defined. They also contain +the TLS options, like the server’s certificate. Transport options +are provided as a list of keys and values, for example +<code>[{port, 8443}, {certfile, "path/to/cert.pem"}]</code>. +</p> +<div class="paragraph"><p>The available options are documented in the +<a href="../ranch_ssl">ranch_ssl(3)</a> manual.</p></div> +</dd> +<dt class="hdlist1"> +ProtocolOpts +</dt> +<dd> +<p> +The protocol options are in a map containing all the options for +the different protocols that may be involved when connecting +to the listener, including HTTP/1.1 and HTTP/2. +</p> +<div class="paragraph"><p>The HTTP/1.1 options are documented in the +<a href="../cowboy_http">cowboy_http(3)</a> manual; +and the HTTP/2 options in +<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of +the top-level supervisor for the listener.</p></div> +<div class="paragraph"><p>An error tuple is returned on error. The error reason may +be any Erlang term.</p></div> +<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port +configured for Cowboy is already in use.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: HTTP/2 support added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_https/4</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Start a listener</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + {<span style="color: #FF6600">'_'</span>, [ + {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []} + ]} +]), + +{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_tls</span></span>(<span style="color: #FF6600">example</span>, [ + {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>}, + {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</span>} +], #{ + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>} +})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</span>, + +{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_tls</span></span>(<span style="color: #009900">Name</span>, [ + {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</span>} +], #{ + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>} +}), + +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>, +<a href="../ranch">ranch(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html b/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html index 512fc5fa..b3d736f9 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:stop_listener(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy:stop_listener(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:stop_listener - Stop the given listener</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">stop_listener</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>())
- <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_found</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Stop a previously started listener.</p></div>
-<div class="paragraph"><p>Alias of <a href="../ranch.stop_listener">ranch:stop_listener(3)</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The name of the listener to be stopped.
-</p>
-<div class="paragraph"><p>The name of the listener is the first argument given to the
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or
-<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div>
-<div class="paragraph"><p>The <code>{error, not_found}</code> tuple is returned when the listener
-does not exist.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Stop a listener</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:stop_listener</span></span>(<span style="color: #FF6600">example</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../ranch">ranch(3)</a>,
-<a href="../ranch.start_listener">ranch:start_listener(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:stop_listener - Stop the given listener</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">stop_listener</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>()) + <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_found</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Stop a previously started listener.</p></div> +<div class="paragraph"><p>Alias of <a href="../ranch.stop_listener">ranch:stop_listener(3)</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The name of the listener to be stopped. +</p> +<div class="paragraph"><p>The name of the listener is the first argument given to the +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or +<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div> +<div class="paragraph"><p>The <code>{error, not_found}</code> tuple is returned when the listener +does not exist.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Stop a listener</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:stop_listener</span></span>(<span style="color: #FF6600">example</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, +<a href="../ranch">ranch(3)</a>, +<a href="../ranch.start_listener">ranch:start_listener(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy/index.html b/docs/en/cowboy/2.0/manual/cowboy/index.html index 1a2a4d08..8f2bc031 100644 --- a/docs/en/cowboy/2.0/manual/cowboy/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy(3)</title> @@ -67,129 +67,129 @@ <h1 class="lined-header"><span>cowboy(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - HTTP server</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy</code> provides convenience functions for
-manipulating Ranch listeners.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a> - Listen for connections using plain TCP
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> - Listen for connections using TLS
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a> - Stop the given listener
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.set_env">cowboy:set_env(3)</a> - Update a listener’s environment value
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_fields">fields()</h3>
-<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: #000000">fields</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Name</span>
- | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>}
- | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Default</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">Constraints</span> <span style="color: #990000">::</span> <span style="color: #009900">Constraint</span> | [<span style="color: #009900">Constraint</span>]
-<span style="color: #009900">Constraint</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_constraints:constraint</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Fields description for match operations.</p></div>
-<div class="paragraph"><p>This type is used in <a href="../cowboy_router">cowboy_router(3)</a>
-for matching bindings and in the match functions found in
-<a href="../cowboy_req">cowboy_req(3)</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_headers">http_headers()</h3>
-<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: #000000">http_headers</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>HTTP headers.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_status">http_status()</h3>
-<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: #000000">http_status</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>HTTP response status.</p></div>
-<div class="paragraph"><p>A binary status can be used to set a reason phrase. Note
-however that HTTP/2 only sends the status code and drops
-the reason phrase entirely.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_version">http_version()</h3>
-<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: #000000">http_version</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">'HTTP/2'</span> | <span style="color: #FF6600">'HTTP/1.1'</span> | <span style="color: #FF6600">'HTTP/1.0'</span></tt></pre></div></div>
-<div class="paragraph"><p>HTTP version.</p></div>
-<div class="paragraph"><p>Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts">opts()</h3>
-<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: #000000">opts</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Options for the HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2.</p></div>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual
-and the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy - HTTP server</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy</code> provides convenience functions for +manipulating Ranch listeners.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a> - Listen for connections using plain TCP +</p> +</li> +<li> +<p> +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> - Listen for connections using TLS +</p> +</li> +<li> +<p> +<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a> - Stop the given listener +</p> +</li> +<li> +<p> +<a href="../cowboy.set_env">cowboy:set_env(3)</a> - Update a listener’s environment value +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_fields">fields()</h3> +<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: #000000">fields</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Name</span> + | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>} + | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Default</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">Constraints</span> <span style="color: #990000">::</span> <span style="color: #009900">Constraint</span> | [<span style="color: #009900">Constraint</span>] +<span style="color: #009900">Constraint</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_constraints:constraint</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Fields description for match operations.</p></div> +<div class="paragraph"><p>This type is used in <a href="../cowboy_router">cowboy_router(3)</a> +for matching bindings and in the match functions found in +<a href="../cowboy_req">cowboy_req(3)</a>.</p></div> +</div> +<div class="sect2"> +<h3 id="_http_headers">http_headers()</h3> +<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: #000000">http_headers</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>HTTP headers.</p></div> +</div> +<div class="sect2"> +<h3 id="_http_status">http_status()</h3> +<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: #000000">http_status</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>HTTP response status.</p></div> +<div class="paragraph"><p>A binary status can be used to set a reason phrase. Note +however that HTTP/2 only sends the status code and drops +the reason phrase entirely.</p></div> +</div> +<div class="sect2"> +<h3 id="_http_version">http_version()</h3> +<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: #000000">http_version</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">'HTTP/2'</span> | <span style="color: #FF6600">'HTTP/1.1'</span> | <span style="color: #FF6600">'HTTP/1.0'</span></tt></pre></div></div> +<div class="paragraph"><p>HTTP version.</p></div> +<div class="paragraph"><p>Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts">opts()</h3> +<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: #000000">opts</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Options for the HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> +<div class="paragraph"><p>The protocol options are in a map containing all the options for +the different protocols that may be involved when connecting +to the listener, including HTTP/1.1 and HTTP/2.</p></div> +<div class="paragraph"><p>The HTTP/1.1 options are documented in the +<a href="../cowboy_http">cowboy_http(3)</a> manual +and the HTTP/2 options in +<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../ranch">ranch(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_app/index.html b/docs/en/cowboy/2.0/manual/cowboy_app/index.html index 689915a5..0c92cf86 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_app/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy(7)</title> @@ -67,166 +67,171 @@ <h1 class="lined-header"><span>cowboy(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the
-HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes
-the implementation of the HTTP RFCs but also any directly
-related standards, like Websocket or Server-Sent Events.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_modules">Modules</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Functions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy">cowboy(3)</a> - Listener management
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req">cowboy_req(3)</a> - Request and response
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_router">cowboy_router(3)</a> - Router
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_http">cowboy_http(3)</a> - HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_http2">cowboy_http2(3)</a> - HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Handlers:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_static">cowboy_static(3)</a> - Static file handler
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Behaviors:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_loop">cowboy_loop(3)</a> - Loop handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_middleware">cowboy_middleware(3)</a> - Middlewares
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Middlewares:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_router">cowboy_router(3)</a> - Router middleware
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_handler">cowboy_handler(3)</a> - Handler middleware
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../ranch">ranch(7)</a> - Socket acceptor pool for TCP protocols
-</p>
-</li>
-<li>
-<p>
-<a href="../cowlib">cowlib(7)</a> - Support library for manipulating Web protocols
-</p>
-</li>
-<li>
-<p>
-ssl - Secure communication over sockets
-</p>
-</li>
-<li>
-<p>
-crypto - Crypto functions
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code>
-application. To start Cowboy and all dependencies at once:</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="color: #FF6600">ok</span>, <span style="color: #990000">_</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">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../ranch">ranch(7)</a>,
-<a href="../cowlib">cowlib(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the +HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> +<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes +the implementation of the HTTP RFCs but also any directly +related standards, like Websocket or Server-Sent Events.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_modules">Modules</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Functions:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy">cowboy(3)</a> - Listener management +</p> +</li> +<li> +<p> +<a href="../cowboy_req">cowboy_req(3)</a> - Request and response +</p> +</li> +<li> +<p> +<a href="../cowboy_router">cowboy_router(3)</a> - Router +</p> +</li> +<li> +<p> +<a href="../cowboy_constraints">cowboy_constraints(3)</a> - Constraints +</p> +</li> +</ul></div> +<div class="paragraph"><p>Protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_http">cowboy_http(3)</a> - HTTP/1.1 +</p> +</li> +<li> +<p> +<a href="../cowboy_http2">cowboy_http2(3)</a> - HTTP/2 +</p> +</li> +<li> +<p> +<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket +</p> +</li> +</ul></div> +<div class="paragraph"><p>Handlers:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_static">cowboy_static(3)</a> - Static file handler +</p> +</li> +</ul></div> +<div class="paragraph"><p>Behaviors:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_loop">cowboy_loop(3)</a> - Loop handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_middleware">cowboy_middleware(3)</a> - Middlewares +</p> +</li> +<li> +<p> +<a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers +</p> +</li> +</ul></div> +<div class="paragraph"><p>Middlewares:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_router">cowboy_router(3)</a> - Router middleware +</p> +</li> +<li> +<p> +<a href="../cowboy_handler">cowboy_handler(3)</a> - Handler middleware +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="../ranch">ranch(7)</a> - Socket acceptor pool for TCP protocols +</p> +</li> +<li> +<p> +<a href="../cowlib">cowlib(7)</a> - Support library for manipulating Web protocols +</p> +</li> +<li> +<p> +ssl - Secure communication over sockets +</p> +</li> +<li> +<p> +crypto - Crypto functions +</p> +</li> +</ul></div> +<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code> +application. To start Cowboy and all dependencies at once:</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="color: #FF6600">ok</span>, <span style="color: #990000">_</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">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy</code> application does not define any application +environment configuration parameters.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../ranch">ranch(7)</a>, +<a href="../cowlib">cowlib(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_constraints.int/index.html b/docs/en/cowboy/2.0/manual/cowboy_constraints.int/index.html new file mode 100644 index 00000000..70c8969e --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_constraints.int/index.html @@ -0,0 +1,225 @@ +<!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.26" /> + + <title>Nine Nines: cowboy_constraints:int(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>cowboy_constraints:int(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_constraints:int - Integer constraint</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Constraint functions implement a number of different operations.</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: #000000">int</span></span>(<span style="color: #FF6600">forward</span>, <span style="color: #009900">Bin</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Int</span>} | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>} + +<span style="color: #009900">Bin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Int</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Validate and convert the text representation of an integer.</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: #000000">int</span></span>(<span style="color: #FF6600">reverse</span>, <span style="color: #009900">Int</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}</tt></pre></div></div> +<div class="paragraph"><p>Convert an integer back to its text representation.</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: #000000">int</span></span>(<span style="color: #FF6600">format_error</span>, <span style="color: #009900">Error</span>) <span style="color: #990000">-></span> <span style="color: #009900">HumanReadable</span> + +<span style="color: #009900">Error</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">not_an_integer</span>, <span style="color: #009900">Bin</span> | <span style="color: #009900">Int</span>} +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iolist</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Generate a human-readable error message.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Arguments vary depending on the operation. Constraint +functions always take the operation type as first argument, +and the value as second argument.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The return value varies depending on the operation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Interface modified to allow for a variety of operations. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Constraint introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This function is not meant to be called directly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_constraints">cowboy_constraints(3)</a>, +<a href="../cowboy_constraints.nonempty">cowboy_constraints:nonempty(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/cowboy/2.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/cowboy/2.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/cowboy/2.0/manual">2.0</a></li> + + <li><a href="/docs/en/cowboy/1.0/manual">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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/index.html b/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/index.html new file mode 100644 index 00000000..b833f1b1 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/index.html @@ -0,0 +1,224 @@ +<!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.26" /> + + <title>Nine Nines: cowboy_constraints:nonempty(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>cowboy_constraints:nonempty(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_constraints:nonempty - Non-empty constraint</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Constraint functions implement a number of different operations.</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: #000000">nonempty</span></span>(<span style="color: #FF6600">forward</span> | <span style="color: #FF6600">reverse</span>, <span style="color: #990000"><<>></span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">empty</span>}</tt></pre></div></div> +<div class="paragraph"><p>Reject empty values.</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: #000000">nonempty</span></span>(<span style="color: #FF6600">forward</span> | <span style="color: #FF6600">reverse</span>, <span style="color: #009900">Bin</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} + +<span style="color: #009900">Bin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Accept any other binary values.</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: #000000">nonempty</span></span>(<span style="color: #FF6600">format_error</span>, <span style="color: #009900">Error</span>) <span style="color: #990000">-></span> <span style="color: #009900">HumanReadable</span> + +<span style="color: #009900">Error</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">empty</span>, <span style="color: #009900">Bin</span>} +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iolist</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Generate a human-readable error message.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Arguments vary depending on the operation. Constraint +functions always take the operation type as first argument, +and the value as second argument.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The return value varies depending on the operation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Interface modified to allow for a variety of operations. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Constraint introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This function is not meant to be called directly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_constraints">cowboy_constraints(3)</a>, +<a href="../cowboy_constraints.int">cowboy_constraints:int(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/cowboy/2.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/cowboy/2.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/cowboy/2.0/manual">2.0</a></li> + + <li><a href="/docs/en/cowboy/1.0/manual">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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_constraints/index.html b/docs/en/cowboy/2.0/manual/cowboy_constraints/index.html new file mode 100644 index 00000000..ae5340eb --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_constraints/index.html @@ -0,0 +1,217 @@ +<!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.26" /> + + <title>Nine Nines: cowboy_constraints(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>cowboy_constraints(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_constraints - Constraints</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_constraints</code> defines the built-in +constraints in Cowboy and provides an interface for +manipulating these constraints.</p></div> +<div class="paragraph"><p>Constraints are functions that define what type of +input is allowed. They are used throughout Cowboy, +from the router to query strings to cookies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Built-in constraints:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_constraints.int">cowboy_constraints:int(3)</a> - Integer constraint +</p> +</li> +<li> +<p> +<a href="../cowboy_constraints.nonempty">cowboy_constraints:nonempty(3)</a> - Non-empty constraint +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_constraint">constraint()</h3> +<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: #000000">constraint</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">int</span> | <span style="color: #FF6600">nonempty</span> | <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>A constraint function.</p></div> +<div class="paragraph"><p>The atom constraints are built-in, see the corresponding +function in the exports list above.</p></div> +</div> +<div class="sect2"> +<h3 id="_reason">reason()</h3> +<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: #000000">reason</span></span>() <span style="color: #990000">::</span> {<span style="font-weight: bold"><span style="color: #000000">constraint</span></span>(), <span style="color: #009900">Reason</span>, <span style="color: #009900">Value</span>} + +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Reason for the constraint failure.</p></div> +<div class="paragraph"><p>It includes the constraint function in question, +a machine-readable error reason and the value that +made the constraint fail.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/cowboy/2.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/cowboy/2.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/cowboy/2.0/manual">2.0</a></li> + + <li><a href="/docs/en/cowboy/1.0/manual">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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html index ab3155ae..c12945ed 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_handler:terminate(3)</title> @@ -67,109 +67,109 @@ <h1 class="lined-header"><span>cowboy_handler:terminate(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_handler:terminate - Terminate the handler</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span> | <span style="color: #000080">undefined</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span>
-
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Call the optional terminate callback if it is defined.</p></div>
-<div class="paragraph"><p>Make sure to use this function at the end of the execution
-of modules that implement custom handler behaviors.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Reason
-</dt>
-<dd>
-<p>
-Reason for termination.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-<div class="paragraph"><p>It is possible to pass <code>undefined</code> if the handler has no concept
-of requests/responses and discarded the Req object before calling
-this function.</p></div>
-</dd>
-<dt class="hdlist1">
-State
-</dt>
-<dd>
-<p>
-Handler state.
-</p>
-</dd>
-<dt class="hdlist1">
-Handler
-</dt>
-<dd>
-<p>
-Handler module.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Terminate a handler normally</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">cowboy_handler:terminate</span></span>(<span style="font-weight: bold"><span style="color: #000080">normal</span></span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_handler">cowboy_handler(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_handler:terminate - Terminate the handler</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">PartialReq</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> + +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">PartialReq</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Call the optional terminate callback if it is defined.</p></div> +<div class="paragraph"><p>Make sure to use this function at the end of the execution +of modules that implement custom handler behaviors.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Reason +</dt> +<dd> +<p> +Reason for termination. +</p> +</dd> +<dt class="hdlist1"> +PartialReq +</dt> +<dd> +<p> +The Req object. +</p> +<div class="paragraph"><p>It is possible to remove fields from the Req object to save memory +when the handler has no concept of requests/responses. The only +requirement is that a map is provided.</p></div> +</dd> +<dt class="hdlist1"> +State +</dt> +<dd> +<p> +Handler state. +</p> +</dd> +<dt class="hdlist1"> +Handler +</dt> +<dd> +<p> +Handler module. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Terminate a handler normally</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">cowboy_handler:terminate</span></span>(<span style="font-weight: bold"><span style="color: #000080">normal</span></span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_handler">cowboy_handler(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html index 0c34537c..6c60377a 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_handler(3)</title> @@ -67,96 +67,96 @@ <h1 class="lined-header"><span>cowboy_handler(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_handler - Plain HTTP handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_handler</code> middleware executes the handler selected
-by the router or any other preceding middleware.</p></div>
-<div class="paragraph"><p>This middleware takes the handler module and initial state
-from the <code>handler</code> and <code>handler_opts</code> environment values,
-respectively. On completion, it adds a <code>result</code> value to
-the middleware environment, containing the return value
-of the <code>terminate/3</code> callback (if defined) and <code>ok</code> otherwise.</p></div>
-<div class="paragraph"><p>This module also defines a callback interface for handling
-HTTP requests.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Plain HTTP handlers implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>These two callbacks are common to all handlers.</p></div>
-<div class="paragraph"><p>Plain HTTP handlers do all their work in the <code>init/2</code>
-callback. Returning <code>ok</code> terminates the handler. If no
-response is sent, Cowboy will send a <code>204 No Content</code>.</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the handler.
-Cowboy will terminate the process right after this. There
-is no need to perform any cleanup in this callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for plain HTTP
-handlers:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-normal
-</dt>
-<dd>
-<p>
- The connection was closed normally.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following function should be called by modules implementing
-custom handlers to execute the optional terminate callback:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_handler.terminate">cowboy_handler:terminate(3)</a> - Terminate the handler
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_handler - Plain HTTP handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy_handler</code> middleware executes the handler selected +by the router or any other preceding middleware.</p></div> +<div class="paragraph"><p>This middleware takes the handler module and initial state +from the <code>handler</code> and <code>handler_opts</code> environment values, +respectively. On completion, it adds a <code>result</code> value to +the middleware environment, containing the return value +of the <code>terminate/3</code> callback (if defined) and <code>ok</code> otherwise.</p></div> +<div class="paragraph"><p>This module also defines a callback interface for handling +HTTP requests.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Plain HTTP handlers implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>These two callbacks are common to all handlers.</p></div> +<div class="paragraph"><p>Plain HTTP handlers do all their work in the <code>init/2</code> +callback. Returning <code>ok</code> terminates the handler. If no +response is sent, Cowboy will send a <code>204 No Content</code>.</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for plain HTTP +handlers:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +normal +</dt> +<dd> +<p> + The connection was closed normally. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The following function should be called by modules implementing +custom handlers to execute the optional terminate callback:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_handler.terminate">cowboy_handler:terminate(3)</a> - Terminate the handler +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_http/index.html b/docs/en/cowboy/2.0/manual/cowboy_http/index.html index 5fd3cecf..414880a1 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_http/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_http/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_http(3)</title> @@ -67,240 +67,240 @@ <h1 class="lined-header"><span>cowboy_http(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_http - HTTP/1.1</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_http</code> implements HTTP/1.1 and HTTP/1.0
-as a Ranch protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options">Options</h2>
-<div class="sectionbody">
-<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: #000000">opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>,
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(),
- <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">max_empty_lines</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_header_name_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_header_value_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_keepalive</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_method_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_request_line_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()],
- <span style="color: #0000FF">request_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()]
-}</tt></pre></div></div>
-<div class="paragraph"><p>Configuration for the HTTP/1.1 protocol.</p></div>
-<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners
-using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div>
-<div class="paragraph"><p>It can be updated without restarting listeners using the
-Ranch functions <code>ranch:get_protocol_options/1</code> and
-<code>ranch:set_protocol_options/2</code>.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-connection_type (supervisor)
-</dt>
-<dd>
-<p>
- Whether the connection process also acts as a supervisor.
-</p>
-</dd>
-<dt class="hdlist1">
-env (#{})
-</dt>
-<dd>
-<p>
- Middleware environment.
-</p>
-</dd>
-<dt class="hdlist1">
-idle_timeout (60000)
-</dt>
-<dd>
-<p>
- Time in ms with no data received before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-inactivity_timeout (300000)
-</dt>
-<dd>
-<p>
- Time in ms with nothing received at all before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_empty_lines (5)
-</dt>
-<dd>
-<p>
- Maximum number of empty lines before a request.
-</p>
-</dd>
-<dt class="hdlist1">
-max_header_name_length (64)
-</dt>
-<dd>
-<p>
- Maximum length of header names.
-</p>
-</dd>
-<dt class="hdlist1">
-max_header_value_length (4096)
-</dt>
-<dd>
-<p>
- Maximum length of header values.
-</p>
-</dd>
-<dt class="hdlist1">
-max_headers (100)
-</dt>
-<dd>
-<p>
- Maximum number of headers allowed per request.
-</p>
-</dd>
-<dt class="hdlist1">
-max_keepalive (100)
-</dt>
-<dd>
-<p>
- Maximum number of requests allowed per connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_method_length (32)
-</dt>
-<dd>
-<p>
- Maximum length of the method.
-</p>
-</dd>
-<dt class="hdlist1">
-max_request_line_length (8000)
-</dt>
-<dd>
-<p>
- Maximum length of the request line.
-</p>
-</dd>
-<dt class="hdlist1">
-middlewares ([cowboy_router, cowboy_handler])
-</dt>
-<dd>
-<p>
- Middlewares to run for every request.
-</p>
-</dd>
-<dt class="hdlist1">
-request_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms with no requests before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms Cowboy will wait for child processes to shut down before killing them.
-</p>
-</dd>
-<dt class="hdlist1">
-stream_handlers ([cowboy_stream_h])
-</dt>
-<dd>
-<p>
- Ordered list of stream handlers that will handle all stream events.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The <code>timeout</code> option was renamed <code>request_timeout</code>.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>idle_timeout</code>, <code>inactivity_timeout</code> and <code>shutdown_timeout</code> options were added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>max_method_length</code> option was added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>max_request_line_length</code> default was increased from 4096 to 8000.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>connection_type</code> option was added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>env</code> option is now a map instead of a proplist.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>stream_handlers</code> option was added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>compress</code> option was removed in favor of the <code>cowboy_compress_h</code> stream handler.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Options are now a map instead of a proplist.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Protocol introduced. Replaces <code>cowboy_protocol</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_http2">cowboy_http2(3)</a>,
-<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_http - HTTP/1.1</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_http</code> implements HTTP/1.1 and HTTP/1.0 +as a Ranch protocol.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options">Options</h2> +<div class="sectionbody"> +<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: #000000">opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>, + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(), + <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">max_empty_lines</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_header_name_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_header_value_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_keepalive</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_method_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_request_line_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()], + <span style="color: #0000FF">request_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()] +}</tt></pre></div></div> +<div class="paragraph"><p>Configuration for the HTTP/1.1 protocol.</p></div> +<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners +using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div> +<div class="paragraph"><p>It can be updated without restarting listeners using the +Ranch functions <code>ranch:get_protocol_options/1</code> and +<code>ranch:set_protocol_options/2</code>.</p></div> +<div class="paragraph"><p>The default value is given next to the option name:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +connection_type (supervisor) +</dt> +<dd> +<p> + Whether the connection process also acts as a supervisor. +</p> +</dd> +<dt class="hdlist1"> +env (#{}) +</dt> +<dd> +<p> + Middleware environment. +</p> +</dd> +<dt class="hdlist1"> +idle_timeout (60000) +</dt> +<dd> +<p> + Time in ms with no data received before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +inactivity_timeout (300000) +</dt> +<dd> +<p> + Time in ms with nothing received at all before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +max_empty_lines (5) +</dt> +<dd> +<p> + Maximum number of empty lines before a request. +</p> +</dd> +<dt class="hdlist1"> +max_header_name_length (64) +</dt> +<dd> +<p> + Maximum length of header names. +</p> +</dd> +<dt class="hdlist1"> +max_header_value_length (4096) +</dt> +<dd> +<p> + Maximum length of header values. +</p> +</dd> +<dt class="hdlist1"> +max_headers (100) +</dt> +<dd> +<p> + Maximum number of headers allowed per request. +</p> +</dd> +<dt class="hdlist1"> +max_keepalive (100) +</dt> +<dd> +<p> + Maximum number of requests allowed per connection. +</p> +</dd> +<dt class="hdlist1"> +max_method_length (32) +</dt> +<dd> +<p> + Maximum length of the method. +</p> +</dd> +<dt class="hdlist1"> +max_request_line_length (8000) +</dt> +<dd> +<p> + Maximum length of the request line. +</p> +</dd> +<dt class="hdlist1"> +middlewares ([cowboy_router, cowboy_handler]) +</dt> +<dd> +<p> + Middlewares to run for every request. +</p> +</dd> +<dt class="hdlist1"> +request_timeout (5000) +</dt> +<dd> +<p> + Time in ms with no requests before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +shutdown_timeout (5000) +</dt> +<dd> +<p> + Time in ms Cowboy will wait for child processes to shut down before killing them. +</p> +</dd> +<dt class="hdlist1"> +stream_handlers ([cowboy_stream_h]) +</dt> +<dd> +<p> + Ordered list of stream handlers that will handle all stream events. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The <code>timeout</code> option was renamed <code>request_timeout</code>. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>idle_timeout</code>, <code>inactivity_timeout</code> and <code>shutdown_timeout</code> options were added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>max_method_length</code> option was added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>max_request_line_length</code> default was increased from 4096 to 8000. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>connection_type</code> option was added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>env</code> option is now a map instead of a proplist. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>stream_handlers</code> option was added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>compress</code> option was removed in favor of the <code>cowboy_compress_h</code> stream handler. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Options are now a map instead of a proplist. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Protocol introduced. Replaces <code>cowboy_protocol</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_http2">cowboy_http2(3)</a>, +<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_http2/index.html b/docs/en/cowboy/2.0/manual/cowboy_http2/index.html index ae0b7103..cac697fa 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_http2/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_http2/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_http2(3)</title> @@ -67,123 +67,123 @@ <h1 class="lined-header"><span>cowboy_http2(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_http2 - HTTP/2</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_http2</code> implements HTTP/2
-as a Ranch protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options">Options</h2>
-<div class="sectionbody">
-<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: #000000">opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>,
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(),
- <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()],
- <span style="color: #0000FF">preface_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()]
-}</tt></pre></div></div>
-<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div>
-<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners
-using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div>
-<div class="paragraph"><p>It can be updated without restarting listeners using the
-Ranch functions <code>ranch:get_protocol_options/1</code> and
-<code>ranch:set_protocol_options/2</code>.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-connection_type (supervisor)
-</dt>
-<dd>
-<p>
- Whether the connection process also acts as a supervisor.
-</p>
-</dd>
-<dt class="hdlist1">
-env (#{})
-</dt>
-<dd>
-<p>
- Middleware environment.
-</p>
-</dd>
-<dt class="hdlist1">
-inactivity_timeout (300000)
-</dt>
-<dd>
-<p>
- Time in ms with nothing received at all before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-middlewares ([cowboy_router, cowboy_handler])
-</dt>
-<dd>
-<p>
- Middlewares to run for every request.
-</p>
-</dd>
-<dt class="hdlist1">
-preface_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms Cowboy is willing to wait for the connection preface.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms Cowboy will wait for child processes to shut down before killing them.
-</p>
-</dd>
-<dt class="hdlist1">
-stream_handlers ([cowboy_stream_h])
-</dt>
-<dd>
-<p>
- Ordered list of stream handlers that will handle all stream events.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Protocol introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_http">cowboy_http(3)</a>,
-<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_http2 - HTTP/2</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_http2</code> implements HTTP/2 +as a Ranch protocol.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options">Options</h2> +<div class="sectionbody"> +<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: #000000">opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>, + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(), + <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()], + <span style="color: #0000FF">preface_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()] +}</tt></pre></div></div> +<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div> +<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners +using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div> +<div class="paragraph"><p>It can be updated without restarting listeners using the +Ranch functions <code>ranch:get_protocol_options/1</code> and +<code>ranch:set_protocol_options/2</code>.</p></div> +<div class="paragraph"><p>The default value is given next to the option name:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +connection_type (supervisor) +</dt> +<dd> +<p> + Whether the connection process also acts as a supervisor. +</p> +</dd> +<dt class="hdlist1"> +env (#{}) +</dt> +<dd> +<p> + Middleware environment. +</p> +</dd> +<dt class="hdlist1"> +inactivity_timeout (300000) +</dt> +<dd> +<p> + Time in ms with nothing received at all before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +middlewares ([cowboy_router, cowboy_handler]) +</dt> +<dd> +<p> + Middlewares to run for every request. +</p> +</dd> +<dt class="hdlist1"> +preface_timeout (5000) +</dt> +<dd> +<p> + Time in ms Cowboy is willing to wait for the connection preface. +</p> +</dd> +<dt class="hdlist1"> +shutdown_timeout (5000) +</dt> +<dd> +<p> + Time in ms Cowboy will wait for child processes to shut down before killing them. +</p> +</dd> +<dt class="hdlist1"> +stream_handlers ([cowboy_stream_h]) +</dt> +<dd> +<p> + Ordered list of stream handlers that will handle all stream events. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Protocol introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_http">cowboy_http(3)</a>, +<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html index b547cfe7..a1f0a289 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_loop(3)</title> @@ -67,120 +67,120 @@ <h1 class="lined-header"><span>cowboy_loop(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_loop - Loop handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_loop</code> defines a callback interface for
-long running HTTP connections.</p></div>
-<div class="paragraph"><p>You should switch to this behavior for long polling,
-server-sent events and similar long-running requests.</p></div>
-<div class="paragraph"><p>There are generally two usage patterns:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Loop until receiving a specific message, then send
- a response and stop execution (for example long polling);
-</p>
-</li>
-<li>
-<p>
-Or initiate a response in <code>init/2</code> and stream the
- body in <code>info/3</code> as necessary (for example server-sent events).
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Loop handlers implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
-
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="color: #FF6600">stop</span>
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch
-to the loop behavior, it must return <code>cowboy_loop</code> as the
-first element of the tuple.</p></div>
-<div class="paragraph"><p>The <code>info/3</code> callback will be called for every Erlang message
-received. It may choose to continue the receive loop or stop
-it.</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the handler.
-Cowboy will terminate the process right after this. There
-is no need to perform any cleanup in this callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-stop
-</dt>
-<dd>
-<p>
- The handler requested to close the connection by returning
- a <code>stop</code> tuple.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Loop handlers no longer need to handle overflow/timeouts.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Behavior introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_handler">cowboy_handler(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_loop - Loop handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_loop</code> defines a callback interface for +long running HTTP connections.</p></div> +<div class="paragraph"><p>You should switch to this behavior for long polling, +server-sent events and similar long-running requests.</p></div> +<div class="paragraph"><p>There are generally two usage patterns:</p></div> +<div class="ulist"><ul> +<li> +<p> +Loop until receiving a specific message, then send + a response and stop execution (for example long polling); +</p> +</li> +<li> +<p> +Or initiate a response in <code>init/2</code> and stream the + body in <code>info/3</code> as necessary (for example server-sent events). +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Loop handlers implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>} + +<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>} + | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="color: #FF6600">stop</span> + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch +to the loop behavior, it must return <code>cowboy_loop</code> as the +first element of the tuple.</p></div> +<div class="paragraph"><p>The <code>info/3</code> callback will be called for every Erlang message +received. It may choose to continue the receive loop or stop +it.</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +stop +</dt> +<dd> +<p> + The handler requested to close the connection by returning + a <code>stop</code> tuple. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Loop handlers no longer need to handle overflow/timeouts. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Behavior introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_handler">cowboy_handler(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html index 2324a945..dbf5b412 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_middleware(3)</title> @@ -67,115 +67,115 @@ <h1 class="lined-header"><span>cowboy_middleware(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_middleware - Middlewares</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_middleware</code> defines a callback interface for
-Cowboy middlewares.</p></div>
-<div class="paragraph"><p>Middlewares process the request sequentially in the order they
-are configured.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Middlewares implement the following interface:</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: #000000">execute</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>}
- | {<span style="color: #FF6600">suspend</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), [<span style="font-weight: bold"><span style="color: #000000">any</span></span>()]}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Env</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>The <code>execute/2</code> is the only callback that needs to be
-implemented. It must execute the middleware and return
-with instructions for Cowboy.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ok
-</dt>
-<dd>
-<p>
-Cowboy should continue processing the request using the
-returned Req object and environment.
-</p>
-</dd>
-<dt class="hdlist1">
-suspend
-</dt>
-<dd>
-<p>
-Cowboy will hibernate the process. When resuming, Cowboy
-will apply the returned module, function and arguments.
-</p>
-</dd>
-<dt class="hdlist1">
-stop
-</dt>
-<dd>
-<p>
-Cowboy will stop middleware execution. No other middleware
-will be executed. This effectively ends the processing of
-the request.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_env">env()</h3>
-<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: #000000">env</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Middleware environment.</p></div>
-<div class="paragraph"><p>A new environment is created for every request. The initial
-environment contained the user configured environment values
-(like <code>dispatch</code> for example) plus the <code>listener</code> value which
-contains the name of the listener for this connection.</p></div>
-<div class="paragraph"><p>Middlewares may modify the environment as necessary.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The <code>env</code> type is now a map instead of a proplist.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Behavior introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_middleware - Middlewares</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_middleware</code> defines a callback interface for +Cowboy middlewares.</p></div> +<div class="paragraph"><p>Middlewares process the request sequentially in the order they +are configured.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Middlewares implement the following interface:</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: #000000">execute</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>} + | {<span style="color: #FF6600">suspend</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), [<span style="font-weight: bold"><span style="color: #000000">any</span></span>()]} + | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>} + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Env</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>The <code>execute/2</code> is the only callback that needs to be +implemented. It must execute the middleware and return +with instructions for Cowboy.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +ok +</dt> +<dd> +<p> +Cowboy should continue processing the request using the +returned Req object and environment. +</p> +</dd> +<dt class="hdlist1"> +suspend +</dt> +<dd> +<p> +Cowboy will hibernate the process. When resuming, Cowboy +will apply the returned module, function and arguments. +</p> +</dd> +<dt class="hdlist1"> +stop +</dt> +<dd> +<p> +Cowboy will stop middleware execution. No other middleware +will be executed. This effectively ends the processing of +the request. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_env">env()</h3> +<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: #000000">env</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Middleware environment.</p></div> +<div class="paragraph"><p>A new environment is created for every request. The initial +environment contained the user configured environment values +(like <code>dispatch</code> for example) plus the <code>listener</code> value which +contains the name of the listener for this connection.</p></div> +<div class="paragraph"><p>Middlewares may modify the environment as necessary.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The <code>env</code> type is now a map instead of a proplist. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Behavior introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html index 27bf3764..94112847 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:binding(3)</title> @@ -67,116 +67,116 @@ <h1 class="lined-header"><span>cowboy_req:binding(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:binding - Access a value bound from the route</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>)
-<span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the value for the given binding.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired binding name as an atom.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the binding is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default the value is a case sensitive binary string, however
-constraints may change the type of this value (for example
-automatically converting numbers to integer).</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the username from the path</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-style: italic"><span style="color: #9A1900">%% Route is "/users/:user"</span></span>
-<span style="color: #009900">Username</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">user</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get the branch name, with a default</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-style: italic"><span style="color: #9A1900">%% Route is "/log[/:branch]"</span></span>
-<span style="color: #009900">Branch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">branch</span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"master"</span><span style="color: #990000">>></span>)</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:binding - Access a value bound from the route</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>) +<span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the value for the given binding.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired binding name as an atom. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the binding is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the value is a case sensitive binary string, however +constraints may change the type of this value (for example +automatically converting numbers to integer).</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the username from the path</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-style: italic"><span style="color: #9A1900">%% Route is "/users/:user"</span></span> +<span style="color: #009900">Username</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">user</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get the branch name, with a default</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-style: italic"><span style="color: #9A1900">%% Route is "/log[/:branch]"</span></span> +<span style="color: #009900">Branch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">branch</span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"master"</span><span style="color: #990000">>></span>)</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html index 256f0491..29c994f8 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:bindings(3)</title> @@ -67,86 +67,86 @@ <h1 class="lined-header"><span>cowboy_req:bindings(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:bindings - Access all values bound from the route</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">bindings</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:bindings</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return a map containing all bindings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default values are case sensitive binary strings, however
-constraints may change the type of this value (for example
-automatically converting numbers to integer).</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the values are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get all bindings</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">Bindings</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:bindings</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:bindings - Access all values bound from the route</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">bindings</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:bindings</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return a map containing all bindings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default values are case sensitive binary strings, however +constraints may change the type of this value (for example +automatically converting numbers to integer).</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the values are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get all bindings</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">Bindings</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:bindings</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html index bd772ac0..3a360235 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:body_length(3)</title> @@ -67,89 +67,89 @@ <h1 class="lined-header"><span>cowboy_req:body_length(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:body_length - Body length</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">body_length</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #000080">undefined</span> | <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the length of the request body.</p></div>
-<div class="paragraph"><p>The length is not always known before reading the body.
-In those cases Cowboy will return <code>undefined</code>. The body
-length is available after the body has been fully read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The length of the request body, or <code>undefined</code> if it is
-not known.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the length is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the body length</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">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_length</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:body_length - Body length</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">body_length</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #000080">undefined</span> | <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the length of the request body.</p></div> +<div class="paragraph"><p>The length is not always known before reading the body. +In those cases Cowboy will return <code>undefined</code>. The body +length is available after the body has been fully read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The length of the request body, or <code>undefined</code> if it is +not known.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the length is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the body length</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">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_length</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html index 1418de55..09e4f66f 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:delete_resp_header(3)</title> @@ -67,95 +67,95 @@ <h1 class="lined-header"><span>cowboy_req:delete_resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:delete_resp_header - Delete a response header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">delete_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Delete the given response header.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the header will still be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Remove the content-type header from the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:delete_resp_header - Delete a response header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">delete_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>Delete the given response header.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the header will still be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Remove the content-type header from the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html index 3935024c..3a8d97ce 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:has_body(3)</title> @@ -67,80 +67,80 @@ <h1 class="lined-header"><span>cowboy_req:has_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:has_body - Is there a request body?</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">has_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return whether the request has a body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A boolean indicating whether the request has a body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Ensure the request has a 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: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:has_body - Is there a request body?</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">has_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return whether the request has a body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A boolean indicating whether the request has a body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Ensure the request has a 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: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html index 7391037c..9d6b92fe 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:has_resp_body(3)</title> @@ -67,82 +67,82 @@ <h1 class="lined-header"><span>cowboy_req:has_resp_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:has_resp_body - Is there a response body?</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">has_resp_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return whether a response body has been set.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A boolean indicating whether a response body has been set.</p></div>
-<div class="paragraph"><p>This function will return <code>false</code> when an empty response
-body has been set.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Check whether a body has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req0</span>),
-<span style="color: #009900">Req1</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
-<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req1</span>),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req1</span>),
-<span style="color: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:has_resp_body - Is there a response body?</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">has_resp_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return whether a response body has been set.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A boolean indicating whether a response body has been set.</p></div> +<div class="paragraph"><p>This function will return <code>false</code> when an empty response +body has been set.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Check whether a body has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req0</span>), +<span style="color: #009900">Req1</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), +<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req1</span>), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req1</span>), +<span style="color: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html index 4fabcde4..1fc629eb 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:has_resp_header(3)</title> @@ -67,95 +67,95 @@ <h1 class="lined-header"><span>cowboy_req:has_resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:has_resp_header - Is the given response header set?</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">has_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the given response header has been set.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A boolean indicating whether the given response header has been set.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Check whether the content-type header has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
-<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:has_resp_header - Is the given response header set?</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">has_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the given response header has been set.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A boolean indicating whether the given response header has been set.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Check whether the content-type header has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), +<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html index 5a508ba4..4680b487 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:header(3)</title> @@ -67,122 +67,122 @@ <h1 class="lined-header"><span>cowboy_req:header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:header - HTTP header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>)
-<span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the value for the given HTTP header.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Headers can also be obtained using pattern matching:</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="color: #FF6600">headers</span> <span style="color: #990000">:=</span> #{<span style="color: #009900">Name</span> <span style="color: #990000">:=</span> <span style="color: #009900">Value</span>}} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that this snippet will crash if the header is missing.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired HTTP header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the header is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The header value is returned as a binary string. When the
-header is missing, the default argument is returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the header value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the accept header</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">Accept</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get the content-length header with a default value</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">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"0"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.headers">cowboy_req:headers(3)</a>,
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:header - HTTP header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>) +<span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the value for the given HTTP header.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Headers can also be obtained using pattern matching:</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="color: #FF6600">headers</span> <span style="color: #990000">:=</span> #{<span style="color: #009900">Name</span> <span style="color: #990000">:=</span> <span style="color: #009900">Value</span>}} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that this snippet will crash if the header is missing.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired HTTP header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the header is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The header value is returned as a binary string. When the +header is missing, the default argument is returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the header value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the accept header</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">Accept</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get the content-length header with a default value</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">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"0"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.headers">cowboy_req:headers(3)</a>, +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html index 61d71c81..28fc85cf 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:headers(3)</title> @@ -67,90 +67,90 @@ <h1 class="lined-header"><span>cowboy_req:headers(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:headers - HTTP headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return all request headers.</p></div>
-<div class="paragraph"><p>Request headers can also be obtained using pattern matching:</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="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="color: #009900">Headers</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Headers are returned as a map with keys being lowercase
-binary strings, and values as binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the headers are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get all 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">Headers</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.header">cowboy_req:header(3)</a>,
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:headers - HTTP headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return all request headers.</p></div> +<div class="paragraph"><p>Request headers can also be obtained using pattern matching:</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="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="color: #009900">Headers</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Headers are returned as a map with keys being lowercase +binary strings, and values as binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the headers are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get all 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">Headers</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.header">cowboy_req:header(3)</a>, +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html index cd6bc638..a5c28fc8 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:host(3)</title> @@ -67,91 +67,91 @@ <h1 class="lined-header"><span>cowboy_req:host(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:host - URI host name</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">host</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the host name of the effective request URI.</p></div>
-<div class="paragraph"><p>The host name can also be obtained using pattern matching:</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="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="color: #009900">Host</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The host name is returned as a lowercase binary string.
-It is case insensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the host name is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s host name</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">Host</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:host - URI host name</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">host</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the host name of the effective request URI.</p></div> +<div class="paragraph"><p>The host name can also be obtained using pattern matching:</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="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="color: #009900">Host</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The host name is returned as a lowercase binary string. +It is case insensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the host name is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s host name</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">Host</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html index 14e065bc..a423256f 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:host_info(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy_req:host_info(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:host_info - Access the route’s heading host segments</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">host_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the tokens for the heading host segments.</p></div>
-<div class="paragraph"><p>This is the part of the host name that was matched using
-the <code>...</code> notation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The tokens are returned as a list of case insensitive
-binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the host_info tokens</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">HostInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:host_info - Access the route’s heading host segments</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">host_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the tokens for the heading host segments.</p></div> +<div class="paragraph"><p>This is the part of the host name that was matched using +the <code>...</code> notation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The tokens are returned as a list of case insensitive +binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the host_info tokens</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">HostInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:host_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html index a1cf74a0..d07ea532 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:match_cookies(3)</title> @@ -67,123 +67,123 @@ <h1 class="lined-header"><span>cowboy_req:match_cookies(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:match_cookies - Match cookies against constraints</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">match_cookies</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Parse the cookies and match specific values against
-constraints.</p></div>
-<div class="paragraph"><p>Cowboy will only return the cookie values specified in the
-fields list, and ignore all others. Fields can be either
-the name of the cookie requested; the name along with a
-list of constraints; or the name, a list of constraints
-and a default value in case the cookie is missing.</p></div>
-<div class="paragraph"><p>This function will crash if the cookie is missing and no
-default value is provided. This function will also crash
-if a constraint fails.</p></div>
-<div class="paragraph"><p>The name of the cookie must be provided as an atom. The
-key of the returned map will be that atom. The value may
-be converted through the use of constraints, making this
-function able to extract, validate and convert values all
-in one step.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Fields
-</dt>
-<dd>
-<p>
-Cookies to retrieve.
-</p>
-<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Desired values are returned as a map. The key is the atom
-that was given in the list of fields, and the value is the
-optionally converted value after applying constraints.</p></div>
-<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div>
-<div class="paragraph"><p>An exception is triggered when the match fails.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Match fields</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-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span>
-#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Match fields and apply constraints</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-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span>
-#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Match fields with default values</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">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:match_cookies - Match cookies against constraints</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">match_cookies</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Parse the cookies and match specific values against +constraints.</p></div> +<div class="paragraph"><p>Cowboy will only return the cookie values specified in the +fields list, and ignore all others. Fields can be either +the name of the cookie requested; the name along with a +list of constraints; or the name, a list of constraints +and a default value in case the cookie is missing.</p></div> +<div class="paragraph"><p>This function will crash if the cookie is missing and no +default value is provided. This function will also crash +if a constraint fails.</p></div> +<div class="paragraph"><p>The name of the cookie must be provided as an atom. The +key of the returned map will be that atom. The value may +be converted through the use of constraints, making this +function able to extract, validate and convert values all +in one step.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Fields +</dt> +<dd> +<p> +Cookies to retrieve. +</p> +<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Desired values are returned as a map. The key is the atom +that was given in the list of fields, and the value is the +optionally converted value after applying constraints.</p></div> +<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div> +<div class="paragraph"><p>An exception is triggered when the match fails.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Match fields</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-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span> +#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Match fields and apply constraints</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-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span> +#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Match fields with default values</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">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html index da342012..bfbc7496 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:match_qs(3)</title> @@ -67,123 +67,123 @@ <h1 class="lined-header"><span>cowboy_req:match_qs(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:match_qs - Match the query string against constraints</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">match_qs</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Parse the query string and match specific values against
-constraints.</p></div>
-<div class="paragraph"><p>Cowboy will only return the query string values specified
-in the fields list, and ignore all others. Fields can be
-either the key requested; the key along with a list of
-constraints; or the key, a list of constraints and a
-default value in case the key is missing.</p></div>
-<div class="paragraph"><p>This function will crash if the key is missing and no
-default value is provided. This function will also crash
-if a constraint fails.</p></div>
-<div class="paragraph"><p>The key must be provided as an atom. The key of the
-returned map will be that atom. The value may be converted
-through the use of constraints, making this function able
-to extract, validate and convert values all in one step.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Fields
-</dt>
-<dd>
-<p>
-Fields to retrieve from the query string.
-</p>
-<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Desired values are returned as a map. The key is the atom
-that was given in the list of fields, and the value is the
-optionally converted value after applying constraints.</p></div>
-<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div>
-<div class="paragraph"><p>An exception is triggered when the match fails.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Match fields</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-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span>
-#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Match fields and apply constraints</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-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span>
-#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Match fields with default values</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">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>,
-<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:match_qs - Match the query string against constraints</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">match_qs</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Parse the query string and match specific values against +constraints.</p></div> +<div class="paragraph"><p>Cowboy will only return the query string values specified +in the fields list, and ignore all others. Fields can be +either the key requested; the key along with a list of +constraints; or the key, a list of constraints and a +default value in case the key is missing.</p></div> +<div class="paragraph"><p>This function will crash if the key is missing and no +default value is provided. This function will also crash +if a constraint fails.</p></div> +<div class="paragraph"><p>The key must be provided as an atom. The key of the +returned map will be that atom. The value may be converted +through the use of constraints, making this function able +to extract, validate and convert values all in one step.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Fields +</dt> +<dd> +<p> +Fields to retrieve from the query string. +</p> +<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Desired values are returned as a map. The key is the atom +that was given in the list of fields, and the value is the +optionally converted value after applying constraints.</p></div> +<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div> +<div class="paragraph"><p>An exception is triggered when the match fails.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Match fields</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-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span> +#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Match fields and apply constraints</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-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span> +#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Match fields with default values</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">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>, +<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html index da70b08c..1beab4a6 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:method(3)</title> @@ -67,100 +67,100 @@ <h1 class="lined-header"><span>cowboy_req:method(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:method - HTTP method</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">method</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Method</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the request’s HTTP method.</p></div>
-<div class="paragraph"><p>The method can also be obtained using pattern matching:</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="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #009900">Method</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The request’s HTTP method is returned as a binary string.
-While methods are case sensitive, standard methods are
-always uppercase.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the method is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Ensure the request’s method is GET</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: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:method</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Allow methods from list</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">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</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">lists:member</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_req:method</span></span>(<span style="color: #009900">Req</span>), [<span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #000080">true</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>);
- <span style="color: #000080">false</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">method_not_allowed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</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="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:method - HTTP method</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">method</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Method</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the request’s HTTP method.</p></div> +<div class="paragraph"><p>The method can also be obtained using pattern matching:</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="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="color: #009900">Method</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The request’s HTTP method is returned as a binary string. +While methods are case sensitive, standard methods are +always uppercase.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the method is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Ensure the request’s method is GET</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: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:method</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Allow methods from list</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">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</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">lists:member</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_req:method</span></span>(<span style="color: #009900">Req</span>), [<span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #000080">true</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>); + <span style="color: #000080">false</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">method_not_allowed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</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="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html index d04e504d..f5949f9f 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:parse_cookies(3)</title> @@ -67,91 +67,91 @@ <h1 class="lined-header"><span>cowboy_req:parse_cookies(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:parse_cookies - Parse cookie headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">parse_cookies</span></span>(<span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Parse cookie headers.</p></div>
-<div class="paragraph"><p>Alias for <a href="../cowboy_req.parse_header">cowboy_req:parse_header(<a href="#cookie">[cookie]</a>, Req)</a>.</p></div>
-<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div>
-<div class="paragraph"><p>While an empty cookie header is not valid, some clients do
-send it. Cowboy will in this case also return <code>[]</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The cookies are returned as a list of key/values. Keys and
-values are case sensitive binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cookie/2,3</code> and <code>cookies/1</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Look for a specific cookie</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">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>),
-{<span style="color: #990000">_</span>, <span style="color: #009900">Token</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #FF6600">token</span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a>,
-<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:parse_cookies - Parse cookie headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">parse_cookies</span></span>(<span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>Parse cookie headers.</p></div> +<div class="paragraph"><p>Alias for <a href="../cowboy_req.parse_header">cowboy_req:parse_header(<a href="#cookie">[cookie]</a>, Req)</a>.</p></div> +<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div> +<div class="paragraph"><p>While an empty cookie header is not valid, some clients do +send it. Cowboy will in this case also return <code>[]</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The cookies are returned as a list of key/values. Keys and +values are case sensitive binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>cookie/2,3</code> and <code>cookies/1</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Look for a specific cookie</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">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>), +{<span style="color: #990000">_</span>, <span style="color: #009900">Token</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #FF6600">token</span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html index aad1926f..7e22192a 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:parse_header(3)</title> @@ -67,283 +67,283 @@ <h1 class="lined-header"><span>cowboy_req:parse_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:parse_header - Parse the given HTTP header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span>
-<span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">ParsedValue</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Parse the given HTTP header.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>The type of the parsed value varies depending on
-the header. Similarly, the default value when calling
-<code>cowboy_req:parse_header/2</code> differs depending on the
-header.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired HTTP header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the header is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The parsed header value varies depending on the header.
-When the header is missing, the default argument is returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_headers">Headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following snippets detail the types returned by the
-different headers. Unless mentioned otherwise, the
-default value when the header is missing will be <code>undefined</code>:</p></div>
-<div class="listingblock">
-<div class="title">accept</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> [{{<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}, <span style="color: #009900">Quality</span>, <span style="color: #009900">AcceptExt</span>}]
-
-<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span>
-<span style="color: #009900">AcceptExt</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">accept-charset, accept-encoding and accept-language</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Value</span>, <span style="color: #009900">Quality</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-charset"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-encoding"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-language"</span><span style="color: #990000">>></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">authorization</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"authorization"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">basic</span>, <span style="color: #009900">Username</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Password</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">bearer</span>, <span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">digest</span>, [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]}</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">content-length</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>When the content-length header is missing, <code>0</code> is returned.</p></div>
-<div class="listingblock">
-<div class="title">content-type</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> {<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}
-
-<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive;</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the value for the charset parameter is case insensitive
-and returned as a lowercase binary string.</p></div>
-<div class="listingblock">
-<div class="title">cookie</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"cookie"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div>
-<div class="paragraph"><p>While an empty cookie header is not valid, some clients do
-send it. Cowboy will in this case also return <code>[]</code>.</p></div>
-<div class="listingblock">
-<div class="title">expect</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"expect"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">continue</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">if-match and if-none-match</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> <span style="color: #FF6600">'*'</span> | [{<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="color: #009900">OpaqueTag</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"if-match"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"if-none-match"</span><span style="color: #990000">>></span>
-<span style="color: #009900">OpaqueTag</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">if-modified-since and if-unmodified-since</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">range</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"range"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #009900">From</span>, <span style="color: #009900">To</span>} | <span style="color: #009900">Final</span>
-
-<span style="color: #009900">From</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()
-<span style="color: #009900">To</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="color: #FF6600">infinity</span>
-<span style="color: #009900">Final</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">neg_integer</span></span>()</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">sec-websocket-extensions</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-extensions"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> [{<span style="color: #009900">Extension</span>, <span style="color: #009900">Params</span>}]
-
-<span style="color: #009900">Extension</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">sec-websocket-protocol and upgrade</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"upgrade"</span><span style="color: #990000">>></span>
-<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">x-forwarded-for</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"x-forwarded-for"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>]
-
-<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Unknown 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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000">_</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #000080">undefined</span>, <span style="color: #009900">RawValue</span>}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Parse the accept header with a custom default value</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-style: italic"><span style="color: #9A1900">%% Accept everything when header is missing.</span></span>
-<span style="color: #009900">Accept</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>,
- [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, []}, <span style="color: #993399">1000</span>, []}])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Parse the content-length header</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-style: italic"><span style="color: #9A1900">%% Default content-length is 0.</span></span>
-<span style="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.header">cowboy_req:header(3)</a>,
-<a href="../cowboy_req.headers">cowboy_req:headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:parse_header - Parse the given HTTP header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span> +<span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">ParsedValue</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Parse the given HTTP header.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>The type of the parsed value varies depending on +the header. Similarly, the default value when calling +<code>cowboy_req:parse_header/2</code> differs depending on the +header.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired HTTP header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the header is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The parsed header value varies depending on the header. +When the header is missing, the default argument is returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_headers">Headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The following snippets detail the types returned by the +different headers. Unless mentioned otherwise, the +default value when the header is missing will be <code>undefined</code>:</p></div> +<div class="listingblock"> +<div class="title">accept</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> [{{<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}, <span style="color: #009900">Quality</span>, <span style="color: #009900">AcceptExt</span>}] + +<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span> +<span style="color: #009900">AcceptExt</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">accept-charset, accept-encoding and accept-language</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Value</span>, <span style="color: #009900">Quality</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-charset"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-encoding"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-language"</span><span style="color: #990000">>></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">authorization</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"authorization"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">basic</span>, <span style="color: #009900">Username</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Password</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">bearer</span>, <span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">digest</span>, [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]}</tt></pre></div></div> +<div class="listingblock"> +<div class="title">content-length</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>When the content-length header is missing, <code>0</code> is returned.</p></div> +<div class="listingblock"> +<div class="title">content-type</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> {<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>} + +<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive;</span></span></tt></pre></div></div> +<div class="paragraph"><p>Note that the value for the charset parameter is case insensitive +and returned as a lowercase binary string.</p></div> +<div class="listingblock"> +<div class="title">cookie</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"cookie"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div> +<div class="paragraph"><p>While an empty cookie header is not valid, some clients do +send it. Cowboy will in this case also return <code>[]</code>.</p></div> +<div class="listingblock"> +<div class="title">expect</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"expect"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">continue</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">if-match and if-none-match</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> <span style="color: #FF6600">'*'</span> | [{<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="color: #009900">OpaqueTag</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"if-match"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"if-none-match"</span><span style="color: #990000">>></span> +<span style="color: #009900">OpaqueTag</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">if-modified-since and if-unmodified-since</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()</tt></pre></div></div> +<div class="listingblock"> +<div class="title">range</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"range"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #009900">From</span>, <span style="color: #009900">To</span>} | <span style="color: #009900">Final</span> + +<span style="color: #009900">From</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">To</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="color: #FF6600">infinity</span> +<span style="color: #009900">Final</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">neg_integer</span></span>()</tt></pre></div></div> +<div class="listingblock"> +<div class="title">sec-websocket-extensions</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-extensions"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> [{<span style="color: #009900">Extension</span>, <span style="color: #009900">Params</span>}] + +<span style="color: #009900">Extension</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">sec-websocket-protocol and upgrade</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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"upgrade"</span><span style="color: #990000">>></span> +<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">x-forwarded-for</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">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"x-forwarded-for"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>] + +<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Unknown 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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000">_</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #000080">undefined</span>, <span style="color: #009900">RawValue</span>}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Parse the accept header with a custom default value</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-style: italic"><span style="color: #9A1900">%% Accept everything when header is missing.</span></span> +<span style="color: #009900">Accept</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, + [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, []}, <span style="color: #993399">1000</span>, []}])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Parse the content-length header</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-style: italic"><span style="color: #9A1900">%% Default content-length is 0.</span></span> +<span style="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.header">cowboy_req:header(3)</a>, +<a href="../cowboy_req.headers">cowboy_req:headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html index 9ac6af9a..3b9970cc 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:parse_qs(3)</title> @@ -67,117 +67,117 @@ <h1 class="lined-header"><span>cowboy_req:parse_qs(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:parse_qs - Parse the query string</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">parse_qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>Parse the query string as a list of key/value pairs.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The parsed query string is returned as a list of key/value pairs.
-The key is a binary string. The value is either a binary string,
-or the atom <code>true</code>. Both key and value are case sensitive.</p></div>
-<div class="paragraph"><p>The atom <code>true</code> is returned when a key is present in the query
-string without a value. For example, in the following URIs
-the key <code><<"edit">></code> will always have the value <code>true</code>:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>/posts/42?edit</code>
-</p>
-</li>
-<li>
-<p>
-<code>/posts/42?edit&exclusive=1</code>
-</p>
-</li>
-<li>
-<p>
-<code>/posts/42?exclusive=1&edit</code>
-</p>
-</li>
-<li>
-<p>
-<code>/posts/42?exclusive=1&edit&from=web</code>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The parsed value is not longer cached in the Req object.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Only the parsed query string is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>qs_val/1</code> and <code>qs_vals/1</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Parse the query string and convert the keys to atoms</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">ParsedQs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_qs</span></span>(<span style="color: #009900">Req</span>),
-<span style="color: #009900">AtomsQs</span> <span style="color: #990000">=</span> [{<span style="font-weight: bold"><span style="color: #000000">binary_to_existing_atom</span></span>(<span style="color: #009900">K</span>, <span style="color: #FF6600">latin1</span>), <span style="color: #009900">V</span>}
- || {<span style="color: #009900">K</span>, <span style="color: #009900">V</span>} <span style="color: #990000"><-</span> <span style="color: #009900">ParsedQs</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>,
-<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:parse_qs - Parse the query string</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">parse_qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div> +<div class="paragraph"><p>Parse the query string as a list of key/value pairs.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The parsed query string is returned as a list of key/value pairs. +The key is a binary string. The value is either a binary string, +or the atom <code>true</code>. Both key and value are case sensitive.</p></div> +<div class="paragraph"><p>The atom <code>true</code> is returned when a key is present in the query +string without a value. For example, in the following URIs +the key <code><<"edit">></code> will always have the value <code>true</code>:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>/posts/42?edit</code> +</p> +</li> +<li> +<p> +<code>/posts/42?edit&exclusive=1</code> +</p> +</li> +<li> +<p> +<code>/posts/42?exclusive=1&edit</code> +</p> +</li> +<li> +<p> +<code>/posts/42?exclusive=1&edit&from=web</code> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The parsed value is not longer cached in the Req object. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Only the parsed query string is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>qs_val/1</code> and <code>qs_vals/1</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Parse the query string and convert the keys to atoms</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">ParsedQs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_qs</span></span>(<span style="color: #009900">Req</span>), +<span style="color: #009900">AtomsQs</span> <span style="color: #990000">=</span> [{<span style="font-weight: bold"><span style="color: #000000">binary_to_existing_atom</span></span>(<span style="color: #009900">K</span>, <span style="color: #FF6600">latin1</span>), <span style="color: #009900">V</span>} + || {<span style="color: #009900">K</span>, <span style="color: #009900">V</span>} <span style="color: #990000"><-</span> <span style="color: #009900">ParsedQs</span>]<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html index e5a69e4f..0836001b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:path(3)</title> @@ -67,90 +67,90 @@ <h1 class="lined-header"><span>cowboy_req:path(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:path - URI path</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">path</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the path of the effective request URI.</p></div>
-<div class="paragraph"><p>The path can also be obtained using pattern matching:</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="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="color: #009900">Path</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The path is returned as a binary string. It is case sensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the path is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s path</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">Path</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:path - URI path</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">path</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the path of the effective request URI.</p></div> +<div class="paragraph"><p>The path can also be obtained using pattern matching:</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="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="color: #009900">Path</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The path is returned as a binary string. It is case sensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the path is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s path</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">Path</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html index 39ef5f81..03649d9b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:path_info(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy_req:path_info(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:path_info - Access the route’s trailing path segments</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">path_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the tokens for the trailing path segments.</p></div>
-<div class="paragraph"><p>This is the part of the host name that was matched using
-the <code>...</code> notation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The tokens are returned as a list of case sensitive
-binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the path_info tokens</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">PathInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:path_info - Access the route’s trailing path segments</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">path_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the tokens for the trailing path segments.</p></div> +<div class="paragraph"><p>This is the part of the host name that was matched using +the <code>...</code> notation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The tokens are returned as a list of case sensitive +binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the path_info tokens</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">PathInfo</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:path_info</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html index 6568e749..634b8e08 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:peer(3)</title> @@ -67,96 +67,96 @@ <h1 class="lined-header"><span>cowboy_req:peer(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:peer - Peer address and port</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">peer</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Peer</span>
-
-<span style="color: #009900">Peer</span> <span style="color: #990000">::</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Return the peer’s IP address and port number.</p></div>
-<div class="paragraph"><p>The peer can also be obtained using pattern matching:</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="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="color: #009900">IP</span>, <span style="color: #009900">Port</span>}} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The peer’s IP address and port number.</p></div>
-<div class="paragraph"><p>The peer is not necessarily the client’s IP address and port.
-It is the IP address of the endpoint connecting directly to
-the server, which may be a gateway or a proxy.</p></div>
-<div class="paragraph"><p>The forwarded header can be used to get better information
-about the different endpoints from the client to the server.
-Note however that it is only informative; there is no reliable
-way of determining the source of an HTTP request.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the peer is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the peer IP address and port number.</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">IP</span>, <span style="color: #009900">Port</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:peer</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:peer - Peer address and port</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">peer</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Peer</span> + +<span style="color: #009900">Peer</span> <span style="color: #990000">::</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Return the peer’s IP address and port number.</p></div> +<div class="paragraph"><p>The peer can also be obtained using pattern matching:</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="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="color: #009900">IP</span>, <span style="color: #009900">Port</span>}} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The peer’s IP address and port number.</p></div> +<div class="paragraph"><p>The peer is not necessarily the client’s IP address and port. +It is the IP address of the endpoint connecting directly to +the server, which may be a gateway or a proxy.</p></div> +<div class="paragraph"><p>The forwarded header can be used to get better information +about the different endpoints from the client to the server. +Note however that it is only informative; there is no reliable +way of determining the source of an HTTP request.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the peer is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the peer IP address and port number.</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">IP</span>, <span style="color: #009900">Port</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:peer</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html index 93f106b0..5864d84a 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:port(3)</title> @@ -67,90 +67,90 @@ <h1 class="lined-header"><span>cowboy_req:port(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:port - URI port number</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">port</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Port</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the port number of the effective request URI.</p></div>
-<div class="paragraph"><p>Note that the port number returned by this function is obtained
-by parsing the host header. It may be different from the port
-the peer used to connect to Cowboy.</p></div>
-<div class="paragraph"><p>The port number can also be obtained using pattern matching:</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="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="color: #009900">Port</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The port number is returned as an integer.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the port number is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s port number</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">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:port</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:port - URI port number</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">port</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Port</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the port number of the effective request URI.</p></div> +<div class="paragraph"><p>Note that the port number returned by this function is obtained +by parsing the host header. It may be different from the port +the peer used to connect to Cowboy.</p></div> +<div class="paragraph"><p>The port number can also be obtained using pattern matching:</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="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="color: #009900">Port</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The port number is returned as an integer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the port number is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s port number</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">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:port</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html index 8097d067..bc56d006 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:push(3)</title> @@ -67,141 +67,141 @@ <h1 class="lined-header"><span>cowboy_req:push(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:push - Push a resource to the client</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span>
-
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:push_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Push a resource to the client.</p></div>
-<div class="paragraph"><p>Cowboy handles push requests the same way as if they came
-from the client, including the creation of a request handling
-process, routing and middlewares and so on.</p></div>
-<div class="paragraph"><p>This function does nothing when the HTTP/1.1 protocol is
-used. You may call it safely without first checking whether
-the connection uses HTTP/2.</p></div>
-<div class="paragraph"><p>The header names must be given as lowercase binary strings.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Note that the headers must be the headers the client is expected
-to send if it were to perform the request. They are therefore
-request headers, and not response headers.</p></div>
-<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string,
-and take the scheme, host and port directly from the current
-request’s URI. You can override them by passing options.</p></div>
-<div class="paragraph"><p>It is not possible to push resources after sending a response.
-Any attempt will result in an error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Path
-</dt>
-<dd>
-<p>
-The status code for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-The response headers.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-Customize the HTTP method or the URI scheme, host, port
-or query string.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Push a resource</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">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req</span>),</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Push a resource with a custom host</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">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:push - Push a resource to the client</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> + +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>() +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:push_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Push a resource to the client.</p></div> +<div class="paragraph"><p>Cowboy handles push requests the same way as if they came +from the client, including the creation of a request handling +process, routing and middlewares and so on.</p></div> +<div class="paragraph"><p>This function does nothing when the HTTP/1.1 protocol is +used. You may call it safely without first checking whether +the connection uses HTTP/2.</p></div> +<div class="paragraph"><p>The header names must be given as lowercase binary strings. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Note that the headers must be the headers the client is expected +to send if it were to perform the request. They are therefore +request headers, and not response headers.</p></div> +<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string, +and take the scheme, host and port directly from the current +request’s URI. You can override them by passing options.</p></div> +<div class="paragraph"><p>It is not possible to push resources after sending a response. +Any attempt will result in an error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Path +</dt> +<dd> +<p> +The status code for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +The response headers. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +Customize the HTTP method or the URI scheme, host, port +or query string. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Push a resource</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">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req</span>),</tt></pre></div></div> +<div class="listingblock"> +<div class="title">Push a resource with a custom host</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">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html index 39ec5d7c..62407766 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:qs(3)</title> @@ -67,89 +67,89 @@ <h1 class="lined-header"><span>cowboy_req:qs(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:qs - URI query string</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Qs</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the query string of the effective request URI.</p></div>
-<div class="paragraph"><p>The query string can also be obtained using pattern matching:</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="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="color: #009900">Qs</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The query string is returned as a binary string. It is case sensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the query string is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s query string</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">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:qs</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a>,
-<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:qs - URI query string</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Qs</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the query string of the effective request URI.</p></div> +<div class="paragraph"><p>The query string can also be obtained using pattern matching:</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="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="color: #009900">Qs</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The query string is returned as a binary string. It is case sensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the query string is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s query string</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">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:qs</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html index e792a7a6..08b506f0 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_body(3)</title> @@ -67,143 +67,143 @@ <h1 class="lined-header"><span>cowboy_req:read_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_body - Read the request body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
- | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Read the request body.</p></div>
-<div class="paragraph"><p>This function reads a chunk of the request body. A <code>more</code> tuple
-is returned when more data remains to be read. Call the function
-repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div>
-<div class="paragraph"><p>An <code>ok</code> tuple with empty data is returned when the request has no body,
-or when calling this function again after the body has already
-been read. It is therefore safe to call this function directly.
-Note that the body can only be read once.</p></div>
-<div class="paragraph"><p>This function reads the request body from the connection process.
-The connection process is responsible for reading from the socket.
-The exact behavior varies depending on the protocol.</p></div>
-<div class="paragraph"><p>The options therefore are only related to the communication
-between the request process and the connection process.</p></div>
-<div class="paragraph"><p>Cowboy will automatically handle protocol details including
-the expect header, chunked transfer-encoding and others.</p></div>
-<div class="paragraph"><p>Once the body has been read fully, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options.
-</p>
-<div class="paragraph"><p>The <code>length</code> option can be used to request smaller or bigger
-chunks of data to be sent. It is a best effort approach, Cowboy
-may send more data than configured on occasions. It defaults
-to 8MB.</p></div>
-<div class="paragraph"><p>The <code>period</code> indicates how long the connection process will wait
-before it provides us with the data it received. It defaults
-to 15 seconds.</p></div>
-<div class="paragraph"><p>The connection process sends data to the request process when
-either the <code>length</code> of data or the <code>period</code> of time is reached.</p></div>
-<div class="paragraph"><p>The <code>timeout</code> option is a safeguard in case the connection
-process becomes unresponsive. The function will crash if no
-message was received in that interval. The timeout should be
-larger than the period. It defaults to the period + 1 second.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div>
-<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read,
-either because this is the last chunk of data, the body has already
-been read, or there was no body to begin with.</p></div>
-<div class="paragraph"><p>The data is always returned as a binary.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>body/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read the entire 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">read_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, <span style="color: #009900">Req</span>};
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Read the body in small chunks</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">cowboy_req:read_body</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_body - Read the request body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Read the request body.</p></div> +<div class="paragraph"><p>This function reads a chunk of the request body. A <code>more</code> tuple +is returned when more data remains to be read. Call the function +repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div> +<div class="paragraph"><p>An <code>ok</code> tuple with empty data is returned when the request has no body, +or when calling this function again after the body has already +been read. It is therefore safe to call this function directly. +Note that the body can only be read once.</p></div> +<div class="paragraph"><p>This function reads the request body from the connection process. +The connection process is responsible for reading from the socket. +The exact behavior varies depending on the protocol.</p></div> +<div class="paragraph"><p>The options therefore are only related to the communication +between the request process and the connection process.</p></div> +<div class="paragraph"><p>Cowboy will automatically handle protocol details including +the expect header, chunked transfer-encoding and others.</p></div> +<div class="paragraph"><p>Once the body has been read fully, Cowboy sets the content-length +header if it was not previously provided.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. +</p> +<div class="paragraph"><p>The <code>length</code> option can be used to request smaller or bigger +chunks of data to be sent. It is a best effort approach, Cowboy +may send more data than configured on occasions. It defaults +to 8MB.</p></div> +<div class="paragraph"><p>The <code>period</code> indicates how long the connection process will wait +before it provides us with the data it received. It defaults +to 15 seconds.</p></div> +<div class="paragraph"><p>The connection process sends data to the request process when +either the <code>length</code> of data or the <code>period</code> of time is reached.</p></div> +<div class="paragraph"><p>The <code>timeout</code> option is a safeguard in case the connection +process becomes unresponsive. The function will crash if no +message was received in that interval. The timeout should be +larger than the period. It defaults to the period + 1 second.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div> +<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read, +either because this is the last chunk of data, the body has already +been read, or there was no body to begin with.</p></div> +<div class="paragraph"><p>The data is always returned as a binary.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>body/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read the entire 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">read_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, <span style="color: #009900">Req</span>}; + {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Read the body in small chunks</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">cowboy_req:read_body</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html index 29f18993..c5b548d3 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_part(3)</title> @@ -67,162 +67,162 @@ <h1 class="lined-header"><span>cowboy_req:read_part(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_part - Read the next multipart headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} | {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Read the next part of a multipart body.</p></div>
-<div class="paragraph"><p>This function reads the request body and parses it as
-multipart. Each parts of a multipart representation have
-their own headers and body. This function parses and returns
-headers. Examples of multipart media types are
-<code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div>
-<div class="paragraph"><p>Cowboy will skip any data remaining until the beginning of
-the next part. This includes the preamble to the multipart
-message but also the body of a previous part if it hasn’t
-been read. Both are skipped automatically when calling this
-function.</p></div>
-<div class="paragraph"><p>Cowboy will read the body before parsing in chunks of size
-up to 64KB, with a period of 5 seconds. This is tailored for
-reading part headers and might not be the most efficient for
-skipping the previous part’s body.</p></div>
-<div class="paragraph"><p>The headers returned are MIME headers, <strong>NOT</strong> HTTP headers.
-They can be parsed using the functions from the <code>cow_multipart</code>
-module. In addition, the <code>cow_multipart:form_data/1</code> function
-can be used to quickly extract information from <code>multipart/form-data</code>
-representations.</p></div>
-<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div>
-<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options. Please refer to
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-for details about each option.
-</p>
-<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code>
-to 5 seconds.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <code>ok</code> tuple is returned containing the next part’s headers
-as a map.</p></div>
-<div class="paragraph"><p>A <code>done</code> tuple is returned if there are no more parts to read.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>part/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read all parts</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">acc_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req1</span>, <span style="color: #990000"><<>></span>),
- <span style="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req</span>, [{<span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>}|<span style="color: #009900">Acc</span>]);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</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">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>);
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, <span style="color: #009900">Req</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Read all part headers, skipping bodies</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">skip_body_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req</span>, [<span style="color: #009900">Headers</span>|<span style="color: #009900">Acc</span>]);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Read a part header in larger chunks</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">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_part - Read the next multipart headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} | {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>() +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Read the next part of a multipart body.</p></div> +<div class="paragraph"><p>This function reads the request body and parses it as +multipart. Each parts of a multipart representation have +their own headers and body. This function parses and returns +headers. Examples of multipart media types are +<code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div> +<div class="paragraph"><p>Cowboy will skip any data remaining until the beginning of +the next part. This includes the preamble to the multipart +message but also the body of a previous part if it hasn’t +been read. Both are skipped automatically when calling this +function.</p></div> +<div class="paragraph"><p>Cowboy will read the body before parsing in chunks of size +up to 64KB, with a period of 5 seconds. This is tailored for +reading part headers and might not be the most efficient for +skipping the previous part’s body.</p></div> +<div class="paragraph"><p>The headers returned are MIME headers, <strong>NOT</strong> HTTP headers. +They can be parsed using the functions from the <code>cow_multipart</code> +module. In addition, the <code>cow_multipart:form_data/1</code> function +can be used to quickly extract information from <code>multipart/form-data</code> +representations.</p></div> +<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div> +<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length +header if it was not previously provided.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. Please refer to +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +for details about each option. +</p> +<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code> +to 5 seconds.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <code>ok</code> tuple is returned containing the next part’s headers +as a map.</p></div> +<div class="paragraph"><p>A <code>done</code> tuple is returned if there are no more parts to read.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>part/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read all parts</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">acc_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req1</span>, <span style="color: #990000"><<>></span>), + <span style="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req</span>, [{<span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>}|<span style="color: #009900">Acc</span>]); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</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">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>); + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, <span style="color: #009900">Req</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Read all part headers, skipping bodies</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">skip_body_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req</span>, [<span style="color: #009900">Headers</span>|<span style="color: #009900">Acc</span>]); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Read a part header in larger chunks</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">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html index 54a79c15..28fe5e6e 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_part_body(3)</title> @@ -67,130 +67,130 @@ <h1 class="lined-header"><span>cowboy_req:read_part_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_part_body - Read the current part’s body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
- | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Read the body of the current part of the multipart message.</p></div>
-<div class="paragraph"><p>This function reads the request body and parses it as
-multipart. Each parts of a multipart representation have
-their own headers and body. This function returns the
-body of the current part. Examples of multipart media types
-are <code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div>
-<div class="paragraph"><p>This function reads a chunk of the part’s body. A <code>more</code> tuple
-is returned when more data remains to be read. Call the function
-repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div>
-<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div>
-<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options. Please refer to
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-for details about each option.
-</p>
-<div class="paragraph"><p>This function uses the same default options as the
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-function.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div>
-<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read.</p></div>
-<div class="paragraph"><p>The data is always returned as a binary.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>part_body/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read a full part’s 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">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>);
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, <span style="color: #009900">Req</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Ensure a part’s body is smaller than 64KB</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">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_part_body - Read the current part’s body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Read the body of the current part of the multipart message.</p></div> +<div class="paragraph"><p>This function reads the request body and parses it as +multipart. Each parts of a multipart representation have +their own headers and body. This function returns the +body of the current part. Examples of multipart media types +are <code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div> +<div class="paragraph"><p>This function reads a chunk of the part’s body. A <code>more</code> tuple +is returned when more data remains to be read. Call the function +repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div> +<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div> +<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length +header if it was not previously provided.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. Please refer to +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +for details about each option. +</p> +<div class="paragraph"><p>This function uses the same default options as the +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +function.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div> +<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read.</p></div> +<div class="paragraph"><p>The data is always returned as a binary.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>part_body/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read a full part’s 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">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>); + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, <span style="color: #009900">Req</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Ensure a part’s body is smaller than 64KB</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">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html index 1be7f378..2fbe784d 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_urlencoded_body(3)</title> @@ -67,126 +67,126 @@ <h1 class="lined-header"><span>cowboy_req:read_urlencoded_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()
-<span style="color: #009900">Body</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>Read and parse a urlencoded request body.</p></div>
-<div class="paragraph"><p>This function reads the request body and parses it as
-<code>application/x-www-form-urlencoded</code>. It returns a list
-of key/values.</p></div>
-<div class="paragraph"><p>The urlencoded media type is used by Web browsers when
-submitting HTML forms using the POST method.</p></div>
-<div class="paragraph"><p>Cowboy needs to read the full body before parsing. By default
-it will read bodies of size up to 64KB. It is possible to
-provide options to read larger bodies if required.</p></div>
-<div class="paragraph"><p>Cowboy will automatically handle protocol details including
-the expect header, chunked transfer-encoding and others.</p></div>
-<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-<div class="paragraph"><p>This function can only be called once. Calling it again will
-result in undefined behavior.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options. Please refer to
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-for details about each option.
-</p>
-<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code>
-to 5 seconds.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <code>ok</code> tuple is returned containing a list of key/values found
-in the body.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>body_qs/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read a urlencoded 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: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>),
-{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Allow large urlencoded bodies</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">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>() +<span style="color: #009900">Body</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div> +<div class="paragraph"><p>Read and parse a urlencoded request body.</p></div> +<div class="paragraph"><p>This function reads the request body and parses it as +<code>application/x-www-form-urlencoded</code>. It returns a list +of key/values.</p></div> +<div class="paragraph"><p>The urlencoded media type is used by Web browsers when +submitting HTML forms using the POST method.</p></div> +<div class="paragraph"><p>Cowboy needs to read the full body before parsing. By default +it will read bodies of size up to 64KB. It is possible to +provide options to read larger bodies if required.</p></div> +<div class="paragraph"><p>Cowboy will automatically handle protocol details including +the expect header, chunked transfer-encoding and others.</p></div> +<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length +header if it was not previously provided.</p></div> +<div class="paragraph"><p>This function can only be called once. Calling it again will +result in undefined behavior.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. Please refer to +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +for details about each option. +</p> +<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code> +to 5 seconds.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <code>ok</code> tuple is returned containing a list of key/values found +in the body.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>body_qs/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read a urlencoded 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: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>), +{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Allow large urlencoded bodies</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">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html index 49b346dd..7f1fe714 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:reply(3)</title> @@ -67,164 +67,164 @@ <h1 class="lined-header"><span>cowboy_req:reply(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:reply - Send the response</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>)
-
-<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>()
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()
-<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Send the response.</p></div>
-<div class="paragraph"><p>The header names must be given as lowercase binary strings.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may overwrite those set by <code>set_resp_header/3</code>
-and <code>set_resp_headers/2</code>.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-<div class="paragraph"><p>The <code>reply/2,3</code> functions will send the body set previously,
-if any. The <code>reply/4</code> function always sends the given body,
-overriding any previously set.</p></div>
-<div class="paragraph"><p>You do not need to set the content-length header when
-sending a response body. Cowboy takes care of it automatically.
-You should however provide a content-type header.</p></div>
-<div class="paragraph"><p>No further data can be transmitted after this function
-returns. This includes the push mechanism. Attempting to
-send two replies, or to push resources after a reply has
-been sent, will result in an error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Status
-</dt>
-<dd>
-<p>
-The status code for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-The response headers.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Body
-</dt>
-<dd>
-<p>
-The body can be either a binary value, an iolist or a
-<code>sendfile</code> tuple telling Cowboy to send the contents of
-a file.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object should be used from that point onward
-as it contains updated information about the state of the request.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Reply</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">404</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Reply 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">401</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"www-authenticate"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Basic realm=\"erlang.org\""</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Reply with custom headers and a 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>
-}, <span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a>,
-<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:reply - Send the response</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>) + +<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>() +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>() +<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Send the response.</p></div> +<div class="paragraph"><p>The header names must be given as lowercase binary strings. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may overwrite those set by <code>set_resp_header/3</code> +and <code>set_resp_headers/2</code>.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +<div class="paragraph"><p>The <code>reply/2,3</code> functions will send the body set previously, +if any. The <code>reply/4</code> function always sends the given body, +overriding any previously set.</p></div> +<div class="paragraph"><p>You do not need to set the content-length header when +sending a response body. Cowboy takes care of it automatically. +You should however provide a content-type header.</p></div> +<div class="paragraph"><p>No further data can be transmitted after this function +returns. This includes the push mechanism. Attempting to +send two replies, or to push resources after a reply has +been sent, will result in an error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Status +</dt> +<dd> +<p> +The status code for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +The response headers. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +Body +</dt> +<dd> +<p> +The body can be either a binary value, an iolist or a +<code>sendfile</code> tuple telling Cowboy to send the contents of +a file. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object should be used from that point onward +as it contains updated information about the state of the request.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Reply</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">404</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Reply 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">401</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"www-authenticate"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Basic realm=\"erlang.org\""</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Reply with custom headers and a 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span> +}, <span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a>, +<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html index c210dd2f..0154a3e9 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:resp_header(3)</title> @@ -67,113 +67,113 @@ <h1 class="lined-header"><span>cowboy_req:resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:resp_header - Response header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>)
-<span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the value for the given response header.</p></div>
-<div class="paragraph"><p>The response header must have been set previously using
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> or
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired response header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the header is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The header value is returned as a binary string. When the
-header is missing, the default argument is returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the content-type response header</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get the content-type response header with a default value</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:resp_header - Response header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>) +<span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the value for the given response header.</p></div> +<div class="paragraph"><p>The response header must have been set previously using +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> or +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired response header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the header is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The header value is returned as a binary string. When the +header is missing, the default argument is returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the content-type response header</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get the content-type response header with a default value</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html index 47e9dcca..731ef078 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:resp_headers(3)</title> @@ -67,79 +67,79 @@ <h1 class="lined-header"><span>cowboy_req:resp_headers(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:resp_headers - Response headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">resp_headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return all response headers.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Headers are returned as a map with keys being lowercase
-binary strings, and values as binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get all response 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">Headers</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:resp_headers - Response headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">resp_headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return all response headers.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Headers are returned as a map with keys being lowercase +binary strings, and values as binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get all response 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">Headers</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html index 12e1fb8b..cb8ea3b9 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:scheme(3)</title> @@ -67,89 +67,89 @@ <h1 class="lined-header"><span>cowboy_req:scheme(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:scheme - URI scheme</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">scheme</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Scheme</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the scheme of the effective request URI.</p></div>
-<div class="paragraph"><p>The scheme can also be obtained using pattern matching:</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="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="color: #009900">Scheme</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The scheme is returned as a binary. It is case insensitive.</p></div>
-<div class="paragraph"><p>Cowboy will only set the scheme to <code><<"http">></code> or <code><<"https">></code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Redirect HTTP to HTTPS</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">init</span></span>(<span style="color: #009900">Req0</span><span style="color: #990000">=</span>#{<span style="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">302</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"https"</span><span style="color: #990000">>></span>})
- }, <span style="color: #009900">Req0</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:scheme - URI scheme</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">scheme</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Scheme</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the scheme of the effective request URI.</p></div> +<div class="paragraph"><p>The scheme can also be obtained using pattern matching:</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="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="color: #009900">Scheme</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The scheme is returned as a binary. It is case insensitive.</p></div> +<div class="paragraph"><p>Cowboy will only set the scheme to <code><<"http">></code> or <code><<"https">></code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Redirect HTTP to HTTPS</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">init</span></span>(<span style="color: #009900">Req0</span><span style="color: #990000">=</span>#{<span style="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">302</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"https"</span><span style="color: #990000">>></span>}) + }, <span style="color: #009900">Req0</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html index 4720ee22..25b53626 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_body(3)</title> @@ -67,138 +67,138 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_body - Set the response body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">set_resp_body</span></span>(<span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Set the response body.</p></div>
-<div class="paragraph"><p>The response body will be sent when a reply is initiated.
-Note that the functions <code>stream_reply/2,3</code> and <code>reply/4</code>
-will override the body set by this function.</p></div>
-<div class="paragraph"><p>This function can also be used to remove a response body
-that was set previously. To do so, simply call this function
-with an empty body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Body
-</dt>
-<dd>
-<p>
-The body can be either a binary value, an iolist or a
-<code>sendfile</code> tuple telling Cowboy to send the contents of
-a file.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the body will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The function now accepts a <code>sendfile</code> tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>set_resp_body_fun/2,3</code> functions were removed.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello world!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Set the response body as an iolist</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>([
- <span style="color: #FF0000">"<html><head><title>"</span>,
- <span style="font-weight: bold"><span style="color: #000000">page_title</span></span>(),
- <span style="color: #FF0000">"</title></head><body>"</span>,
- <span style="font-weight: bold"><span style="color: #000000">page_body</span></span>(),
- <span style="color: #FF0000">"</body></html>"</span>
-], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Tell Cowboy to send data from a 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">ok</span>, <span style="color: #008080">#file_info</span>{<span style="font-weight: bold"><span style="color: #000080">size</span></span><span style="color: #990000">=</span><span style="color: #009900">Size</span>}} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file_info</span></span>(<span style="color: #009900">Filename</span>),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>({<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Filename</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Clear any previously set response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_body - Set the response body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">set_resp_body</span></span>(<span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Set the response body.</p></div> +<div class="paragraph"><p>The response body will be sent when a reply is initiated. +Note that the functions <code>stream_reply/2,3</code> and <code>reply/4</code> +will override the body set by this function.</p></div> +<div class="paragraph"><p>This function can also be used to remove a response body +that was set previously. To do so, simply call this function +with an empty body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Body +</dt> +<dd> +<p> +The body can be either a binary value, an iolist or a +<code>sendfile</code> tuple telling Cowboy to send the contents of +a file. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the body will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The function now accepts a <code>sendfile</code> tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>set_resp_body_fun/2,3</code> functions were removed. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello world!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Set the response body as an iolist</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>([ + <span style="color: #FF0000">"<html><head><title>"</span>, + <span style="font-weight: bold"><span style="color: #000000">page_title</span></span>(), + <span style="color: #FF0000">"</title></head><body>"</span>, + <span style="font-weight: bold"><span style="color: #000000">page_body</span></span>(), + <span style="color: #FF0000">"</body></html>"</span> +], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Tell Cowboy to send data from a 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">ok</span>, <span style="color: #008080">#file_info</span>{<span style="font-weight: bold"><span style="color: #000080">size</span></span><span style="color: #990000">=</span><span style="color: #009900">Size</span>}} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file_info</span></span>(<span style="color: #009900">Filename</span>), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>({<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Filename</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Clear any previously set response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html index b080f69b..f77c91e3 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_cookie(3)</title> @@ -67,167 +67,167 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_cookie(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_cookie - Set a cookie</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, [], <span style="color: #009900">Req</span>)
-
-<span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_cookie:cookie_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Set a cookie to be sent with the response.</p></div>
-<div class="paragraph"><p>Note that cookie names are case sensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Cookie name.
-</p>
-</dd>
-<dt class="hdlist1">
-Value
-</dt>
-<dd>
-<p>
-Cookie value.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-Cookie options.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the cookie will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: <code>set_resp_cookie/3</code> introduced as an alias to <code>set_resp_cookie/4</code> with no options.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The first argument type is now <code>binary()</code> instead of <code>iodata()</code>.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set a session cookie</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Set a cookie with an expiration time</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"fr-FR"</span><span style="color: #990000">>></span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Delete a cookie</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<>></span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Set a cookie for a specific domain and path</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Restrict a cookie to HTTPS</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Restrict a cookie to HTTP</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_cookie - Set a cookie</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, [], <span style="color: #009900">Req</span>) + +<span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_cookie:cookie_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Set a cookie to be sent with the response.</p></div> +<div class="paragraph"><p>Note that cookie names are case sensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Cookie name. +</p> +</dd> +<dt class="hdlist1"> +Value +</dt> +<dd> +<p> +Cookie value. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +Cookie options. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the cookie will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: <code>set_resp_cookie/3</code> introduced as an alias to <code>set_resp_cookie/4</code> with no options. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The first argument type is now <code>binary()</code> instead of <code>iodata()</code>. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set a session cookie</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Set a cookie with an expiration time</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"fr-FR"</span><span style="color: #990000">>></span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Delete a cookie</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<>></span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Set a cookie for a specific domain and path</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Restrict a cookie to HTTPS</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Restrict a cookie to HTTP</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html index 1fe9aa82..6f9d80cf 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_header(3)</title> @@ -67,121 +67,121 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_header - Set a response header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">set_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case depends on header</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Set a header to be sent with the response.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may be overwritten by those set from the
-reply functions.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Value
-</dt>
-<dd>
-<p>
-Header value.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the header will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set a header in the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Construct a header using iolists</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>,
- [<span style="font-weight: bold"><span style="color: #000000">allowed_methods</span></span>(), <span style="color: #FF0000">", OPTIONS"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_header - Set a response header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">set_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case depends on header</span></span></tt></pre></div></div> +<div class="paragraph"><p>Set a header to be sent with the response.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may be overwritten by those set from the +reply functions.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Value +</dt> +<dd> +<p> +Header value. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the header will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set a header in the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Construct a header using iolists</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, + [<span style="font-weight: bold"><span style="color: #000000">allowed_methods</span></span>(), <span style="color: #FF0000">", OPTIONS"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html index e55c1223..5a60c156 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_headers(3)</title> @@ -67,109 +67,109 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_headers(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_headers - Set several response headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">set_resp_headers</span></span>(<span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Set several headers to be sent with the response.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may be overwritten by those set from the
-reply functions. Likewise, headers set by this function may
-overwrite headers that were set previously.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-Headers as a map with keys being lowercase binary strings,
-and values as binary strings.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the headers will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set several response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_headers</span></span>(#{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>,
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-encoding"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"gzip"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_headers - Set several response headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">set_resp_headers</span></span>(<span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Set several headers to be sent with the response.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may be overwritten by those set from the +reply functions. Likewise, headers set by this function may +overwrite headers that were set previously.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +Headers as a map with keys being lowercase binary strings, +and values as binary strings. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the headers will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set several response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_headers</span></span>(#{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>, + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-encoding"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"gzip"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html index 2a8651cb..1753c362 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:stream_body(3)</title> @@ -67,116 +67,116 @@ <h1 class="lined-header"><span>cowboy_req:stream_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:stream_body - Stream the response body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span>
-
-<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div>
-<div class="paragraph"><p>Stream the response body.</p></div>
-<div class="paragraph"><p>This function may be called as many times as needed after
-initiating a response using the
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a>
-function.</p></div>
-<div class="paragraph"><p>The second argument indicates if this call is the final
-call. Use the <code>nofin</code> value until you know no more data
-will be sent. The final call should use <code>fin</code> (possibly
-with an empty data value).</p></div>
-<div class="paragraph"><p>Note that not using <code>fin</code> for the final call is not an
-error; Cowboy will take care of it when the request
-handler terminates if needed. Depending on the resource
-it may however be more efficient to do it as early as
-possible.</p></div>
-<div class="paragraph"><p>You do not need to handle HEAD requests specifically as
-Cowboy will ensure no data is sent when you call this function.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Data
-</dt>
-<dd>
-<p>
-The data to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin
-</dt>
-<dd>
-<p>
-A flag indicating whether this is the final piece of data
-to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>chunk/2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Stream the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:stream_body - Stream the response body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> + +<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() +<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div> +<div class="paragraph"><p>Stream the response body.</p></div> +<div class="paragraph"><p>This function may be called as many times as needed after +initiating a response using the +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a> +function.</p></div> +<div class="paragraph"><p>The second argument indicates if this call is the final +call. Use the <code>nofin</code> value until you know no more data +will be sent. The final call should use <code>fin</code> (possibly +with an empty data value).</p></div> +<div class="paragraph"><p>Note that not using <code>fin</code> for the final call is not an +error; Cowboy will take care of it when the request +handler terminates if needed. Depending on the resource +it may however be more efficient to do it as early as +possible.</p></div> +<div class="paragraph"><p>You do not need to handle HEAD requests specifically as +Cowboy will ensure no data is sent when you call this function.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Data +</dt> +<dd> +<p> +The data to be sent. +</p> +</dd> +<dt class="hdlist1"> +IsFin +</dt> +<dd> +<p> +A flag indicating whether this is the final piece of data +to be sent. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>chunk/2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Stream the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html index 0c3dc711..a2b9bef1 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:stream_reply(3)</title> @@ -67,148 +67,148 @@ <h1 class="lined-header"><span>cowboy_req:stream_reply(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:stream_reply - Send the response headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>)
-
-<span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>()
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Send the response headers.</p></div>
-<div class="paragraph"><p>The header names must be given as lowercase binary strings.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may overwrite those set by <code>set_resp_header/3</code>.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-<div class="paragraph"><p>If a response body was set before calling this function,
-it will not be sent.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a>
-to stream the response body.</p></div>
-<div class="paragraph"><p>You may want to set the content-length header when using
-this function, if it is known in advance. This will allow
-clients using HTTP/2 and HTTP/1.0 to process the response
-more efficiently.</p></div>
-<div class="paragraph"><p>The streaming method varies depending on the protocol being
-used. HTTP/2 will use the usual DATA frames. HTTP/1.1 will
-use chunked transfer-encoding. HTTP/1.0 will send the body
-unmodified and close the connection at the end if no
-content-length was set.</p></div>
-<div class="paragraph"><p>It is not possible to push resources after this function
-returns. Any attempt will result in an error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Status
-</dt>
-<dd>
-<p>
-The status code for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-The response headers.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward
-in order to be able to stream the response body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>chunked_reply/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Initiate the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Stream the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a>,
-<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:stream_reply - Send the response headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>) + +<span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>() +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Send the response headers.</p></div> +<div class="paragraph"><p>The header names must be given as lowercase binary strings. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may overwrite those set by <code>set_resp_header/3</code>.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +<div class="paragraph"><p>If a response body was set before calling this function, +it will not be sent.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a> +to stream the response body.</p></div> +<div class="paragraph"><p>You may want to set the content-length header when using +this function, if it is known in advance. This will allow +clients using HTTP/2 and HTTP/1.0 to process the response +more efficiently.</p></div> +<div class="paragraph"><p>The streaming method varies depending on the protocol being +used. HTTP/2 will use the usual DATA frames. HTTP/1.1 will +use chunked transfer-encoding. HTTP/1.0 will send the body +unmodified and close the connection at the end if no +content-length was set.</p></div> +<div class="paragraph"><p>It is not possible to push resources after this function +returns. Any attempt will result in an error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Status +</dt> +<dd> +<p> +The status code for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +The response headers. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward +in order to be able to stream the response body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>chunked_reply/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Initiate the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Stream the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a>, +<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html index dcfc1bd2..98e3e2b2 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:uri(3)</title> @@ -67,177 +67,177 @@ <h1 class="lined-header"><span>cowboy_req:uri(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:uri - Reconstructed URI</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span>, #{})
-<span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">fragment</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>
-}</tt></pre></div></div>
-<div class="paragraph"><p>Reconstruct the effective request URI, optionally modifying components.</p></div>
-<div class="paragraph"><p>By default Cowboy will build a URI using the components found
-in the request. Options allow disabling or replacing individual
-components.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-Map for overriding individual components.
-</p>
-<div class="paragraph"><p>To replace a component, provide its new value as a binary
-string or an iolist. To disable a component, set its value
-to <code>undefined</code>.</p></div>
-<div class="paragraph"><p>As this function always returns a valid URI, there are some
-things to note:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Disabling the host also disables the scheme and port.
-</p>
-</li>
-<li>
-<p>
-There is no fragment component by default as these are
- not sent with the request.
-</p>
-</li>
-<li>
-<p>
-The port number may not appear in the resulting URI if
- it is the default port for the given scheme (http: 80; https: 443).
-</p>
-</li>
-</ul></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The reconstructed URI is returned as an iolist or a binary string.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Individual components can be replaced or disabled.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Only the URI is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>host_url/1</code> and <code>url/1</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>With an effective request URI <a href="http://example.org/path/to/res?edit=1">http://example.org/path/to/res?edit=1</a>
-we can have:</p></div>
-<div class="listingblock">
-<div class="title">Protocol relative form</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-style: italic"><span style="color: #9A1900">%% //example.org/path/to/res?edit=1</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Serialized origin for use in the origin header</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>, <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">HTTP/1.1 origin form (path and query string only)</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-style: italic"><span style="color: #9A1900">%% /path/to/res?edit=1</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Add a fragment to the URI</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1#errors</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">fragment</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"errors"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Ensure the scheme is HTTPS</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">https://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"https"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Convert the URI to a binary string</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">iolist_to_binary</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>))<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a>,
-<a href="../cowboy_req.host">cowboy_req:host(3)</a>,
-<a href="../cowboy_req.port">cowboy_req:port(3)</a>,
-<a href="../cowboy_req.path">cowboy_req:path(3)</a>,
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:uri - Reconstructed URI</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span>, #{}) +<span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">fragment</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span> +}</tt></pre></div></div> +<div class="paragraph"><p>Reconstruct the effective request URI, optionally modifying components.</p></div> +<div class="paragraph"><p>By default Cowboy will build a URI using the components found +in the request. Options allow disabling or replacing individual +components.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +Map for overriding individual components. +</p> +<div class="paragraph"><p>To replace a component, provide its new value as a binary +string or an iolist. To disable a component, set its value +to <code>undefined</code>.</p></div> +<div class="paragraph"><p>As this function always returns a valid URI, there are some +things to note:</p></div> +<div class="ulist"><ul> +<li> +<p> +Disabling the host also disables the scheme and port. +</p> +</li> +<li> +<p> +There is no fragment component by default as these are + not sent with the request. +</p> +</li> +<li> +<p> +The port number may not appear in the resulting URI if + it is the default port for the given scheme (http: 80; https: 443). +</p> +</li> +</ul></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The reconstructed URI is returned as an iolist or a binary string.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Individual components can be replaced or disabled. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Only the URI is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>host_url/1</code> and <code>url/1</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="paragraph"><p>With an effective request URI <a href="http://example.org/path/to/res?edit=1">http://example.org/path/to/res?edit=1</a> +we can have:</p></div> +<div class="listingblock"> +<div class="title">Protocol relative form</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-style: italic"><span style="color: #9A1900">%% //example.org/path/to/res?edit=1</span></span> +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Serialized origin for use in the origin header</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org</span></span> +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>, <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">HTTP/1.1 origin form (path and query string only)</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-style: italic"><span style="color: #9A1900">%% /path/to/res?edit=1</span></span> +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Add a fragment to the URI</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1#errors</span></span> +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">fragment</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"errors"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Ensure the scheme is HTTPS</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-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">https://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1</span></span> +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>, #{<span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"https"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Convert the URI to a binary string</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">iolist_to_binary</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_req:uri</span></span>(<span style="color: #009900">Req</span>))<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a>, +<a href="../cowboy_req.host">cowboy_req:host(3)</a>, +<a href="../cowboy_req.port">cowboy_req:port(3)</a>, +<a href="../cowboy_req.path">cowboy_req:path(3)</a>, +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html index 4fb572fa..313b06af 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:version(3)</title> @@ -67,88 +67,88 @@ <h1 class="lined-header"><span>cowboy_req:version(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:version - HTTP version</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">version</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Version</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the HTTP version used for the request.</p></div>
-<div class="paragraph"><p>The version can also be obtained using pattern matching:</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="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="color: #009900">Version</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP version used for the request is returned as an
-atom. It is provided for informative purposes only.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the version is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the HTTP version</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">Version</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:version</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:version - HTTP version</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">version</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Version</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the HTTP version used for the request.</p></div> +<div class="paragraph"><p>The version can also be obtained using pattern matching:</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="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="color: #009900">Version</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP version used for the request is returned as an +atom. It is provided for informative purposes only.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the version is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the HTTP version</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">Version</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:version</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req/index.html b/docs/en/cowboy/2.0/manual/cowboy_req/index.html index a9965645..b04c65d5 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req(3)</title> @@ -67,389 +67,389 @@ <h1 class="lined-header"><span>cowboy_req(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req - HTTP request and response</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_req</code> provides functions to access, manipulate
-and respond to requests.</p></div>
-<div class="paragraph"><p>There are four types of functions in this module. They can be
-differentiated by their name and their return type:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Type </th>
-<th align="left" valign="top"> Name pattern </th>
-<th align="left" valign="top"> Return type</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">access</p></td>
-<td align="left" valign="top"><p class="table">no verb, parse_*, match_*</p></td>
-<td align="left" valign="top"><p class="table"><code>Value</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">question</p></td>
-<td align="left" valign="top"><p class="table">has_*</p></td>
-<td align="left" valign="top"><p class="table"><code>boolean()</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">modification</p></td>
-<td align="left" valign="top"><p class="table">set_*</p></td>
-<td align="left" valign="top"><p class="table"><code>Req</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">action</p></td>
-<td align="left" valign="top"><p class="table">any other verb</p></td>
-<td align="left" valign="top"><p class="table"><code>ok | {Result, Value, Req}</code></p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>Any <code>Req</code> returned must be used in place of the one passed as
-argument. Functions that perform an action in particular write
-state in the Req object to make sure you are using the function
-correctly. For example, it’s only possible to send one response,
-and to read the body once.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Raw request:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.method">cowboy_req:method(3)</a> - HTTP method
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.version">cowboy_req:version(3)</a> - HTTP version
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a> - URI scheme
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.host">cowboy_req:host(3)</a> - URI host name
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.port">cowboy_req:port(3)</a> - URI port number
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.path">cowboy_req:path(3)</a> - URI path
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a> - URI query string
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.uri">cowboy_req:uri(3)</a> - Reconstructed URI
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.header">cowboy_req:header(3)</a> - HTTP header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.headers">cowboy_req:headers(3)</a> - HTTP headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.peer">cowboy_req:peer(3)</a> - Peer address and port
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Processed request:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a> - Parse the query string
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a> - Match the query string against constraints
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a> - Parse the given HTTP header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a> - Parse cookie headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a> - Match cookies against constraints
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a> - Access a value bound from the route
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a> - Access all values bound from the route
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a> - Access the route’s heading host segments
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a> - Access the route’s trailing path segments
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Request body:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a> - Is there a request body?
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a> - Body length
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> - Read the request body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a> - Read and parse a urlencoded request body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a> - Read the next multipart headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a> - Read the current part’s body
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Response:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> - Set a cookie
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> - Set a response header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a> - Set several response headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a> - Is the given response header set?
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a> - Response header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a> - Response headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a> - Delete a response header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a> - Set the response body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.has_resp_body">cowboy_req:has_resp_body(3)</a> - Is there a response body?
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a> - Send the response
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a> - Send the response headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a> - Stream the response body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.push">cowboy_req:push(3)</a> - Push a resource to the client
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_push_opts">push_opts()</h3>
-<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: #000000">push_opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-}</tt></pre></div></div>
-<div class="paragraph"><p>Push options.</p></div>
-<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string,
-and take the scheme, host and port directly from the current
-request’s URI.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_read_body_opts">read_body_opts()</h3>
-<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: #000000">read_body_opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()
-}</tt></pre></div></div>
-<div class="paragraph"><p>Body reading options.</p></div>
-<div class="paragraph"><p>The defaults are function-specific.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_req">req()</h3>
-<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: #000000">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(),
- <span style="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(),
- <span style="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
-}</tt></pre></div></div>
-<div class="paragraph"><p>The Req object.</p></div>
-<div class="paragraph"><p>Contains information about the request and response. While
-some fields are publicly documented, others aren’t and shouldn’t
-be used.</p></div>
-<div class="paragraph"><p>You may add custom fields if required. Make sure to namespace
-them by prepending an underscore and the name of your application:</p></div>
-<div class="listingblock">
-<div class="title">Setting a custom field</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">Req</span>#{<span style="color: #009900">_myapp_auth_method</span> <span style="color: #990000">=></span> <span style="color: #FF6600">pubkey</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_resp_body">resp_body()</h3>
-<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: #000000">resp_body</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
- | {<span style="color: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>}
-
-<span style="color: #009900">Offset</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()
-<span style="color: #009900">Length</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()
-<span style="color: #009900">Filename</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:name_all</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Response body.</p></div>
-<div class="paragraph"><p>It can take two forms: the actual data to be sent or a
-tuple indicating which file to send.</p></div>
-<div class="paragraph"><p>When sending data directly, the type is either a binary or
-an iolist. Iolists are an efficient way to build output.
-Instead of concatenating strings or binaries, you can simply
-build a list containing the fragments you want to send in the
-order they should be sent:</p></div>
-<div class="listingblock">
-<div class="title">Example iolists usage</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="color: #009900">RespBody</span> <span style="color: #990000">=</span> [<span style="color: #FF0000">"Hello "</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">$!</span>]]<span style="color: #990000">.</span>
-[<span style="color: #FF0000">"Hello "</span>,[<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>,<span style="color: #993399">33</span>]]
-<span style="color: #993399">2</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">RespBody</span>])<span style="color: #990000">.</span>
-<span style="color: #009900">Hello</span> <span style="color: #FF6600">world</span><span style="color: #990000">!</span></tt></pre></div></div>
-<div class="paragraph"><p>When using the sendfile tuple, the <code>Length</code> value is mandatory
-and must be higher than 0. It is sent with the response in the
-content-length header.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req - HTTP request and response</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_req</code> provides functions to access, manipulate +and respond to requests.</p></div> +<div class="paragraph"><p>There are four types of functions in this module. They can be +differentiated by their name and their return type:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="33%" /> +<col width="33%" /> +<col width="33%" /> +<thead> +<tr> +<th align="left" valign="top"> Type </th> +<th align="left" valign="top"> Name pattern </th> +<th align="left" valign="top"> Return type</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">access</p></td> +<td align="left" valign="top"><p class="table">no verb, parse_*, match_*</p></td> +<td align="left" valign="top"><p class="table"><code>Value</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">question</p></td> +<td align="left" valign="top"><p class="table">has_*</p></td> +<td align="left" valign="top"><p class="table"><code>boolean()</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">modification</p></td> +<td align="left" valign="top"><p class="table">set_*</p></td> +<td align="left" valign="top"><p class="table"><code>Req</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">action</p></td> +<td align="left" valign="top"><p class="table">any other verb</p></td> +<td align="left" valign="top"><p class="table"><code>ok | {Result, Value, Req}</code></p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>Any <code>Req</code> returned must be used in place of the one passed as +argument. Functions that perform an action in particular write +state in the Req object to make sure you are using the function +correctly. For example, it’s only possible to send one response, +and to read the body once.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Raw request:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.method">cowboy_req:method(3)</a> - HTTP method +</p> +</li> +<li> +<p> +<a href="../cowboy_req.version">cowboy_req:version(3)</a> - HTTP version +</p> +</li> +<li> +<p> +<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a> - URI scheme +</p> +</li> +<li> +<p> +<a href="../cowboy_req.host">cowboy_req:host(3)</a> - URI host name +</p> +</li> +<li> +<p> +<a href="../cowboy_req.port">cowboy_req:port(3)</a> - URI port number +</p> +</li> +<li> +<p> +<a href="../cowboy_req.path">cowboy_req:path(3)</a> - URI path +</p> +</li> +<li> +<p> +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a> - URI query string +</p> +</li> +<li> +<p> +<a href="../cowboy_req.uri">cowboy_req:uri(3)</a> - Reconstructed URI +</p> +</li> +<li> +<p> +<a href="../cowboy_req.header">cowboy_req:header(3)</a> - HTTP header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.headers">cowboy_req:headers(3)</a> - HTTP headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.peer">cowboy_req:peer(3)</a> - Peer address and port +</p> +</li> +</ul></div> +<div class="paragraph"><p>Processed request:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a> - Parse the query string +</p> +</li> +<li> +<p> +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a> - Match the query string against constraints +</p> +</li> +<li> +<p> +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a> - Parse the given HTTP header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a> - Parse cookie headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a> - Match cookies against constraints +</p> +</li> +<li> +<p> +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a> - Access a value bound from the route +</p> +</li> +<li> +<p> +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a> - Access all values bound from the route +</p> +</li> +<li> +<p> +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a> - Access the route’s heading host segments +</p> +</li> +<li> +<p> +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a> - Access the route’s trailing path segments +</p> +</li> +</ul></div> +<div class="paragraph"><p>Request body:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a> - Is there a request body? +</p> +</li> +<li> +<p> +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a> - Body length +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> - Read the request body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a> - Read and parse a urlencoded request body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a> - Read the next multipart headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a> - Read the current part’s body +</p> +</li> +</ul></div> +<div class="paragraph"><p>Response:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> - Set a cookie +</p> +</li> +<li> +<p> +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> - Set a response header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a> - Set several response headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a> - Is the given response header set? +</p> +</li> +<li> +<p> +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a> - Response header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a> - Response headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a> - Delete a response header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a> - Set the response body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.has_resp_body">cowboy_req:has_resp_body(3)</a> - Is there a response body? +</p> +</li> +<li> +<p> +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a> - Send the response +</p> +</li> +<li> +<p> +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a> - Send the response headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a> - Stream the response body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.push">cowboy_req:push(3)</a> - Push a resource to the client +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_push_opts">push_opts()</h3> +<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: #000000">push_opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +}</tt></pre></div></div> +<div class="paragraph"><p>Push options.</p></div> +<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string, +and take the scheme, host and port directly from the current +request’s URI.</p></div> +</div> +<div class="sect2"> +<h3 id="_read_body_opts">read_body_opts()</h3> +<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: #000000">read_body_opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() +}</tt></pre></div></div> +<div class="paragraph"><p>Body reading options.</p></div> +<div class="paragraph"><p>The defaults are function-specific.</p></div> +</div> +<div class="sect2"> +<h3 id="_req">req()</h3> +<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: #000000">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), + <span style="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), + <span style="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} +}</tt></pre></div></div> +<div class="paragraph"><p>The Req object.</p></div> +<div class="paragraph"><p>Contains information about the request and response. While +some fields are publicly documented, others aren’t and shouldn’t +be used.</p></div> +<div class="paragraph"><p>You may add custom fields if required. Make sure to namespace +them by prepending an underscore and the name of your application:</p></div> +<div class="listingblock"> +<div class="title">Setting a custom field</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">Req</span>#{<span style="color: #009900">_myapp_auth_method</span> <span style="color: #990000">=></span> <span style="color: #FF6600">pubkey</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_resp_body">resp_body()</h3> +<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: #000000">resp_body</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() + | {<span style="color: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>} + +<span style="color: #009900">Offset</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">Length</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">Filename</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:name_all</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Response body.</p></div> +<div class="paragraph"><p>It can take two forms: the actual data to be sent or a +tuple indicating which file to send.</p></div> +<div class="paragraph"><p>When sending data directly, the type is either a binary or +an iolist. Iolists are an efficient way to build output. +Instead of concatenating strings or binaries, you can simply +build a list containing the fragments you want to send in the +order they should be sent:</p></div> +<div class="listingblock"> +<div class="title">Example iolists usage</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="color: #009900">RespBody</span> <span style="color: #990000">=</span> [<span style="color: #FF0000">"Hello "</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">$!</span>]]<span style="color: #990000">.</span> +[<span style="color: #FF0000">"Hello "</span>,[<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>,<span style="color: #993399">33</span>]] +<span style="color: #993399">2</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">RespBody</span>])<span style="color: #990000">.</span> +<span style="color: #009900">Hello</span> <span style="color: #FF6600">world</span><span style="color: #990000">!</span></tt></pre></div></div> +<div class="paragraph"><p>Note that the length must be greater than zero for any data +to be sent. Cowboy will send an empty body when the length +is zero.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html index 174f8d53..cca510c5 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_rest(3)</title> @@ -67,641 +67,641 @@ <h1 class="lined-header"><span>cowboy_rest(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_rest - REST handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_rest</code> implements the HTTP state machine.</p></div>
-<div class="paragraph"><p>Implementing REST handlers is not enough to provide a REST
-interface; this interface must also follow the REST
-constraints including HATEOAS (hypermedia as the engine
-of application state).</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>REST handlers implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Callback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
- <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}
-
-<span style="color: #009900">Callback</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span>
-<span style="color: #009900">Result</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch
-to the REST handler behavior, it must return <code>cowboy_rest</code>
-as the first element of the tuple.</p></div>
-<div class="paragraph"><p>The <code>Callback/2</code> above represents all the REST-specific
-callbacks. They are described in the following section
-of this manual. REST-specific callbacks differ by their
-name, semantics, result and default values. The default
-value is the one used when the callback has not been
-implemented. They otherwise all follow the same interface.</p></div>
-<div class="paragraph"><p>The <code>stop</code> tuple can be returned to stop REST processing.
-If no response was sent before then, Cowboy will send a
-<em>204 No Content</em>.</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the handler.
-Cowboy will terminate the process right after this. There
-is no need to perform any cleanup in this callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-normal
-</dt>
-<dd>
-<p>
- The handler terminated normally.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest_callbacks">REST callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_acceptcallback">AcceptCallback</h3>
-<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="color: #009900">AcceptCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>}
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div>
-<div class="paragraph"><p>Process the request body.</p></div>
-<div class="paragraph"><p>This function should create or update the resource using the
-request body.</p></div>
-<div class="paragraph"><p>For PUT requests, the body is a representation of the resource
-that is being created or replaced.</p></div>
-<div class="paragraph"><p>For POST requests, the body is typically application-specific
-instructions on how to process the request, but it may also
-be a representation of the resource. When creating a new
-resource with POST at a different location, return <code>{true, URI}</code>
-with <code>URI</code> the new location.</p></div>
-<div class="paragraph"><p>For PATCH requests, the body is a series of instructions on
-how to update the resource. Patch files or JSON Patch are
-examples of such media types.</p></div>
-<div class="paragraph"><p>A response body may be sent. The appropriate media type, charset
-and language for the response can be retrieved from the Req
-object using the <code>media_type</code>, <code>charset</code> and <code>language</code> keys,
-respectively. The body can be set using
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_allowed_methods">allowed_methods</h3>
-<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: #000000">allowed_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> [<span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of allowed methods.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_allow_missing_post">allow_missing_post</h3>
-<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: #000000">allow_missing_post</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether POST is allowed when the resource doesn’t exist.</p></div>
-<div class="paragraph"><p>Returning <code>true</code> here means that a new resource will be
-created. The URI for the newly created resource should be
-returned from the <code>AcceptCallback</code> function.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_charsets_provided">charsets_provided</h3>
-<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: #000000">charsets_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the list of charsets the resource provides in order
-of preference.</p></div>
-<div class="paragraph"><p>During content negotiation Cowboy will pick the most
-appropriate charset for the client. The client advertises
-charsets it prefers with the accept-charset header. When
-that header is missing, Cowboy picks the first charset
-from the resource.</p></div>
-<div class="paragraph"><p>Cowboy will add the negotiated <code>charset</code> to the Req object
-after this step completes:</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: #000000">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">charset</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_content_types_accepted">content_types_accepted</h3>
-<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: #000000">content_types_accepted</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">AcceptCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]
-
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the list of media types the resource accepts in
-order of preference.</p></div>
-<div class="paragraph"><p>A media type is made of different parts. The media type
-<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code>
-and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div>
-<div class="paragraph"><p>Cowboy will match the content-type request header against
-the media types the server accepts and select the appropriate
-callback. When that header is missing, or when the server does not
-accept this media type, the request fails and an error response
-is returned. Cowboy will execute the callback immediately otherwise.</p></div>
-<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be
-accepted. When any parameter is acceptable, the tuple form
-should be used with parameters as the atom <code>'*'</code>.</p></div>
-<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the
-<code>charset</code> parameter, which is known to be case insensitive. You
-should therefore always provide the charset as a lowercase
-binary string.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_content_types_provided">content_types_provided</h3>
-<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: #000000">content_types_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">ProvideCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]
-
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"html"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">'*'</span>}, <span style="color: #FF6600">to_html</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of media types the resource provides in
-order of preference.</p></div>
-<div class="paragraph"><p>A media type is made of different parts. The media type
-<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code>
-and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div>
-<div class="paragraph"><p>During content negotiation Cowboy will pick the most appropriate
-media type for the client. The client advertises media types it
-prefers with the accept header. When that header is missing,
-the content negotiation fails and an error response is returned.</p></div>
-<div class="paragraph"><p>The callback given for the selected media type will be called
-at the end of the execution of GET and HEAD requests when a
-representation must be sent to the client.</p></div>
-<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be
-accepted. When any parameter is acceptable, the tuple form
-should be used with parameters as the atom <code>'*'</code>.</p></div>
-<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the
-<code>charset</code> parameter, which is known to be case insensitive. You
-should therefore always provide the charset as a lowercase
-binary string.</p></div>
-<div class="paragraph"><p>Cowboy will add the negotiated <code>media_type</code> to the Req object
-after this step completes:</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: #000000">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">media_type</span> <span style="color: #990000">=></span> <span style="color: #009900">ParsedMime</span>
-}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_completed">delete_completed</h3>
-<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: #000000">delete_completed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource has been fully deleted from the
-system, including from any internal cache.</p></div>
-<div class="paragraph"><p>Returning <code>false</code> will result in a <em>202 Accepted</em> response
-being sent instead of a <em>200 OK</em> or <em>204 No Content</em>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_resource">delete_resource</h3>
-<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: #000000">delete_resource</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Delete the resource.</p></div>
-<div class="paragraph"><p>Cowboy will send an error response when this function
-returns <code>false</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_expires">expires</h3>
-<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: #000000">expires</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">undefined</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">undefined</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the resource’s expiration date.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_forbidden">forbidden</h3>
-<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: #000000">forbidden</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether access to the resource is forbidden.</p></div>
-<div class="paragraph"><p>A <em>403 Forbidden</em> response will be sent if this
-function returns <code>true</code>. This status code means that
-access is forbidden regardless of authentication,
-and that the request shouldn’t be repeated.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_generate_etag">generate_etag</h3>
-<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: #000000">generate_etag</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | {<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">etag</span> <span style="color: #FF6600">value</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the entity tag of the resource.</p></div>
-<div class="paragraph"><p>When a binary is returned, the value is automatically
-parsed to a tuple. The binary must be in the same
-format as the etag header, including quotes.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_is_authorized">is_authorized</h3>
-<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: #000000">is_authorized</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">false</span>, <span style="color: #009900">AuthHeader</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the user is authorized to perform the action.</p></div>
-<div class="paragraph"><p>This function should be used to perform any necessary
-authentication of the user before attempting to perform
-any action on the resource.</p></div>
-<div class="paragraph"><p>When authentication fails, the <code>AuthHeader</code> value will
-be sent in the www-authenticate header for the
-<em>401 Unauthorized</em> response.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_is_conflict">is_conflict</h3>
-<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: #000000">is_conflict</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the PUT request results in a conflict.</p></div>
-<div class="paragraph"><p>A <em>409 Conflict</em> response is sent when <code>true</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_known_methods">known_methods</h3>
-<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: #000000">known_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> [<span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"PUT"</span><span style="color: #990000">>></span>,
- <span style="color: #990000"><<</span><span style="color: #FF0000">"PATCH"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"DELETE"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of known methods.</p></div>
-<div class="paragraph"><p>The full list of methods known by the server should be
-returned, regardless of their use in the resource.</p></div>
-<div class="paragraph"><p>The default value lists the methods Cowboy knows and
-implement in <code>cowboy_rest</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_languages_provided">languages_provided</h3>
-<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: #000000">languages_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the list of languages the resource provides in order
-of preference.</p></div>
-<div class="paragraph"><p>During content negotiation Cowboy will pick the most
-appropriate language for the client. The client advertises
-languages it prefers with the accept-language header. When
-that header is missing, Cowboy picks the first language
-from the resource.</p></div>
-<div class="paragraph"><p>Cowboy will add the negotiated <code>language</code> to the Req object
-after this step completes:</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: #000000">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">language</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_last_modified">last_modified</h3>
-<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: #000000">last_modified</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">last</span> <span style="color: #FF6600">modified</span> <span style="color: #FF6600">value</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the resource’s last modification date.</p></div>
-<div class="paragraph"><p>This date will be used to test against the if-modified-since
-and if-unmodified-since headers, and sent as the last-modified
-header in the response to GET and HEAD requests.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_malformed_request">malformed_request</h3>
-<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: #000000">malformed_request</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the request is malformed.</p></div>
-<div class="paragraph"><p>A request is malformed when a component required by the
-resource is invalid. This may include the query string
-or individual headers. They should be parsed and validated
-in this function. The body should not be read at this point.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_moved_permanently">moved_permanently</h3>
-<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: #000000">moved_permanently</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource was permanently moved, and
-what its new location is.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_moved_temporarily">moved_temporarily</h3>
-<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: #000000">moved_temporarily</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource was temporarily moved, and
-what its new location is.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_multiple_choices">multiple_choices</h3>
-<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: #000000">multiple_choices</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the client should engage in reactive
-negotiation.</p></div>
-<div class="paragraph"><p>Return <code>true</code> when the server has multiple representations
-of a resource, each with their specific identifier, but is
-unable to determine which is best for the client. For
-example an image might have different sizes and the server
-is unable to determine the capabilities of the client.</p></div>
-<div class="paragraph"><p>When returning <code>true</code> the server should send a body with
-links to the different representations. If the server has
-a preferred representation it can send its link inside a
-location header.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options">options</h3>
-<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: #000000">options</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}</tt></pre></div></div>
-<div class="paragraph"><p>Respond to an OPTIONS request.</p></div>
-<div class="paragraph"><p>The response should inform the client the communication
-options available for this resource. By default Cowboy
-will send a <em>200 OK</em> response with the allow header set.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_previously_existed">previously_existed</h3>
-<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: #000000">previously_existed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource existed previously.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_providecallback">ProvideCallback</h3>
-<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="color: #009900">ProvideCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the response body.</p></div>
-<div class="paragraph"><p>The response body can be provided either as the actual data
-to be sent or a tuple indicating which file to send.</p></div>
-<div class="paragraph"><p>This function is called for both GET and HEAD requests. For
-the latter the body is not sent, however.</p></div>
-<div class="paragraph"><p>Note that there used to be a way to stream the response body.
-It was temporarily removed and will be added back in a later
-release.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_resource_exists">resource_exists</h3>
-<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: #000000">resource_exists</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource exists.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_service_available">service_available</h3>
-<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: #000000">service_available</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the service is available.</p></div>
-<div class="paragraph"><p>A <em>503 Service Unavailable</em> response will be sent when this
-function returns <code>false</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_uri_too_long">uri_too_long</h3>
-<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: #000000">uri_too_long</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the requested URI is too long.</p></div>
-<div class="paragraph"><p>This function can be used to further restrict the length
-of the URI for this specific resource.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_valid_content_headers">valid_content_headers</h3>
-<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: #000000">valid_content_headers</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the content headers are valid.</p></div>
-<div class="paragraph"><p>This callback can be used to reject requests that have
-invalid content header values, for example an unsupported
-content-encoding.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_valid_entity_length">valid_entity_length</h3>
-<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: #000000">valid_entity_length</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the request body length is within acceptable boundaries.</p></div>
-<div class="paragraph"><p>A <em>413 Request Entity Too Large</em> response will be sent if this
-function returns <code>false</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_variances">variances</h3>
-<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: #000000">variances</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> []</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of request headers that affect the
-representation of the resource.</p></div>
-<div class="paragraph"><p>Cowboy automatically adds the accept, accept-charset and
-accept-language headers when necessary.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_handler">cowboy_handler(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_rest - REST handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_rest</code> implements the HTTP state machine.</p></div> +<div class="paragraph"><p>Implementing REST handlers is not enough to provide a REST +interface; this interface must also follow the REST +constraints including HATEOAS (hypermedia as the engine +of application state).</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>REST handlers implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Callback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) + <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()} + +<span style="color: #009900">Callback</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span> +<span style="color: #009900">Result</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span> +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch +to the REST handler behavior, it must return <code>cowboy_rest</code> +as the first element of the tuple.</p></div> +<div class="paragraph"><p>The <code>Callback/2</code> above represents all the REST-specific +callbacks. They are described in the following section +of this manual. REST-specific callbacks differ by their +name, semantics, result and default values. The default +value is the one used when the callback has not been +implemented. They otherwise all follow the same interface.</p></div> +<div class="paragraph"><p>The <code>stop</code> tuple can be returned to stop REST processing. +If no response was sent before then, Cowboy will send a +<em>204 No Content</em>.</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +normal +</dt> +<dd> +<p> + The handler terminated normally. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rest_callbacks">REST callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_acceptcallback">AcceptCallback</h3> +<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="color: #009900">AcceptCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>} +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div> +<div class="paragraph"><p>Process the request body.</p></div> +<div class="paragraph"><p>This function should create or update the resource using the +request body.</p></div> +<div class="paragraph"><p>For PUT requests, the body is a representation of the resource +that is being created or replaced.</p></div> +<div class="paragraph"><p>For POST requests, the body is typically application-specific +instructions on how to process the request, but it may also +be a representation of the resource. When creating a new +resource with POST at a different location, return <code>{true, URI}</code> +with <code>URI</code> the new location.</p></div> +<div class="paragraph"><p>For PATCH requests, the body is a series of instructions on +how to update the resource. Patch files or JSON Patch are +examples of such media types.</p></div> +<div class="paragraph"><p>A response body may be sent. The appropriate media type, charset +and language for the response can be retrieved from the Req +object using the <code>media_type</code>, <code>charset</code> and <code>language</code> keys, +respectively. The body can be set using +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>.</p></div> +</div> +<div class="sect2"> +<h3 id="_allowed_methods">allowed_methods</h3> +<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: #000000">allowed_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> [<span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div> +<div class="paragraph"><p>Return the list of allowed methods.</p></div> +</div> +<div class="sect2"> +<h3 id="_allow_missing_post">allow_missing_post</h3> +<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: #000000">allow_missing_post</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether POST is allowed when the resource doesn’t exist.</p></div> +<div class="paragraph"><p>Returning <code>true</code> here means that a new resource will be +created. The URI for the newly created resource should be +returned from the <code>AcceptCallback</code> function.</p></div> +</div> +<div class="sect2"> +<h3 id="_charsets_provided">charsets_provided</h3> +<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: #000000">charsets_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div> +<div class="paragraph"><p>Return the list of charsets the resource provides in order +of preference.</p></div> +<div class="paragraph"><p>During content negotiation Cowboy will pick the most +appropriate charset for the client. The client advertises +charsets it prefers with the accept-charset header. When +that header is missing, Cowboy picks the first charset +from the resource.</p></div> +<div class="paragraph"><p>Cowboy will add the negotiated <code>charset</code> to the Req object +after this step completes:</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: #000000">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">charset</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_content_types_accepted">content_types_accepted</h3> +<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: #000000">content_types_accepted</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">AcceptCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}] +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}] + +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div> +<div class="paragraph"><p>Return the list of media types the resource accepts in +order of preference.</p></div> +<div class="paragraph"><p>A media type is made of different parts. The media type +<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code> +and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div> +<div class="paragraph"><p>Cowboy will match the content-type request header against +the media types the server accepts and select the appropriate +callback. When that header is missing, or when the server does not +accept this media type, the request fails and an error response +is returned. Cowboy will execute the callback immediately otherwise.</p></div> +<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be +accepted. When any parameter is acceptable, the tuple form +should be used with parameters as the atom <code>'*'</code>.</p></div> +<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the +<code>charset</code> parameter, which is known to be case insensitive. You +should therefore always provide the charset as a lowercase +binary string.</p></div> +</div> +<div class="sect2"> +<h3 id="_content_types_provided">content_types_provided</h3> +<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: #000000">content_types_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">ProvideCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}] +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}] + +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"html"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">'*'</span>}, <span style="color: #FF6600">to_html</span>}]</tt></pre></div></div> +<div class="paragraph"><p>Return the list of media types the resource provides in +order of preference.</p></div> +<div class="paragraph"><p>A media type is made of different parts. The media type +<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code> +and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div> +<div class="paragraph"><p>During content negotiation Cowboy will pick the most appropriate +media type for the client. The client advertises media types it +prefers with the accept header. When that header is missing, +the content negotiation fails and an error response is returned.</p></div> +<div class="paragraph"><p>The callback given for the selected media type will be called +at the end of the execution of GET and HEAD requests when a +representation must be sent to the client.</p></div> +<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be +accepted. When any parameter is acceptable, the tuple form +should be used with parameters as the atom <code>'*'</code>.</p></div> +<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the +<code>charset</code> parameter, which is known to be case insensitive. You +should therefore always provide the charset as a lowercase +binary string.</p></div> +<div class="paragraph"><p>Cowboy will add the negotiated <code>media_type</code> to the Req object +after this step completes:</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: #000000">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">media_type</span> <span style="color: #990000">=></span> <span style="color: #009900">ParsedMime</span> +}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_delete_completed">delete_completed</h3> +<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: #000000">delete_completed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource has been fully deleted from the +system, including from any internal cache.</p></div> +<div class="paragraph"><p>Returning <code>false</code> will result in a <em>202 Accepted</em> response +being sent instead of a <em>200 OK</em> or <em>204 No Content</em>.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_resource">delete_resource</h3> +<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: #000000">delete_resource</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Delete the resource.</p></div> +<div class="paragraph"><p>Cowboy will send an error response when this function +returns <code>false</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_expires">expires</h3> +<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: #000000">expires</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">undefined</span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">undefined</span></tt></pre></div></div> +<div class="paragraph"><p>Return the resource’s expiration date.</p></div> +</div> +<div class="sect2"> +<h3 id="_forbidden">forbidden</h3> +<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: #000000">forbidden</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether access to the resource is forbidden.</p></div> +<div class="paragraph"><p>A <em>403 Forbidden</em> response will be sent if this +function returns <code>true</code>. This status code means that +access is forbidden regardless of authentication, +and that the request shouldn’t be repeated.</p></div> +</div> +<div class="sect2"> +<h3 id="_generate_etag">generate_etag</h3> +<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: #000000">generate_etag</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | {<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">etag</span> <span style="color: #FF6600">value</span></tt></pre></div></div> +<div class="paragraph"><p>Return the entity tag of the resource.</p></div> +<div class="paragraph"><p>When a binary is returned, the value is automatically +parsed to a tuple. The binary must be in the same +format as the etag header, including quotes.</p></div> +</div> +<div class="sect2"> +<h3 id="_is_authorized">is_authorized</h3> +<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: #000000">is_authorized</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">false</span>, <span style="color: #009900">AuthHeader</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the user is authorized to perform the action.</p></div> +<div class="paragraph"><p>This function should be used to perform any necessary +authentication of the user before attempting to perform +any action on the resource.</p></div> +<div class="paragraph"><p>When authentication fails, the <code>AuthHeader</code> value will +be sent in the www-authenticate header for the +<em>401 Unauthorized</em> response.</p></div> +</div> +<div class="sect2"> +<h3 id="_is_conflict">is_conflict</h3> +<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: #000000">is_conflict</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the PUT request results in a conflict.</p></div> +<div class="paragraph"><p>A <em>409 Conflict</em> response is sent when <code>true</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_known_methods">known_methods</h3> +<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: #000000">known_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> [<span style="color: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"PUT"</span><span style="color: #990000">>></span>, + <span style="color: #990000"><<</span><span style="color: #FF0000">"PATCH"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"DELETE"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div> +<div class="paragraph"><p>Return the list of known methods.</p></div> +<div class="paragraph"><p>The full list of methods known by the server should be +returned, regardless of their use in the resource.</p></div> +<div class="paragraph"><p>The default value lists the methods Cowboy knows and +implement in <code>cowboy_rest</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_languages_provided">languages_provided</h3> +<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: #000000">languages_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div> +<div class="paragraph"><p>Return the list of languages the resource provides in order +of preference.</p></div> +<div class="paragraph"><p>During content negotiation Cowboy will pick the most +appropriate language for the client. The client advertises +languages it prefers with the accept-language header. When +that header is missing, Cowboy picks the first language +from the resource.</p></div> +<div class="paragraph"><p>Cowboy will add the negotiated <code>language</code> to the Req object +after this step completes:</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: #000000">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">language</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_last_modified">last_modified</h3> +<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: #000000">last_modified</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">last</span> <span style="color: #FF6600">modified</span> <span style="color: #FF6600">value</span></tt></pre></div></div> +<div class="paragraph"><p>Return the resource’s last modification date.</p></div> +<div class="paragraph"><p>This date will be used to test against the if-modified-since +and if-unmodified-since headers, and sent as the last-modified +header in the response to GET and HEAD requests.</p></div> +</div> +<div class="sect2"> +<h3 id="_malformed_request">malformed_request</h3> +<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: #000000">malformed_request</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the request is malformed.</p></div> +<div class="paragraph"><p>A request is malformed when a component required by the +resource is invalid. This may include the query string +or individual headers. They should be parsed and validated +in this function. The body should not be read at this point.</p></div> +</div> +<div class="sect2"> +<h3 id="_moved_permanently">moved_permanently</h3> +<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: #000000">moved_permanently</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource was permanently moved, and +what its new location is.</p></div> +</div> +<div class="sect2"> +<h3 id="_moved_temporarily">moved_temporarily</h3> +<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: #000000">moved_temporarily</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource was temporarily moved, and +what its new location is.</p></div> +</div> +<div class="sect2"> +<h3 id="_multiple_choices">multiple_choices</h3> +<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: #000000">multiple_choices</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the client should engage in reactive +negotiation.</p></div> +<div class="paragraph"><p>Return <code>true</code> when the server has multiple representations +of a resource, each with their specific identifier, but is +unable to determine which is best for the client. For +example an image might have different sizes and the server +is unable to determine the capabilities of the client.</p></div> +<div class="paragraph"><p>When returning <code>true</code> the server should send a body with +links to the different representations. If the server has +a preferred representation it can send its link inside a +location header.</p></div> +</div> +<div class="sect2"> +<h3 id="_options">options</h3> +<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: #000000">options</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}</tt></pre></div></div> +<div class="paragraph"><p>Respond to an OPTIONS request.</p></div> +<div class="paragraph"><p>The response should inform the client the communication +options available for this resource. By default Cowboy +will send a <em>200 OK</em> response with the allow header set.</p></div> +</div> +<div class="sect2"> +<h3 id="_previously_existed">previously_existed</h3> +<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: #000000">previously_existed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource existed previously.</p></div> +</div> +<div class="sect2"> +<h3 id="_providecallback">ProvideCallback</h3> +<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="color: #009900">ProvideCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div> +<div class="paragraph"><p>Return the response body.</p></div> +<div class="paragraph"><p>The response body can be provided either as the actual data +to be sent or a tuple indicating which file to send.</p></div> +<div class="paragraph"><p>This function is called for both GET and HEAD requests. For +the latter the body is not sent, however.</p></div> +<div class="paragraph"><p>Note that there used to be a way to stream the response body. +It was temporarily removed and will be added back in a later +release.</p></div> +</div> +<div class="sect2"> +<h3 id="_resource_exists">resource_exists</h3> +<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: #000000">resource_exists</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource exists.</p></div> +</div> +<div class="sect2"> +<h3 id="_service_available">service_available</h3> +<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: #000000">service_available</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the service is available.</p></div> +<div class="paragraph"><p>A <em>503 Service Unavailable</em> response will be sent when this +function returns <code>false</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_uri_too_long">uri_too_long</h3> +<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: #000000">uri_too_long</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the requested URI is too long.</p></div> +<div class="paragraph"><p>This function can be used to further restrict the length +of the URI for this specific resource.</p></div> +</div> +<div class="sect2"> +<h3 id="_valid_content_headers">valid_content_headers</h3> +<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: #000000">valid_content_headers</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the content headers are valid.</p></div> +<div class="paragraph"><p>This callback can be used to reject requests that have +invalid content header values, for example an unsupported +content-encoding.</p></div> +</div> +<div class="sect2"> +<h3 id="_valid_entity_length">valid_entity_length</h3> +<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: #000000">valid_entity_length</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the request body length is within acceptable boundaries.</p></div> +<div class="paragraph"><p>A <em>413 Request Entity Too Large</em> response will be sent if this +function returns <code>false</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_variances">variances</h3> +<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: #000000">variances</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> []</tt></pre></div></div> +<div class="paragraph"><p>Return the list of request headers that affect the +representation of the resource.</p></div> +<div class="paragraph"><p>Cowboy automatically adds the accept, accept-charset and +accept-language headers when necessary.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_handler">cowboy_handler(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html b/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html index 58e60685..7987500b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_router:compile(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy_router:compile(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_router:compile - Compile routes to the resources</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000000">compile</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_router:routes</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:dispatch_rules</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Compile routes to the resources.</p></div>
-<div class="paragraph"><p>Takes a human readable list of routes and transforms it
-into a form more efficient to process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Routes
-</dt>
-<dd>
-<p>
-Human readable list of routes.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An opaque dispatch rules value is returned. This value
-must be given to Cowboy as a middleware environment value.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Compile routes and start a listener</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- {<span style="color: #FF6600">'_'</span>, [
- {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []},
- {<span style="color: #FF0000">"/[...], cowboy_static, {priv_dir, my_example_app, ""}}</span>
-<span style="color: #FF0000"> ]}</span>
-<span style="color: #FF0000">]),</span>
-
-<span style="color: #FF0000">{ok, _} = cowboy:start_clear(example, [{port, 8080}], #{</span>
-<span style="color: #FF0000"> env => #{dispatch => Dispatch}</span>
-<span style="color: #FF0000">}).</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_router:compile - Compile routes to the resources</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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: #000000">compile</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_router:routes</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:dispatch_rules</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Compile routes to the resources.</p></div> +<div class="paragraph"><p>Takes a human readable list of routes and transforms it +into a form more efficient to process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Routes +</dt> +<dd> +<p> +Human readable list of routes. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An opaque dispatch rules value is returned. This value +must be given to Cowboy as a middleware environment value.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Compile routes and start a listener</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([ + {<span style="color: #FF6600">'_'</span>, [ + {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []}, + {<span style="color: #FF0000">"/[...], cowboy_static, {priv_dir, my_example_app, ""}}</span> +<span style="color: #FF0000"> ]}</span> +<span style="color: #FF0000">]),</span> + +<span style="color: #FF0000">{ok, _} = cowboy:start_clear(example, [{port, 8080}], #{</span> +<span style="color: #FF0000"> env => #{dispatch => Dispatch}</span> +<span style="color: #FF0000">}).</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_router/index.html b/docs/en/cowboy/2.0/manual/cowboy_router/index.html index 8121066c..3ebdb9e7 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_router/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_router/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_router(3)</title> @@ -67,110 +67,110 @@ <h1 class="lined-header"><span>cowboy_router(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_router - Router middleware</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_router</code> middleware maps the requested host and
-path to the handler to be used for processing the request.</p></div>
-<div class="paragraph"><p>The router takes the <code>dispatch</code> rules as input from the
-middleware environment. Dispatch rules are generated by
-calling the
-<a href="../cowboy_router.compile">cowboy_router:compile(3)</a>
-function.</p></div>
-<div class="paragraph"><p>When a route matches, the router sets the <code>handler</code> and
-<code>handler_opts</code> middleware environment values containing
-the handler module and initial state, respectively.</p></div>
-<div class="paragraph"><p>The router will stop execution when no route matches.
-It will send a 400 response if no host was found, and
-a 404 response otherwise.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_router.compile">cowboy_router:compile(3)</a> - Compile routes to the resources
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_bindings">bindings()</h3>
-<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: #000000">bindings</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Bindings found during routing.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_dispatch_rules">dispatch_rules()</h3>
-<div class="paragraph"><p>Opaque type containing the compiled routes.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_routes">routes()</h3>
-<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: #000000">routes</span></span>() <span style="color: #990000">=</span> [
- {<span style="color: #009900">Host</span>, <span style="color: #009900">PathList</span>} |
- {<span style="color: #009900">Host</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">PathList</span>}
-]
-
-<span style="color: #009900">PathList</span> <span style="color: #990000">::</span> [
- {<span style="color: #009900">Path</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>} |
- {<span style="color: #009900">Path</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}
-]
-
-<span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>()
-<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>()
-<span style="color: #009900">InitialState</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Human readable list of routes to handlers.</p></div>
-<div class="paragraph"><p>Cowboy uses this list to map hosts and paths, optionally
-augmented with constraints applied to the bindings, to
-handler modules.</p></div>
-<div class="paragraph"><p>The syntax for routes is currently defined in the user guide.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_tokens">tokens()</h3>
-<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: #000000">tokens</span></span>() <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]</tt></pre></div></div>
-<div class="paragraph"><p>List of <code>host_info</code> and <code>path_info</code> tokens that were found
-using the <code>...</code> syntax.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_router - Router middleware</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy_router</code> middleware maps the requested host and +path to the handler to be used for processing the request.</p></div> +<div class="paragraph"><p>The router takes the <code>dispatch</code> rules as input from the +middleware environment. Dispatch rules are generated by +calling the +<a href="../cowboy_router.compile">cowboy_router:compile(3)</a> +function.</p></div> +<div class="paragraph"><p>When a route matches, the router sets the <code>handler</code> and +<code>handler_opts</code> middleware environment values containing +the handler module and initial state, respectively.</p></div> +<div class="paragraph"><p>The router will stop execution when no route matches. +It will send a 400 response if no host was found, and +a 404 response otherwise.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_router.compile">cowboy_router:compile(3)</a> - Compile routes to the resources +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_bindings">bindings()</h3> +<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: #000000">bindings</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Bindings found during routing.</p></div> +</div> +<div class="sect2"> +<h3 id="_dispatch_rules">dispatch_rules()</h3> +<div class="paragraph"><p>Opaque type containing the compiled routes.</p></div> +</div> +<div class="sect2"> +<h3 id="_routes">routes()</h3> +<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: #000000">routes</span></span>() <span style="color: #990000">=</span> [ + {<span style="color: #009900">Host</span>, <span style="color: #009900">PathList</span>} | + {<span style="color: #009900">Host</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">PathList</span>} +] + +<span style="color: #009900">PathList</span> <span style="color: #990000">::</span> [ + {<span style="color: #009900">Path</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>} | + {<span style="color: #009900">Path</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>} +] + +<span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() +<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>() +<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>() +<span style="color: #009900">InitialState</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Human readable list of routes to handlers.</p></div> +<div class="paragraph"><p>Cowboy uses this list to map hosts and paths, optionally +augmented with constraints applied to the bindings, to +handler modules.</p></div> +<div class="paragraph"><p>The syntax for routes is currently defined in the user guide.</p></div> +</div> +<div class="sect2"> +<h3 id="_tokens">tokens()</h3> +<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: #000000">tokens</span></span>() <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]</tt></pre></div></div> +<div class="paragraph"><p>List of <code>host_info</code> and <code>path_info</code> tokens that were found +using the <code>...</code> syntax.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_static/index.html b/docs/en/cowboy/2.0/manual/cowboy_static/index.html index b981578b..4630aa10 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_static/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_static/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_static(3)</title> @@ -67,175 +67,175 @@ <h1 class="lined-header"><span>cowboy_static(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_static - Static file handler</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_static</code> implements file serving capabilities
-using the REST semantics provided by <code>cowboy_rest</code>.</p></div>
-<div class="paragraph"><p>The static file handler is a pre-written handler coming with
-Cowboy. To serve files, use it in your routes.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options">Options</h2>
-<div class="sectionbody">
-<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: #000000">opts</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
- | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
- | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
- | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
-
-<span style="color: #009900">App</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()
-<span style="color: #009900">Extra</span> <span style="color: #990000">::</span> [<span style="color: #009900">Etag</span> | <span style="color: #009900">Mimetypes</span>]
-
-<span style="color: #009900">Etag</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">etag</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()}
- | {<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}
-
-<span style="color: #009900">Mimetypes</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()}
- | {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>}
-
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div>
-<div class="paragraph"><p>Static handler configuration.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-priv_file
-</dt>
-<dd>
-<p>
-Send a file.
-</p>
-<div class="paragraph"><p>The path is relative to the given application’s private
-directory.</p></div>
-</dd>
-<dt class="hdlist1">
-file
-</dt>
-<dd>
-<p>
-Send a file.
-</p>
-<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s
-current directory.</p></div>
-</dd>
-<dt class="hdlist1">
-priv_dir
-</dt>
-<dd>
-<p>
-Recursively serve files from a directory.
-</p>
-<div class="paragraph"><p>The path is relative to the given application’s private
-directory.</p></div>
-</dd>
-<dt class="hdlist1">
-dir
-</dt>
-<dd>
-<p>
-Recursively serve files from a directory.
-</p>
-<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s
-current directory.</p></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The extra options allow you to define how the etag should be
-calculated and how the MIME type of files should be detected.</p></div>
-<div class="paragraph"><p>By default the static handler will generate an etag based
-on the size and modification time of the file. You may disable
-the etag entirely with <code>{etag, false}</code> or provide a module
-and function that will be called when needed:</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: #000000">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">strong</span> | <span style="color: #FF6600">weak</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
-
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">Size</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()
-<span style="color: #009900">Mtime</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:date_time</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>By default the static handler will detect Web-related MIME types
-by looking at the file extension. You can provide a specific
-MIME type that will always be used, or a module and function that
-will be called when needed:</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: #000000">detect_mimetype</span></span>(<span style="color: #009900">Path</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedMime</span>
-
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div>
-<div class="paragraph"><p>Cowboy comes with two such functions; the default function
-<code>cow_mimetypes:web/1</code>, and a second function generated from
-the Apache <em>mime.types</em> file, <code>cow_mimetypes:all/1</code>.</p></div>
-<div class="paragraph"><p>The MIME type function should return
-<code>{<<"application">>, <<"octet-stream">>, []}</code>
-when it fails to detect a file’s MIME type.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Handler introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Custom etag function</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">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(
- <span style="font-weight: bold"><span style="color: #000000">erlang:phash2</span></span>({<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>}, <span style="color: #993399">16#ffffffff</span>))}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Custom MIME type function</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">always_octet_stream</span></span>(<span style="color: #009900">_Path</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">filename:extension</span></span>(<span style="color: #009900">Path</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #990000"><<</span><span style="color: #FF0000">".erl"</span><span style="color: #990000">>></span> <span style="color: #990000">-></span> {<span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"plain"</span><span style="color: #990000">>></span>, []};
- <span style="color: #990000">_</span> <span style="color: #990000">-></span> {<span style="color: #990000"><<</span><span style="color: #FF0000">"application"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"octet-stream"</span><span style="color: #990000">>></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="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_static - Static file handler</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_static</code> implements file serving capabilities +using the REST semantics provided by <code>cowboy_rest</code>.</p></div> +<div class="paragraph"><p>The static file handler is a pre-written handler coming with +Cowboy. To serve files, use it in your routes.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options">Options</h2> +<div class="sectionbody"> +<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: #000000">opts</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + +<span style="color: #009900">App</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="font-weight: bold"><span style="color: #000000">string</span></span>() +<span style="color: #009900">Extra</span> <span style="color: #990000">::</span> [<span style="color: #009900">Etag</span> | <span style="color: #009900">Mimetypes</span>] + +<span style="color: #009900">Etag</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">etag</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()} + | {<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>} + +<span style="color: #009900">Mimetypes</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()} + | {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>} + +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div> +<div class="paragraph"><p>Static handler configuration.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +priv_file +</dt> +<dd> +<p> +Send a file. +</p> +<div class="paragraph"><p>The path is relative to the given application’s private +directory.</p></div> +</dd> +<dt class="hdlist1"> +file +</dt> +<dd> +<p> +Send a file. +</p> +<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s +current directory.</p></div> +</dd> +<dt class="hdlist1"> +priv_dir +</dt> +<dd> +<p> +Recursively serve files from a directory. +</p> +<div class="paragraph"><p>The path is relative to the given application’s private +directory.</p></div> +</dd> +<dt class="hdlist1"> +dir +</dt> +<dd> +<p> +Recursively serve files from a directory. +</p> +<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s +current directory.</p></div> +</dd> +</dl></div> +<div class="paragraph"><p>The extra options allow you to define how the etag should be +calculated and how the MIME type of files should be detected.</p></div> +<div class="paragraph"><p>By default the static handler will generate an etag based +on the size and modification time of the file. You may disable +the etag entirely with <code>{etag, false}</code> or provide a module +and function that will be called when needed:</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: #000000">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">strong</span> | <span style="color: #FF6600">weak</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Size</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">Mtime</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:date_time</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>By default the static handler will detect Web-related MIME types +by looking at the file extension. You can provide a specific +MIME type that will always be used, or a module and function that +will be called when needed:</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: #000000">detect_mimetype</span></span>(<span style="color: #009900">Path</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedMime</span> + +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div> +<div class="paragraph"><p>Cowboy comes with two such functions; the default function +<code>cow_mimetypes:web/1</code>, and a second function generated from +the Apache <em>mime.types</em> file, <code>cow_mimetypes:all/1</code>.</p></div> +<div class="paragraph"><p>The MIME type function should return +<code>{<<"application">>, <<"octet-stream">>, []}</code> +when it fails to detect a file’s MIME type.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Handler introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Custom etag function</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">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>( + <span style="font-weight: bold"><span style="color: #000000">erlang:phash2</span></span>({<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>}, <span style="color: #993399">16#ffffffff</span>))}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Custom MIME type function</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">always_octet_stream</span></span>(<span style="color: #009900">_Path</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">filename:extension</span></span>(<span style="color: #009900">Path</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #990000"><<</span><span style="color: #FF0000">".erl"</span><span style="color: #990000">>></span> <span style="color: #990000">-></span> {<span style="color: #990000"><<</span><span style="color: #FF0000">"text"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"plain"</span><span style="color: #990000">>></span>, []}; + <span style="color: #990000">_</span> <span style="color: #990000">-></span> {<span style="color: #990000"><<</span><span style="color: #FF0000">"application"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"octet-stream"</span><span style="color: #990000">>></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="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_stream/index.html b/docs/en/cowboy/2.0/manual/cowboy_stream/index.html index a51a544e..40d11bcb 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_stream/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_stream/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_stream(3)</title> @@ -67,404 +67,411 @@ <h1 class="lined-header"><span>cowboy_stream(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_handler - Stream handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_stream</code> defines a callback interface
-and a protocol for handling HTTP streams.</p></div>
-<div class="paragraph"><p>An HTTP request and its associated response is called
-a stream. A connection may have many streams. In HTTP/1.1
-they are executed sequentially, while in HTTP/2 they are
-executed concurrently.</p></div>
-<div class="paragraph"><p>Cowboy calls the stream handler for nearly all events
-related to a stream. Exceptions vary depending on the
-protocol.</p></div>
-<div class="paragraph"><p>Extra care must be taken when implementing stream handlers
-to ensure compatibility. While some modification of the
-events and commands is allowed, it is generally not a good
-idea to completely omit them.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Stream handlers must implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>}
-<span style="font-weight: bold"><span style="color: #000000">data</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>}
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>}
-<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="font-weight: bold"><span style="color: #000000">early_error</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">PartialReq</span>, <span style="color: #009900">Resp</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">Resp</span>
-
-<span style="color: #009900">StreamID</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:streamid</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:opts</span></span>()
-<span style="color: #009900">Commands</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:commands</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:fin</span></span>()
-<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:reason</span></span>()
-<span style="color: #009900">PartialReq</span> <span style="color: #990000">-</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #FF6600">except</span> <span style="color: #FF6600">all</span> <span style="color: #FF6600">fields</span> <span style="color: #FF6600">are</span> <span style="color: #FF6600">optional</span>
-<span style="color: #009900">Resp</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:resp_command</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>HTTP/1.1 will initialize a stream only when the request-line
-and all headers have been received. When errors occur before
-that point Cowboy will call the callback <code>early_error/5</code>
-with a partial request, the error reason and the response
-Cowboy intends to send. All other events go throuh the
-stream handler using the normal callbacks.</p></div>
-<div class="paragraph"><p>HTTP/2 will initialize the stream when the <code>HEADERS</code> block has
-been fully received and decoded. Any protocol error occuring
-before that will not result in a response being sent and
-will therefore not go through the stream handler. In addition
-Cowboy may terminate streams without sending an HTTP response
-back.</p></div>
-<div class="paragraph"><p>The stream is initialized by calling <code>init/3</code>. All streams
-that are initialized will eventually be terminated by calling
-<code>terminate/3</code>.</p></div>
-<div class="paragraph"><p>When Cowboy receives data for the stream it will call <code>data/4</code>.
-The data given is the request body after any transfer decoding
-has been applied.</p></div>
-<div class="paragraph"><p>When Cowboy receives a message addressed to a stream, or when
-Cowboy needs to inform the stream handler that an internal
-event has occurred, it will call <code>info/3</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="commands">Commands</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Stream handlers can return a list of commands to be executed
-from the <code>init/3</code>, <code>data/4</code> and <code>info/3</code> callbacks. In addition,
-the <code>early_error/5</code> callback must return a response command.</p></div>
-<div class="paragraph"><p>The following commands are defined:</p></div>
-<div class="sect2">
-<h3 id="response_command">response</h3>
-<div class="paragraph"><p>Send a response to the client.</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="color: #FF6600">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(),
- <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>No more data can be sent after this command.</p></div>
-</div>
-<div class="sect2">
-<h3 id="headers_command">headers</h3>
-<div class="paragraph"><p>Initiate a response to the client.</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="color: #FF6600">headers</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>This initiates a response to the client. The stream
-will end when a data command with the <code>fin</code> flag is
-returned.</p></div>
-</div>
-<div class="sect2">
-<h3 id="data_command">data</h3>
-<div class="paragraph"><p>Send data to the client.</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="color: #FF6600">data</span>, <span style="font-weight: bold"><span style="color: #000000">fin</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="push_command">push</h3>
-<div class="paragraph"><p>Push a resource to the client.</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="color: #FF6600">push</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">Scheme</span>, <span style="color: #009900">Host</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #009900">Path</span>, <span style="color: #009900">Qs</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()}
-
-<span style="color: #009900">Method</span> <span style="color: #990000">=</span> <span style="color: #009900">Scheme</span> <span style="color: #990000">=</span> <span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="color: #009900">Path</span> <span style="color: #990000">=</span> <span style="color: #009900">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>The command will be ignored if the protocol does not provide
-any server push mechanism.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_flow">flow</h3>
-<div class="paragraph"><p>TODO</p></div>
-</div>
-<div class="sect2">
-<h3 id="_spawn">spawn</h3>
-<div class="paragraph"><p>Inform Cowboy that a process was spawned and should be
-supervised.</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: #000080">spawn</span></span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_error_response">error_response</h3>
-<div class="paragraph"><p>Send an error response if no response was sent previously.</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="color: #FF6600">error_response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="switch_protocol_command">switch_protocol</h3>
-<div class="paragraph"><p>Switch to a different protocol.</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="color: #FF6600">switch_protocol</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000000">state</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Contains the headers that will be sent in the 101 response,
-along with the module implementing the protocol we are
-switching to and its initial state.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_stop">stop</h3>
-<div class="paragraph"><p>Stop the stream.</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="color: #FF6600">stop</span></tt></pre></div></div>
-<div class="paragraph"><p>While no more data can be sent after the <code>fin</code> flag was set,
-the stream is still tracked by Cowboy until it is stopped by
-the handler.</p></div>
-<div class="paragraph"><p>The behavior when stopping a stream for which no response
-has been sent will vary depending on the protocol. The stream
-will end successfully as far as the client is concerned.</p></div>
-<div class="paragraph"><p>To indicate that an error occurred, either use <code>error_response</code>
-before stopping, or use <code>internal_error</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_internal_error">internal_error</h3>
-<div class="paragraph"><p>Stop the stream with an error.</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="color: #FF6600">internal_error</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">HumanReadable</span>}
-
-<span style="color: #009900">Reason</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>This command should be used when the stream cannot continue
-because of an internal error. An <code>error_response</code> command
-may be sent before that to advertise to the client why the
-stream is dropped.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_predefined_events">Predefined events</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will forward all messages sent to the stream to
-the <code>info/3</code> callback. To send a message to a stream,
-send a message to the connection process with the form
-<code>{{Pid, StreamID}, Msg}</code>. The connection process will
-then forward <code>Msg</code> to the stream handlers.</p></div>
-<div class="paragraph"><p>Cowboy will also forward the exit signals for the
-processes that the stream spawned.</p></div>
-<div class="sect2">
-<h3 id="_exit">EXIT</h3>
-<div class="paragraph"><p>A process spawned by this stream has exited.</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="color: #000080">'EXIT'</span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>This is the raw exit message without any modification.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_response">response</h3>
-<div class="paragraph"><p>Same as the <a href="../response_command">response command</a>.</p></div>
-<div class="paragraph"><p>Usually sent when the request process replies to the client.
-May also be sent by Cowboy internally.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_headers">headers</h3>
-<div class="paragraph"><p>Same as the <a href="../headers_command">headers command</a>.</p></div>
-<div class="paragraph"><p>Sent when the request process starts replying to the client.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_data">data</h3>
-<div class="paragraph"><p>Same as the <a href="../data_command">data command</a>.</p></div>
-<div class="paragraph"><p>Sent when the request process streams data to the client.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_push">push</h3>
-<div class="paragraph"><p>Same as the <a href="../push_command">push command</a>.</p></div>
-<div class="paragraph"><p>Sent when the request process pushes a resource to the client.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_switch_protocol">switch_protocol</h3>
-<div class="paragraph"><p>Same as the <a href="../switch_protocol_command">switch_protocol command</a>.</p></div>
-<div class="paragraph"><p>Sent when switching to the HTTP/2 or Websocket protocol.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following function should be called by modules implementing
-stream handlers to execute the next stream handler in the list:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_stream.init">cowboy_stream:init(3)</a> - Initialize a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.data">cowboy_stream:data(3)</a> - Handle data for a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.info">cowboy_stream:info(3)</a> - Handle a message for a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.terminate">cowboy_stream:terminate(3)</a> - Terminate a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.early_error">cowboy_stream:early_error(3)</a> - Handle an early error for a stream
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_commands">commands()</h3>
-<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: #000000">commands</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Command</span>]</tt></pre></div></div>
-<div class="paragraph"><p>See the <a href="../commands">list of commands</a> for details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_fin">fin()</h3>
-<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: #000000">fin</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div>
-<div class="paragraph"><p>Used in commands and events to indicate that this is
-the end of the stream.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_partial_req">partial_req()</h3>
-<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: #000000">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">version</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(),
- <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(),
- <span style="color: #0000FF">peer</span> <span style="color: #990000">=></span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
-}</tt></pre></div></div>
-<div class="paragraph"><p>Partial request information received when an early error is
-detected.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_reason">reason()</h3>
-<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: #000000">reason</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
- | {<span style="color: #FF6600">internal_error</span>, <span style="color: #FF6600">timeout</span> | {<span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}, <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">socket_error</span>, <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">stream_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">connection_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="font-weight: bold"><span style="color: #000000">cow_http2:frame</span></span>(), <span style="color: #009900">HumanReadable</span>}
-
-<span style="color: #009900">Error</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Reason for the stream termination.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_resp_command">resp_command()</h3>
-<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: #000000">resp_command</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(),
- <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>See the <a href="../response_command">response command</a> for details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_streamid">streamid()</h3>
-<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: #000000">streamid</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>The identifier for this stream.</p></div>
-<div class="paragraph"><p>The identifier is unique over the connection process.
-It is possible to form a unique identifier node-wide and
-cluster-wide by wrapping it in a <code>{self(), StreamID}</code>
-tuple.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Module introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_http">cowboy_http(3)</a>,
-<a href="../cowboy_http2">cowboy_http2(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_handler - Stream handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_stream</code> defines a callback interface +and a protocol for handling HTTP streams.</p></div> +<div class="paragraph"><p>An HTTP request and its associated response is called +a stream. A connection may have many streams. In HTTP/1.1 +they are executed sequentially, while in HTTP/2 they are +executed concurrently.</p></div> +<div class="paragraph"><p>Cowboy calls the stream handler for nearly all events +related to a stream. Exceptions vary depending on the +protocol.</p></div> +<div class="paragraph"><p>Extra care must be taken when implementing stream handlers +to ensure compatibility. While some modification of the +events and commands is allowed, it is generally not a good +idea to completely omit them.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Stream handlers must implement the following interface:</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: #000000">init</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>} +<span style="font-weight: bold"><span style="color: #000000">data</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>} +<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>} +<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="font-weight: bold"><span style="color: #000000">early_error</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">PartialReq</span>, <span style="color: #009900">Resp</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">Resp</span> + +<span style="color: #009900">StreamID</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:streamid</span></span>() +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:opts</span></span>() +<span style="color: #009900">Commands</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:commands</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:fin</span></span>() +<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:reason</span></span>() +<span style="color: #009900">PartialReq</span> <span style="color: #990000">-</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #FF6600">except</span> <span style="color: #FF6600">all</span> <span style="color: #FF6600">fields</span> <span style="color: #FF6600">are</span> <span style="color: #FF6600">optional</span> +<span style="color: #009900">Resp</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:resp_command</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>HTTP/1.1 will initialize a stream only when the request-line +and all headers have been received. When errors occur before +that point Cowboy will call the callback <code>early_error/5</code> +with a partial request, the error reason and the response +Cowboy intends to send. All other events go throuh the +stream handler using the normal callbacks.</p></div> +<div class="paragraph"><p>HTTP/2 will initialize the stream when the <code>HEADERS</code> block has +been fully received and decoded. Any protocol error occuring +before that will not result in a response being sent and +will therefore not go through the stream handler. In addition +Cowboy may terminate streams without sending an HTTP response +back.</p></div> +<div class="paragraph"><p>The stream is initialized by calling <code>init/3</code>. All streams +that are initialized will eventually be terminated by calling +<code>terminate/3</code>.</p></div> +<div class="paragraph"><p>When Cowboy receives data for the stream it will call <code>data/4</code>. +The data given is the request body after any transfer decoding +has been applied.</p></div> +<div class="paragraph"><p>When Cowboy receives a message addressed to a stream, or when +Cowboy needs to inform the stream handler that an internal +event has occurred, it will call <code>info/3</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="commands">Commands</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Stream handlers can return a list of commands to be executed +from the <code>init/3</code>, <code>data/4</code> and <code>info/3</code> callbacks. In addition, +the <code>early_error/5</code> callback must return a response command.</p></div> +<div class="paragraph"><p>The following commands are defined:</p></div> +<div class="sect2"> +<h3 id="response_command">response</h3> +<div class="paragraph"><p>Send a response to the client.</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="color: #FF6600">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), + <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>No more data can be sent after this command.</p></div> +</div> +<div class="sect2"> +<h3 id="headers_command">headers</h3> +<div class="paragraph"><p>Initiate a response to the client.</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="color: #FF6600">headers</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>This initiates a response to the client. The stream +will end when a data command with the <code>fin</code> flag is +returned.</p></div> +</div> +<div class="sect2"> +<h3 id="data_command">data</h3> +<div class="paragraph"><p>Send data to the client.</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="color: #FF6600">data</span>, <span style="font-weight: bold"><span style="color: #000000">fin</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="push_command">push</h3> +<div class="paragraph"><p>Push a resource to the client.</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="color: #FF6600">push</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">Scheme</span>, <span style="color: #009900">Host</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #009900">Path</span>, <span style="color: #009900">Qs</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()} + +<span style="color: #009900">Method</span> <span style="color: #990000">=</span> <span style="color: #009900">Scheme</span> <span style="color: #990000">=</span> <span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="color: #009900">Path</span> <span style="color: #990000">=</span> <span style="color: #009900">Qs</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>The command will be ignored if the protocol does not provide +any server push mechanism.</p></div> +</div> +<div class="sect2"> +<h3 id="_flow">flow</h3> +<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="color: #FF6600">flow</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Request more data to be read from the request body. The +exact behavior depends on the protocol.</p></div> +</div> +<div class="sect2"> +<h3 id="_spawn">spawn</h3> +<div class="paragraph"><p>Inform Cowboy that a process was spawned and should be +supervised.</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: #000080">spawn</span></span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_error_response">error_response</h3> +<div class="paragraph"><p>Send an error response if no response was sent previously.</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="color: #FF6600">error_response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="switch_protocol_command">switch_protocol</h3> +<div class="paragraph"><p>Switch to a different protocol.</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="color: #FF6600">switch_protocol</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000000">state</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Contains the headers that will be sent in the 101 response, +along with the module implementing the protocol we are +switching to and its initial state.</p></div> +</div> +<div class="sect2"> +<h3 id="_stop">stop</h3> +<div class="paragraph"><p>Stop the stream.</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="color: #FF6600">stop</span></tt></pre></div></div> +<div class="paragraph"><p>While no more data can be sent after the <code>fin</code> flag was set, +the stream is still tracked by Cowboy until it is stopped by +the handler.</p></div> +<div class="paragraph"><p>The behavior when stopping a stream for which no response +has been sent will vary depending on the protocol. The stream +will end successfully as far as the client is concerned.</p></div> +<div class="paragraph"><p>To indicate that an error occurred, either use <code>error_response</code> +before stopping, or use <code>internal_error</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_internal_error">internal_error</h3> +<div class="paragraph"><p>Stop the stream with an error.</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="color: #FF6600">internal_error</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">HumanReadable</span>} + +<span style="color: #009900">Reason</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>This command should be used when the stream cannot continue +because of an internal error. An <code>error_response</code> command +may be sent before that to advertise to the client why the +stream is dropped.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_predefined_events">Predefined events</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will forward all messages sent to the stream to +the <code>info/3</code> callback. To send a message to a stream, +send a message to the connection process with the form +<code>{{Pid, StreamID}, Msg}</code>. The connection process will +then forward <code>Msg</code> to the stream handlers.</p></div> +<div class="paragraph"><p>Cowboy will also forward the exit signals for the +processes that the stream spawned.</p></div> +<div class="sect2"> +<h3 id="_exit">EXIT</h3> +<div class="paragraph"><p>A process spawned by this stream has exited.</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="color: #000080">'EXIT'</span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>This is the raw exit message without any modification.</p></div> +</div> +<div class="sect2"> +<h3 id="_response">response</h3> +<div class="paragraph"><p>Same as the <a href="../response_command">response command</a>.</p></div> +<div class="paragraph"><p>Usually sent when the request process replies to the client. +May also be sent by Cowboy internally.</p></div> +</div> +<div class="sect2"> +<h3 id="_headers">headers</h3> +<div class="paragraph"><p>Same as the <a href="../headers_command">headers command</a>.</p></div> +<div class="paragraph"><p>Sent when the request process starts replying to the client.</p></div> +</div> +<div class="sect2"> +<h3 id="_data">data</h3> +<div class="paragraph"><p>Same as the <a href="../data_command">data command</a>.</p></div> +<div class="paragraph"><p>Sent when the request process streams data to the client.</p></div> +</div> +<div class="sect2"> +<h3 id="_push">push</h3> +<div class="paragraph"><p>Same as the <a href="../push_command">push command</a>.</p></div> +<div class="paragraph"><p>Sent when the request process pushes a resource to the client.</p></div> +</div> +<div class="sect2"> +<h3 id="_switch_protocol">switch_protocol</h3> +<div class="paragraph"><p>Same as the <a href="../switch_protocol_command">switch_protocol command</a>.</p></div> +<div class="paragraph"><p>Sent when switching to the HTTP/2 or Websocket protocol.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The following function should be called by modules implementing +stream handlers to execute the next stream handler in the list:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_stream.init">cowboy_stream:init(3)</a> - Initialize a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.data">cowboy_stream:data(3)</a> - Handle data for a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.info">cowboy_stream:info(3)</a> - Handle a message for a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.terminate">cowboy_stream:terminate(3)</a> - Terminate a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.early_error">cowboy_stream:early_error(3)</a> - Handle an early error for a stream +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_commands">commands()</h3> +<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: #000000">commands</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Command</span>]</tt></pre></div></div> +<div class="paragraph"><p>See the <a href="../commands">list of commands</a> for details.</p></div> +</div> +<div class="sect2"> +<h3 id="_fin">fin()</h3> +<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: #000000">fin</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div> +<div class="paragraph"><p>Used in commands and events to indicate that this is +the end of the stream.</p></div> +</div> +<div class="sect2"> +<h3 id="_partial_req">partial_req()</h3> +<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: #000000">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">version</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), + <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), + <span style="color: #0000FF">peer</span> <span style="color: #990000">=></span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} +}</tt></pre></div></div> +<div class="paragraph"><p>Partial request information received when an early error is +detected.</p></div> +</div> +<div class="sect2"> +<h3 id="_reason">reason()</h3> +<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: #000000">reason</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> + | {<span style="color: #FF6600">internal_error</span>, <span style="color: #FF6600">timeout</span> | {<span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}, <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">socket_error</span>, <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">stream_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">connection_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">stop</span>, <span style="font-weight: bold"><span style="color: #000000">cow_http2:frame</span></span>(), <span style="color: #009900">HumanReadable</span>} + +<span style="color: #009900">Error</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Reason for the stream termination.</p></div> +</div> +<div class="sect2"> +<h3 id="_resp_command">resp_command()</h3> +<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: #000000">resp_command</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), + <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>See the <a href="../response_command">response command</a> for details.</p></div> +</div> +<div class="sect2"> +<h3 id="_streamid">streamid()</h3> +<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: #000000">streamid</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>The identifier for this stream.</p></div> +<div class="paragraph"><p>The identifier is unique over the connection process. +It is possible to form a unique identifier node-wide and +cluster-wide by wrapping it in a <code>{self(), StreamID}</code> +tuple.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Module introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_http">cowboy_http(3)</a>, +<a href="../cowboy_http2">cowboy_http2(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html index f09890a8..8903a079 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_websocket(3)</title> @@ -67,277 +67,295 @@ <h1 class="lined-header"><span>cowboy_websocket(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_websocket - Websocket</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_websocket</code> implements Websocket
-as a Ranch protocol. It also defines a callback interface
-for handling Websocket connections.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket handlers must implement the following callback
-interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}
-
-<span style="font-weight: bold"><span style="color: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">InFrame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span>
-<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span>
-
-<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #000080">undefined</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_websocket:opts</span></span>()
-<span style="color: #009900">InFrame</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span> | <span style="font-weight: bold"><span style="color: #000080">binary</span></span> | <span style="color: #FF6600">ping</span> | <span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
-<span style="color: #009900">OutFrame</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_ws:frame</span></span>()
-<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-
-<span style="color: #009900">CallResult</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> | <span style="color: #FF6600">stop</span> | <span style="color: #FF6600">timeout</span>
- | <span style="color: #FF6600">remote</span> | {<span style="color: #FF6600">remote</span>, <span style="font-weight: bold"><span style="color: #000000">cow_ws:close_code</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">badencoding</span> | <span style="color: #FF6600">badframe</span> | <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To upgrade
-the connection to Websocket, it must return <code>cowboy_websocket</code>
-as the first element of the tuple.</p></div>
-<div class="paragraph"><p>Any operation requiring the HTTP request must be done in the
-<code>init/2</code> function, as the Req object will not be available
-after it returns. Websocket sub-protocol selection should
-therefore be done in this function.</p></div>
-<div class="paragraph"><p>The optional <code>websocket_init/1</code> callback will be called once
-the connection has been upgraded to Websocket. It can be used
-to perform any required initialization of the handler.</p></div>
-<div class="paragraph"><p>Note that the <code>init/2</code> function does not run in the same
-process as the Websocket callbacks. Any Websocket-specific
-initialization must be done in <code>websocket_init/1</code>.</p></div>
-<div class="paragraph"><p>The <code>websocket_handle/2</code> callback will be called for every
-frame received. The <code>websocket_info/2</code> callback will be
-called for every Erlang message received.</p></div>
-<div class="paragraph"><p>All three Websocket callbacks may send one or more frames
-back to the client (by returning a <code>reply</code> tuple) or terminate
-the connection (by sending a <code>close</code> frame or returning a <code>stop</code>
-tuple).</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the connection. This
-callback is common to all handlers. Note that Websocket has
-no concept of requests so it sets the second argument to
-undefined.</p></div>
-<div class="paragraph"><p>Cowboy will terminate the process right after closing the
-Websocket connection. This means that there is no need to
-perform any cleanup in the <code>terminate/3</code> callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for Websocket
-connections:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-normal
-</dt>
-<dd>
-<p>
- The connection was closed normally before establishing a Websocket
- connection. This typically happens if an <code>ok</code> tuple is returned
- from the <code>init/2</code> callback.
-</p>
-</dd>
-<dt class="hdlist1">
-remote
-</dt>
-<dd>
-<p>
- The remote endpoint closed the connection without giving any
- further details.
-</p>
-</dd>
-<dt class="hdlist1">
-{remote, Code, Payload}
-</dt>
-<dd>
-<p>
- The remote endpoint closed the connection with the given
- <code>Code</code> and <code>Payload</code> as the reason.
-</p>
-</dd>
-<dt class="hdlist1">
-stop
-</dt>
-<dd>
-<p>
- The handler requested to close the connection, either by returning
- a <code>stop</code> tuple or by sending a <code>close</code> frame.
-</p>
-</dd>
-<dt class="hdlist1">
-timeout
-</dt>
-<dd>
-<p>
- The connection has been closed due to inactivity. The timeout
- value can be configured from <code>init/2</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, badencoding}
-</dt>
-<dd>
-<p>
- A text frame was sent by the client with invalid encoding. All
- text frames must be valid UTF-8.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, badframe}
-</dt>
-<dd>
-<p>
- A protocol error has been detected.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, closed}
-</dt>
-<dd>
-<p>
- The socket has been closed brutally without a close frame being
- received first.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, Reason}
-</dt>
-<dd>
-<p>
- A socket error ocurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opts">opts()</h3>
-<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: #000000">opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(),
- <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">req_filter</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>((<span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>())
-}</tt></pre></div></div>
-<div class="paragraph"><p>Websocket handler options.</p></div>
-<div class="paragraph"><p>This configuration is passed to Cowboy from the <code>init/2</code>
-function:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Opts</span> <span style="color: #990000">=</span> #{<span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>},
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The default value is given next to the option name:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-compress (false)
-</dt>
-<dd>
-<p>
- Whether to enable the Websocket frame compression
- extension. Frames will only be compressed for the
- clients that support this extension.
-</p>
-</dd>
-<dt class="hdlist1">
-idle_timeout (60000)
-</dt>
-<dd>
-<p>
- Time in milliseconds that Cowboy will keep the
- connection open without receiving anything from
- the client.
-</p>
-</dd>
-<dt class="hdlist1">
-req_filter
-</dt>
-<dd>
-<p>
- A function applied to the Req to compact it and
- only keep required information. The Req is only
- given back in the <code>terminate/3</code> callback. By default
- it keeps the method, version, URI components and peer
- information.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The Req object is no longer passed to Websocket callbacks.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The callback <code>websocket_terminate/3</code> was removed in favor of <code>terminate/3</code>.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Protocol introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_handler">cowboy_handler(3)</a>,
-<a href="../cowboy_http">cowboy_http(3)</a>,
-<a href="../cowboy_http2">cowboy_http2(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_websocket - Websocket</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_websocket</code> implements Websocket +as a Ranch protocol. It also defines a callback interface +for handling Websocket connections.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Websocket handlers must implement the following callback +interface:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>} + +<span style="font-weight: bold"><span style="color: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span> +<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">InFrame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> +<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> + +<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">PartialReq</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">PartialReq</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_websocket:opts</span></span>() +<span style="color: #009900">InFrame</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span> | <span style="font-weight: bold"><span style="color: #000080">binary</span></span> | <span style="color: #FF6600">ping</span> | <span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} +<span style="color: #009900">OutFrame</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_ws:frame</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% see types below</span></span> +<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() + +<span style="color: #009900">CallResult</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>} + | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>} + | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> | <span style="color: #FF6600">stop</span> | <span style="color: #FF6600">timeout</span> + | <span style="color: #FF6600">remote</span> | {<span style="color: #FF6600">remote</span>, <span style="font-weight: bold"><span style="color: #000000">cow_ws:close_code</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">badencoding</span> | <span style="color: #FF6600">badframe</span> | <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()} + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To upgrade +the connection to Websocket, it must return <code>cowboy_websocket</code> +as the first element of the tuple.</p></div> +<div class="paragraph"><p>Any operation requiring the HTTP request must be done in the +<code>init/2</code> function, as the Req object will not be available +after it returns. Websocket sub-protocol selection should +therefore be done in this function.</p></div> +<div class="paragraph"><p>The optional <code>websocket_init/1</code> callback will be called once +the connection has been upgraded to Websocket. It can be used +to perform any required initialization of the handler.</p></div> +<div class="paragraph"><p>Note that the <code>init/2</code> function does not run in the same +process as the Websocket callbacks. Any Websocket-specific +initialization must be done in <code>websocket_init/1</code>.</p></div> +<div class="paragraph"><p>The <code>websocket_handle/2</code> callback will be called for every +frame received. The <code>websocket_info/2</code> callback will be +called for every Erlang message received.</p></div> +<div class="paragraph"><p>All three Websocket callbacks may send one or more frames +back to the client (by returning a <code>reply</code> tuple) or terminate +the connection (by sending a <code>close</code> frame or returning a <code>stop</code> +tuple).</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the connection. This +callback is common to all handlers. Note that Websocket will +not provide the full Req object by default, to save memory.</p></div> +<div class="paragraph"><p>Cowboy will terminate the process right after closing the +Websocket connection. This means that there is no need to +perform any cleanup in the <code>terminate/3</code> callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for Websocket +connections:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +normal +</dt> +<dd> +<p> + The connection was closed normally before establishing a Websocket + connection. This typically happens if an <code>ok</code> tuple is returned + from the <code>init/2</code> callback. +</p> +</dd> +<dt class="hdlist1"> +remote +</dt> +<dd> +<p> + The remote endpoint closed the connection without giving any + further details. +</p> +</dd> +<dt class="hdlist1"> +{remote, Code, Payload} +</dt> +<dd> +<p> + The remote endpoint closed the connection with the given + <code>Code</code> and <code>Payload</code> as the reason. +</p> +</dd> +<dt class="hdlist1"> +stop +</dt> +<dd> +<p> + The handler requested to close the connection, either by returning + a <code>stop</code> tuple or by sending a <code>close</code> frame. +</p> +</dd> +<dt class="hdlist1"> +timeout +</dt> +<dd> +<p> + The connection has been closed due to inactivity. The timeout + value can be configured from <code>init/2</code>. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +<dt class="hdlist1"> +{error, badencoding} +</dt> +<dd> +<p> + A text frame was sent by the client with invalid encoding. All + text frames must be valid UTF-8. +</p> +</dd> +<dt class="hdlist1"> +{error, badframe} +</dt> +<dd> +<p> + A protocol error has been detected. +</p> +</dd> +<dt class="hdlist1"> +{error, closed} +</dt> +<dd> +<p> + The socket has been closed brutally without a close frame being + received first. +</p> +</dd> +<dt class="hdlist1"> +{error, Reason} +</dt> +<dd> +<p> + A socket error ocurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect3"> +<h4 id="_cow_ws_frame">cow_ws:frame()</h4> +<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: #000000">frame</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | <span style="color: #FF6600">ping</span> | {<span style="color: #FF6600">ping</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | <span style="color: #FF6600">pong</span> | {<span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | <span style="color: #FF6600">close</span> | {<span style="color: #FF6600">close</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | {<span style="color: #FF6600">close</span>, <span style="font-weight: bold"><span style="color: #000000">close_code</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + +<span style="font-weight: bold"><span style="color: #000000">close_code</span></span>() <span style="color: #990000">::</span> <span style="color: #993399">1000</span><span style="color: #990000">..</span><span style="color: #993399">1003</span> | <span style="color: #993399">1006</span><span style="color: #990000">..</span><span style="color: #993399">1011</span> | <span style="color: #993399">3000</span><span style="color: #990000">..</span><span style="color: #993399">4999</span></tt></pre></div></div> +<div class="paragraph"><p>Websocket frames that can be sent as a response.</p></div> +<div class="paragraph"><p>Note that there is no need to send pong frames back as +Cowboy does it automatically for you.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts">opts()</h3> +<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: #000000">opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), + <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">req_filter</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>((<span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()) +}</tt></pre></div></div> +<div class="paragraph"><p>Websocket handler options.</p></div> +<div class="paragraph"><p>This configuration is passed to Cowboy from the <code>init/2</code> +function:</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: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Opts</span> <span style="color: #990000">=</span> #{<span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>}, + {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The default value is given next to the option name:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +compress (false) +</dt> +<dd> +<p> + Whether to enable the Websocket frame compression + extension. Frames will only be compressed for the + clients that support this extension. +</p> +</dd> +<dt class="hdlist1"> +idle_timeout (60000) +</dt> +<dd> +<p> + Time in milliseconds that Cowboy will keep the + connection open without receiving anything from + the client. +</p> +</dd> +<dt class="hdlist1"> +req_filter +</dt> +<dd> +<p> + A function applied to the Req to compact it and + only keep required information. The Req is only + given back in the <code>terminate/3</code> callback. By default + it keeps the method, version, URI components and peer + information. +</p> +</dd> +</dl></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The Req object is no longer passed to Websocket callbacks. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The callback <code>websocket_terminate/3</code> was removed in favor of <code>terminate/3</code>. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Protocol introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_handler">cowboy_handler(3)</a>, +<a href="../cowboy_http">cowboy_http(3)</a>, +<a href="../cowboy_http2">cowboy_http2(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/http_status_codes/index.html b/docs/en/cowboy/2.0/manual/http_status_codes/index.html index 7f94b815..31b3296d 100644 --- a/docs/en/cowboy/2.0/manual/http_status_codes/index.html +++ b/docs/en/cowboy/2.0/manual/http_status_codes/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: HTTP status codes(7)</title> @@ -67,271 +67,271 @@ <h1 class="lined-header"><span>HTTP status codes(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP status codes - status codes used by Cowboy</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This chapter aims to list all HTTP status codes that Cowboy
-may return, with details on the reasons why. The list given
-here only includes the replies that Cowboy sends, not user
-replies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_100_continue">100 Continue</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When the client sends an <code>expect: 100-continue</code> header,
-Cowboy automatically sends a this status code before
-trying to read the request body. This behavior can be
-disabled using the appropriate body option.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_101_switching_protocols">101 Switching Protocols</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This is the status code sent when switching to the
-Websocket protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_200_ok">200 OK</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_201_created">201 Created</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_202_accepted">202 Accepted</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_204_no_content">204 No Content</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when the processing of a request
-ends without any reply having been sent. It may also be
-sent by <code>cowboy_rest</code> under normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_300_multiple_choices">300 Multiple Choices</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_301_moved_permanently">301 Moved Permanently</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_303_see_other">303 See Other</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_304_not_modified">304 Not Modified</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_307_temporary_redirect">307 Temporary Redirect</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_400_bad_request">400 Bad Request</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code for any of the
-following reasons:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Too many empty lines were sent before the request.
-</p>
-</li>
-<li>
-<p>
-The request-line could not be parsed.
-</p>
-</li>
-<li>
-<p>
-Too many headers were sent.
-</p>
-</li>
-<li>
-<p>
-A header name was too long.
-</p>
-</li>
-<li>
-<p>
-A header value was too long.
-</p>
-</li>
-<li>
-<p>
-The host header was missing from an HTTP/1.1 request.
-</p>
-</li>
-<li>
-<p>
-The host header could not be parsed.
-</p>
-</li>
-<li>
-<p>
-The requested host was not found.
-</p>
-</li>
-<li>
-<p>
-The requested path could not be parsed.
-</p>
-</li>
-<li>
-<p>
-The accept header could not be parsed when using REST.
-</p>
-</li>
-<li>
-<p>
-REST under normal conditions.
-</p>
-</li>
-<li>
-<p>
-A Websocket upgrade failed.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_401_unauthorized">401 Unauthorized</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_403_forbidden">403 Forbidden</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_404_not_found">404 Not Found</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when the router successfully
-resolved the host but didn’t find a matching path for
-the request. It may also be sent by <code>cowboy_rest</code> under
-normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_405_method_not_allowed">405 Method Not Allowed</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_406_not_acceptable">406 Not Acceptable</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_408_request_timeout">408 Request Timeout</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code to the client if the
-client started to send a request, indicated by the
-request-line being received fully, but failed to send
-all headers in a reasonable time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_409_conflict">409 Conflict</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_410_gone">410 Gone</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_412_precondition_failed">412 Precondition Failed</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_413_request_entity_too_large">413 Request Entity Too Large</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_414_request_uri_too_long">414 Request-URI Too Long</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code to the client if the
-request-line is too long. It may also be sent by
-<code>cowboy_rest</code> under normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_415_unsupported_media_type">415 Unsupported Media Type</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_500_internal_server_error">500 Internal Server Error</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when a crash occurs in HTTP, loop
-or REST handlers, or when an invalid return value is
-returned. It may also be sent by <code>cowboy_rest</code> under
-normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_501_not_implemented">501 Not Implemented</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_503_service_unavailable">503 Service Unavailable</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_505_http_version_not_supported">505 HTTP Version Not Supported</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy only supports the versions 1.0 and 1.1 of HTTP.
-In all other cases this status code is sent back to the
-client and the connection is closed.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>HTTP status codes - status codes used by Cowboy</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This chapter aims to list all HTTP status codes that Cowboy +may return, with details on the reasons why. The list given +here only includes the replies that Cowboy sends, not user +replies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_100_continue">100 Continue</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When the client sends an <code>expect: 100-continue</code> header, +Cowboy automatically sends a this status code before +trying to read the request body. This behavior can be +disabled using the appropriate body option.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_101_switching_protocols">101 Switching Protocols</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This is the status code sent when switching to the +Websocket protocol.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_200_ok">200 OK</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_201_created">201 Created</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_202_accepted">202 Accepted</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_204_no_content">204 No Content</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent when the processing of a request +ends without any reply having been sent. It may also be +sent by <code>cowboy_rest</code> under normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_300_multiple_choices">300 Multiple Choices</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_301_moved_permanently">301 Moved Permanently</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_303_see_other">303 See Other</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_304_not_modified">304 Not Modified</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_307_temporary_redirect">307 Temporary Redirect</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_400_bad_request">400 Bad Request</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will send this status code for any of the +following reasons:</p></div> +<div class="ulist"><ul> +<li> +<p> +Too many empty lines were sent before the request. +</p> +</li> +<li> +<p> +The request-line could not be parsed. +</p> +</li> +<li> +<p> +Too many headers were sent. +</p> +</li> +<li> +<p> +A header name was too long. +</p> +</li> +<li> +<p> +A header value was too long. +</p> +</li> +<li> +<p> +The host header was missing from an HTTP/1.1 request. +</p> +</li> +<li> +<p> +The host header could not be parsed. +</p> +</li> +<li> +<p> +The requested host was not found. +</p> +</li> +<li> +<p> +The requested path could not be parsed. +</p> +</li> +<li> +<p> +The accept header could not be parsed when using REST. +</p> +</li> +<li> +<p> +REST under normal conditions. +</p> +</li> +<li> +<p> +A Websocket upgrade failed. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_401_unauthorized">401 Unauthorized</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_403_forbidden">403 Forbidden</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_404_not_found">404 Not Found</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent when the router successfully +resolved the host but didn’t find a matching path for +the request. It may also be sent by <code>cowboy_rest</code> under +normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_405_method_not_allowed">405 Method Not Allowed</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_406_not_acceptable">406 Not Acceptable</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_408_request_timeout">408 Request Timeout</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will send this status code to the client if the +client started to send a request, indicated by the +request-line being received fully, but failed to send +all headers in a reasonable time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_409_conflict">409 Conflict</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_410_gone">410 Gone</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_412_precondition_failed">412 Precondition Failed</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_413_request_entity_too_large">413 Request Entity Too Large</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_414_request_uri_too_long">414 Request-URI Too Long</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will send this status code to the client if the +request-line is too long. It may also be sent by +<code>cowboy_rest</code> under normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_415_unsupported_media_type">415 Unsupported Media Type</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_500_internal_server_error">500 Internal Server Error</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent when a crash occurs in HTTP, loop +or REST handlers, or when an invalid return value is +returned. It may also be sent by <code>cowboy_rest</code> under +normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_501_not_implemented">501 Not Implemented</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_503_service_unavailable">503 Service Unavailable</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_505_http_version_not_supported">505 HTTP Version Not Supported</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy only supports the versions 1.0 and 1.1 of HTTP. +In all other cases this status code is sent back to the +client and the connection is closed.</p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/index.html b/docs/en/cowboy/2.0/manual/index.html index 24286315..aec2688c 100644 --- a/docs/en/cowboy/2.0/manual/index.html +++ b/docs/en/cowboy/2.0/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy Function Reference</title> @@ -67,166 +67,171 @@ <h1 class="lined-header"><span>Cowboy Function Reference</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the
-HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes
-the implementation of the HTTP RFCs but also any directly
-related standards, like Websocket or Server-Sent Events.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_modules">Modules</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Functions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy">cowboy(3)</a> - Listener management
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_req">cowboy_req(3)</a> - Request and response
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_router">cowboy_router(3)</a> - Router
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_http">cowboy_http(3)</a> - HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_http2">cowboy_http2(3)</a> - HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Handlers:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_static">cowboy_static(3)</a> - Static file handler
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Behaviors:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_loop">cowboy_loop(3)</a> - Loop handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_middleware">cowboy_middleware(3)</a> - Middlewares
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Middlewares:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_router">cowboy_router(3)</a> - Router middleware
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_handler">cowboy_handler(3)</a> - Handler middleware
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="/docs">ranch(7)</a> - Socket acceptor pool for TCP protocols
-</p>
-</li>
-<li>
-<p>
-<a href="/docs">cowlib(7)</a> - Support library for manipulating Web protocols
-</p>
-</li>
-<li>
-<p>
-ssl - Secure communication over sockets
-</p>
-</li>
-<li>
-<p>
-crypto - Crypto functions
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code>
-application. To start Cowboy and all dependencies at once:</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="color: #FF6600">ok</span>, <span style="color: #990000">_</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">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="/docs">ranch(7)</a>,
-<a href="/docs">cowlib(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the +HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> +<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes +the implementation of the HTTP RFCs but also any directly +related standards, like Websocket or Server-Sent Events.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_modules">Modules</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Functions:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy">cowboy(3)</a> - Listener management +</p> +</li> +<li> +<p> +<a href="cowboy_req">cowboy_req(3)</a> - Request and response +</p> +</li> +<li> +<p> +<a href="cowboy_router">cowboy_router(3)</a> - Router +</p> +</li> +<li> +<p> +<a href="cowboy_constraints">cowboy_constraints(3)</a> - Constraints +</p> +</li> +</ul></div> +<div class="paragraph"><p>Protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_http">cowboy_http(3)</a> - HTTP/1.1 +</p> +</li> +<li> +<p> +<a href="cowboy_http2">cowboy_http2(3)</a> - HTTP/2 +</p> +</li> +<li> +<p> +<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket +</p> +</li> +</ul></div> +<div class="paragraph"><p>Handlers:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_static">cowboy_static(3)</a> - Static file handler +</p> +</li> +</ul></div> +<div class="paragraph"><p>Behaviors:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers +</p> +</li> +<li> +<p> +<a href="cowboy_loop">cowboy_loop(3)</a> - Loop handlers +</p> +</li> +<li> +<p> +<a href="cowboy_middleware">cowboy_middleware(3)</a> - Middlewares +</p> +</li> +<li> +<p> +<a href="cowboy_rest">cowboy_rest(3)</a> - REST handlers +</p> +</li> +<li> +<p> +<a href="cowboy_stream">cowboy_stream(3)</a> - Stream handlers +</p> +</li> +<li> +<p> +<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers +</p> +</li> +</ul></div> +<div class="paragraph"><p>Middlewares:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_router">cowboy_router(3)</a> - Router middleware +</p> +</li> +<li> +<p> +<a href="cowboy_handler">cowboy_handler(3)</a> - Handler middleware +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="/docs">ranch(7)</a> - Socket acceptor pool for TCP protocols +</p> +</li> +<li> +<p> +<a href="/docs">cowlib(7)</a> - Support library for manipulating Web protocols +</p> +</li> +<li> +<p> +ssl - Secure communication over sockets +</p> +</li> +<li> +<p> +crypto - Crypto functions +</p> +</li> +</ul></div> +<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code> +application. To start Cowboy and all dependencies at once:</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="color: #FF6600">ok</span>, <span style="color: #990000">_</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">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy</code> application does not define any application +environment configuration parameters.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="/docs">ranch(7)</a>, +<a href="/docs">cowlib(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/HEAD/guide/index.html b/docs/en/cowboy/HEAD/guide/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/HEAD/guide/index.html +++ b/docs/en/cowboy/HEAD/guide/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/HEAD/index.html b/docs/en/cowboy/HEAD/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/HEAD/index.html +++ b/docs/en/cowboy/HEAD/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/HEAD/manual/index.html b/docs/en/cowboy/HEAD/manual/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/HEAD/manual/index.html +++ b/docs/en/cowboy/HEAD/manual/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/index.html b/docs/en/cowboy/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/index.html +++ b/docs/en/cowboy/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/erlang.mk/1/guide/app/index.html b/docs/en/erlang.mk/1/guide/app/index.html index 49f9c1f4..c4fa21f7 100644 --- a/docs/en/erlang.mk/1/guide/app/index.html +++ b/docs/en/erlang.mk/1/guide/app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Building</title> @@ -67,555 +67,614 @@ <h1 class="lined-header"><span>Building</span></h1> -<div class="paragraph"><p>Erlang.mk can do a lot of things, but it is, first and
-foremost, a build tool. In this chapter we will cover
-the basics of building a project with Erlang.mk.</p></div>
-<div class="paragraph"><p>For most of this chapter, we will assume that you are
-using a project <a href="../getting_started">generated by Erlang.mk</a>.</p></div>
-<div class="sect1">
-<h2 id="_how_to_build">How to build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build a project, all you have to do is type <code>make</code>:</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>$ make</tt></pre></div></div>
-<div class="paragraph"><p>It will work regardless of your project: OTP applications,
-library applications, NIFs, port drivers or even releases.
-Erlang.mk also automatically downloads and compiles the
-dependencies for your project.</p></div>
-<div class="paragraph"><p>All this is possible thanks to a combination of configuration
-and conventions. Most of the conventions come from Erlang/OTP
-itself so any seasoned Erlang developers should feel right at
-home.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_what_to_build">What to build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk gives you control over three steps of the build
-process, allowing you to do a partial build if needed.</p></div>
-<div class="paragraph"><p>A build has three phases: first any dependency is fetched
-and built, then the project itself is built and finally a
-release may be generated when applicable. A release is only
-generated for projects specifically configured to do so.</p></div>
-<div class="paragraph"><p>Erlang.mk handles those three phases automatically when you
-type <code>make</code>. But sometimes you just want to repeat one or
-two of them.</p></div>
-<div class="paragraph"><p>The commands detailed in this section are most useful after
-you have a successful build as they allow you to quickly
-redo a step instead of going through everything. This is
-especially useful for large projects or projects that end
-up generating releases.</p></div>
-<div class="sect3">
-<h4 id="_application">Application</h4>
-<div class="paragraph"><p>You can build your application and dependencies without
-generating a release by running the following command:</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>$ make app</tt></pre></div></div>
-<div class="paragraph"><p>To build your application without touching dependencies
-at all, you can use the <code>SKIP_DEPS</code> variable:</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>$ make app <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>This command is very useful if you have a lot of dependencies
-and develop on a machine with slow file access, like the
-Raspberry Pi and many other embedded devices.</p></div>
-<div class="paragraph"><p>Note that this command may fail if a required dependency
-is missing.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_dependencies">Dependencies</h4>
-<div class="paragraph"><p>You can build all dependencies, and nothing else, by
-running the following command:</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>$ make deps</tt></pre></div></div>
-<div class="paragraph"><p>This will fetch and compile all dependencies and their
-dependencies, recursively.</p></div>
-<div class="paragraph"><p><a href="../deps">Packages and dependencies</a> are covered
-in the next chapter.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_release">Release</h4>
-<div class="paragraph"><p>It is not possible to build the release without at least
-building the application itself, unless of course if there’s
-no application to begin with.</p></div>
-<div class="paragraph"><p>To generate the release, <code>make</code> will generally suffice with
-a normal Erlang.mk. A separate target is however available,
-and will take care of building the release, after building
-the application and all dependencies:</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>$ make rel</tt></pre></div></div>
-<div class="paragraph"><p>Consult the <a href="../relx">Releases</a> chapter for more
-information about what releases are and how they are generated.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_application_resource_file">Application resource file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When building your application, Erlang.mk will generate the
-<a href="http://www.erlang.org/doc/man/app.html">application resource file</a>.
-This file is mandatory for all Erlang applications and is
-found in <em>ebin/$(PROJECT).app</em>.</p></div>
-<div class="paragraph"><p><code>PROJECT</code> is a variable defined in your Makefile and taken
-from the name of the directory when Erlang.mk bootstraps
-your project.</p></div>
-<div class="paragraph"><p>Erlang.mk can build the <em>ebin/$(PROJECT).app</em> in two different
-ways: from the configuration found in the Makefile, or from
-the <em>src/$(PROJECT).app.src</em> file.</p></div>
-<div class="sect3">
-<h4 id="_application_configuration">Application configuration</h4>
-<div class="paragraph"><p>Erlang.mk automatically fills the <code>PROJECT</code> variable when
-bootstrapping a new project, but everything else is up to
-you. None of the values are required to build your project,
-although it is recommended to fill everything relevant to
-your situation.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>PROJECT</code>
-</dt>
-<dd>
-<p>
- The name of the OTP application or library.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_DESCRIPTION</code>
-</dt>
-<dd>
-<p>
- Short description of the project.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_VERSION</code>
-</dt>
-<dd>
-<p>
- Current version of the project.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_MOD</code>
-</dt>
-<dd>
-<p>
- The application callback module.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_REGISTERED</code>
-</dt>
-<dd>
-<p>
- List of the names of all registered processes.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_ENV</code>
-</dt>
-<dd>
-<p>
- Configuration parameters used by the application.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_APP_EXTRA_KEYS</code>
-</dt>
-<dd>
-<p>
- Other keys you want to add to the application <code>.app</code> file.
- The variable content is written as-is to the <code>.app</code> file,
- so be sure to format valid Erlang terms. For example:
- <code>PROJECT_APP_EXTRA_KEYS = {maxT, 10000}, {start_phases, [...]}</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LOCAL_DEPS</code>
-</dt>
-<dd>
-<p>
- List of Erlang/OTP applications this project depends on,
- excluding <code>erts</code>, <code>kernel</code> and <code>stdlib</code>, or list of
- dependencies local to this repository (in <code>APPS_DIR</code>).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>DEPS</code>
-</dt>
-<dd>
-<p>
- List of applications this project depends on that need
- to be fetched by Erlang.mk.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>There’s no need for quotes or anything. The relevant part of
-the Cowboy Makefile follows, if you need an example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Any space before and after the value is dropped.</p></div>
-<div class="paragraph"><p><a href="../deps">Dependencies</a> are covered in details in
-the next chapter.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_legacy_method">Legacy method</h4>
-<div class="paragraph"><p>The <em>src/$(PROJECT).app.src</em> file is a legacy method of
-building Erlang applications. It was introduced by the original
-<code>rebar</code> build tool, of which Erlang.mk owes a great deal as it
-is its main inspiration.</p></div>
-<div class="paragraph"><p>The <em>.app.src</em> file serves as a template to generate the <em>.app</em>
-file. Erlang.mk will take it, fill in the <code>modules</code> value
-dynamically, and save the result in <em>ebin/$(PROJECT).app</em>.</p></div>
-<div class="paragraph"><p>When using this method, Erlang.mk cannot fill the <code>applications</code>
-key from dependencies automatically, which means you need to
-add them to Erlang.mk and to the <em>.app.src</em> at the same time,
-duplicating the work.</p></div>
-<div class="paragraph"><p>If you really can’t live without the legacy method, for one
-reason or another, worry not; Erlang.mk will support it. And
-if you need to create a new project that uses this method, you
-just have to say so when bootstrapping:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib <span style="color: #009900">LEGACY</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_automatic_application_resource_file_values">Automatic application resource file values</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When building the application resource file, Erlang.mk may
-automatically add an <code>id</code> key with information about the
-Git commit (if using Git), or an empty string otherwise.
-It will only do this under specific conditions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The application was built as a dependency of another, or
-</p>
-</li>
-<li>
-<p>
-The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This value is most useful when you need to help your users,
-as it allows you to know which version they run exactly by
-asking them to look in the file, or by running a simple
-command on their production server:</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="color: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:get_all_key</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span>
-{<span style="color: #FF6600">ok</span>,[{<span style="color: #FF6600">description</span>,<span style="color: #FF0000">"Small, fast, modular HTTP server."</span>},
- {<span style="color: #FF6600">id</span>,<span style="color: #FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</span>},</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_file_formats">File formats</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports a variety of different source file formats.
-The following formats are supported natively:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Extension </th>
-<th align="center" valign="top"> Location </th>
-<th align="center" valign="top"> Description </th>
-<th align="center" valign="top"> Output</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">.erl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Erlang source</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.core</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Core Erlang source</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.xrl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Leex source</p></td>
-<td align="center" valign="top"><p class="table">src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.yrl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Yecc source</p></td>
-<td align="center" valign="top"><p class="table">src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.asn1</p></td>
-<td align="center" valign="top"><p class="table">asn1/</p></td>
-<td align="center" valign="top"><p class="table">ASN.1 files</p></td>
-<td align="center" valign="top"><p class="table">include/<strong>.hrl include/</strong>.asn1db src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.mib</p></td>
-<td align="center" valign="top"><p class="table">mibs/</p></td>
-<td align="center" valign="top"><p class="table">SNMP MIB files</p></td>
-<td align="center" valign="top"><p class="table">include/<strong>.hrl priv/mibs/</strong>.bin</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>Files are always searched recursively.</p></div>
-<div class="paragraph"><p>The build is ordered, so that files that generate Erlang source
-files are run before, and the resulting Erlang source files are
-then built normally.</p></div>
-<div class="paragraph"><p>In addition, Erlang.mk keeps track of header files (<code>.hrl</code>)
-as described at the end of this chapter. It can also compile
-C code, as described in the <a href="../ports">NIFs and port drivers</a>
-chapter.</p></div>
-<div class="paragraph"><p>Erlang.mk also comes with plugins for the following formats:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Extension </th>
-<th align="center" valign="top"> Location </th>
-<th align="center" valign="top"> Description </th>
-<th align="center" valign="top"> Output</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">.dtl</p></td>
-<td align="center" valign="top"><p class="table">templates/</p></td>
-<td align="center" valign="top"><p class="table">Django templates</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.proto</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Protocol buffers</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_compilation_options">Compilation options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a few variables that you can use to customize
-the build process and the resulting files.</p></div>
-<div class="sect3">
-<h4 id="_erlc_opts">ERLC_OPTS</h4>
-<div class="paragraph"><p><code>ERLC_OPTS</code> can be used to pass some options to <code>erlc</code>, the Erlang
-compiler. Erlang.mk does not restrict any option. Please refer to
-the <a href="http://www.erlang.org/doc/man/erlc.html">erlc Manual</a> for the
-full list.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will set the following options:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>In other words: warnings as errors, debug info (recommended) and
-enable warnings for exported variables, shadow variables and
-obsolete guard functions.</p></div>
-<div class="paragraph"><p>You can redefine this variable in your Makefile to change it
-completely, either before or after including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can also filter out some options from the defaults Erlang.mk
-sets, by defining ERLC_OPTS after including Erlang.mk using the
-<code>:=</code> operator.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-<div class="sect3">
-<h4 id="_erlc_asn1_opts">ERLC_ASN1_OPTS</h4>
-<div class="paragraph"><p><code>ERLC_ASN1_OPTS</code> can be used to pass compiler options when compiling
-ASN.1 files. Please refer to the
-<a href="http://erlang.org/doc/man/asn1ct.html">asn1ct manual</a> for the full list.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will leave this empty.</p></div>
-<div class="paragraph"><p>You can redefine this variable in your Makefile.
-Please see the <code>ERLC_OPTS</code> section for instructions.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4>
-<div class="paragraph"><p><code>ERLC_EXCLUDE</code> can be used to exclude some modules from the
-compilation. It’s there for handling special cases, you should
-not normally need it.</p></div>
-<div class="paragraph"><p>To exclude a module, simply list it in the variable, either
-before or after including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cold_and_hot_builds">Cold and hot builds</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first time you run <code>make</code>, Erlang.mk will build everything.</p></div>
-<div class="paragraph"><p>The second time you run <code>make</code>, and all subsequent times, Erlang.mk
-will only rebuild what changed. Erlang.mk has been optimized for
-this use case, as it is the most common during development.</p></div>
-<div class="paragraph"><p>Erlang.mk figures out what changed by using the dependency tracking
-feature of Make. Make automatically rebuilds a target if one of its
-dependency has changed (for example if a header file has changed,
-all the source files that include it will be rebuilt), and Erlang.mk
-leverages this feature to cut down on rebuild times.</p></div>
-<div class="paragraph"><p>Note that this applies only to building; some other features of
-Erlang.mk will run every time they are called regardless of files
-changed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependency_tracking">Dependency tracking</h2>
-<div class="sectionbody">
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">This section is about the dependency tracking between files
-inside your project, not application dependencies.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>Erlang.mk keeps track of the dependencies between the different
-files in your project. This information is kept in the <em>$(PROJECT).d</em>
-file in your directory. It is generated if missing, and will be
-generated again after every file change, by default.</p></div>
-<div class="paragraph"><p>Dependency tracking is what allows Erlang.mk to know when to
-rebuild Erlang files when header files, behaviors or parse
-transforms have changed. Erlang.mk also automatically keeps
-track of which files should be compiled first, for example
-when you have behaviors used by other modules in your project.</p></div>
-<div class="paragraph"><p>If your project is stable, you may want to disable generating
-the dependency tracking file every time you compile. You can
-do this by adding the following line to your <em>Makefile</em>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>As you can see, the snippet above uses <code>?=</code> instead of a
-simple equal sign. This is to allow you to temporarily override
-this value when you do make substantial changes to your project
-(including a new header file, new module with dependencies, etc.)
-and want to rebuild the dependency tracking file. You’ll be
-able to use the following command:</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="color: #009900">NO_MAKEDEP</span><span style="color: #990000">=</span> make</tt></pre></div></div>
-<div class="paragraph"><p>Otherwise, <code>make clean app</code> will of course force the
-recompilation of your project.</p></div>
-<div class="paragraph"><p>Erlang.mk can also keep track of the source files generated
-by other means, for example if you generate code from a data
-file in your repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_erlang_source">Generating Erlang source</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides hooks at different stages of the build process.
-When your goal is to generate Erlang source files, you can
-add your own rules before or after the dependency tracking
-file is generated. To do this, you would add your hook before
-or after including the <em>erlang.mk</em> file.</p></div>
-<div class="paragraph"><p>The easiest way is after:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>In this case we use <code>$(gen_verbose)</code> to hide the details of
-the build by default. Erlang.mk will simply say what file
-is it currently generating.</p></div>
-<div class="paragraph"><p>When using an external script to generate the Erlang source
-file, it is recommended to depend on that script, so that
-the source file gets generated again when the script gets
-modified.</p></div>
-<div class="paragraph"><p>If for whatever reason you prefer to hook before including
-Erlang.mk, don’t forget to set the <code>.DEFAULT_GOAL</code> variable,
-otherwise nothing will get built:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cleaning">Cleaning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Building typically involves creating a lot of new files. Some
-are reused in rebuilds, some are simply replaced. All can be
-removed safely.</p></div>
-<div class="paragraph"><p>Erlang.mk provides two commands to remove them: <code>clean</code> and
-<code>distclean</code>. <code>clean</code> removes all the intermediate files that
-were created as a result of building, including the BEAM files,
-the dependency tracking file and the generated documentation.
-<code>distclean</code> removes these and more, including the downloaded
-dependencies, Dialyzer’s PLT file and the generated release,
-putting your directory back to the state it was before you
-started working on it.</p></div>
-<div class="paragraph"><p>To clean:</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>$ make clean</tt></pre></div></div>
-<div class="paragraph"><p>Or distclean:</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>$ make distclean</tt></pre></div></div>
-<div class="paragraph"><p>That is the question.</p></div>
-<div class="paragraph"><p>Note that Erlang.mk will automatically clean some files as
-part of other targets, but it will never run <code>distclean</code> if
-you don’t explicitly use it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can do a lot of things, but it is, first and +foremost, a build tool. In this chapter we will cover +the basics of building a project with Erlang.mk.</p></div> +<div class="paragraph"><p>For most of this chapter, we will assume that you are +using a project <a href="../getting_started">generated by Erlang.mk</a>.</p></div> +<div class="sect1"> +<h2 id="_how_to_build">How to build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build a project, all you have to do is type <code>make</code>:</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>$ make</tt></pre></div></div> +<div class="paragraph"><p>It will work regardless of your project: OTP applications, +library applications, NIFs, port drivers or even releases. +Erlang.mk also automatically downloads and compiles the +dependencies for your project.</p></div> +<div class="paragraph"><p>All this is possible thanks to a combination of configuration +and conventions. Most of the conventions come from Erlang/OTP +itself so any seasoned Erlang developers should feel right at +home.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_what_to_build">What to build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk gives you control over three steps of the build +process, allowing you to do a partial build if needed.</p></div> +<div class="paragraph"><p>A build has three phases: first any dependency is fetched +and built, then the project itself is built and finally a +release may be generated when applicable. A release is only +generated for projects specifically configured to do so.</p></div> +<div class="paragraph"><p>Erlang.mk handles those three phases automatically when you +type <code>make</code>. But sometimes you just want to repeat one or +two of them.</p></div> +<div class="paragraph"><p>The commands detailed in this section are most useful after +you have a successful build as they allow you to quickly +redo a step instead of going through everything. This is +especially useful for large projects or projects that end +up generating releases.</p></div> +<div class="sect3"> +<h4 id="_application">Application</h4> +<div class="paragraph"><p>You can build your application and dependencies without +generating a release by running the following command:</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>$ make app</tt></pre></div></div> +<div class="paragraph"><p>To build your application without touching dependencies +at all, you can use the <code>SKIP_DEPS</code> variable:</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>$ make app <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>This command is very useful if you have a lot of dependencies +and develop on a machine with slow file access, like the +Raspberry Pi and many other embedded devices.</p></div> +<div class="paragraph"><p>Note that this command may fail if a required dependency +is missing.</p></div> +</div> +<div class="sect3"> +<h4 id="_dependencies">Dependencies</h4> +<div class="paragraph"><p>You can build all dependencies, and nothing else, by +running the following command:</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>$ make deps</tt></pre></div></div> +<div class="paragraph"><p>This will fetch and compile all dependencies and their +dependencies, recursively.</p></div> +<div class="paragraph"><p><a href="../deps">Packages and dependencies</a> are covered +in the next chapter.</p></div> +</div> +<div class="sect3"> +<h4 id="_release">Release</h4> +<div class="paragraph"><p>It is not possible to build the release without at least +building the application itself, unless of course if there’s +no application to begin with.</p></div> +<div class="paragraph"><p>To generate the release, <code>make</code> will generally suffice with +a normal Erlang.mk. A separate target is however available, +and will take care of building the release, after building +the application and all dependencies:</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>$ make rel</tt></pre></div></div> +<div class="paragraph"><p>Consult the <a href="../relx">Releases</a> chapter for more +information about what releases are and how they are generated.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_application_resource_file">Application resource file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When building your application, Erlang.mk will generate the +<a href="http://www.erlang.org/doc/man/app.html">application resource file</a>. +This file is mandatory for all Erlang applications and is +found in <em>ebin/$(PROJECT).app</em>.</p></div> +<div class="paragraph"><p><code>PROJECT</code> is a variable defined in your Makefile and taken +from the name of the directory when Erlang.mk bootstraps +your project.</p></div> +<div class="paragraph"><p>Erlang.mk can build the <em>ebin/$(PROJECT).app</em> in two different +ways: from the configuration found in the Makefile, or from +the <em>src/$(PROJECT).app.src</em> file.</p></div> +<div class="sect3"> +<h4 id="_application_configuration">Application configuration</h4> +<div class="paragraph"><p>Erlang.mk automatically fills the <code>PROJECT</code> variable when +bootstrapping a new project, but everything else is up to +you. None of the values are required to build your project, +although it is recommended to fill everything relevant to +your situation.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>PROJECT</code> +</dt> +<dd> +<p> + The name of the OTP application or library. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_DESCRIPTION</code> +</dt> +<dd> +<p> + Short description of the project. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_VERSION</code> +</dt> +<dd> +<p> + Current version of the project. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_MOD</code> +</dt> +<dd> +<p> + The application callback module. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_REGISTERED</code> +</dt> +<dd> +<p> + List of the names of all registered processes. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_ENV</code> +</dt> +<dd> +<p> + Configuration parameters used by the application. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_APP_EXTRA_KEYS</code> +</dt> +<dd> +<p> + Other keys you want to add to the application <code>.app</code> file. + The variable content is written as-is to the <code>.app</code> file, + so be sure to format valid Erlang terms. For example: + <code>PROJECT_APP_EXTRA_KEYS = {maxT, 10000}, {start_phases, [...]}</code>. +</p> +</dd> +<dt class="hdlist1"> +<code>LOCAL_DEPS</code> +</dt> +<dd> +<p> + List of Erlang/OTP applications this project depends on, + excluding <code>erts</code>, <code>kernel</code> and <code>stdlib</code>, or list of + dependencies local to this repository (in <code>APPS_DIR</code>). +</p> +</dd> +<dt class="hdlist1"> +<code>DEPS</code> +</dt> +<dd> +<p> + List of applications this project depends on that need + to be fetched by Erlang.mk. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>There’s no need for quotes or anything. The relevant part of +the Cowboy Makefile follows, if you need an example:</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="color: #009900">PROJECT =</span> cowboy +<span style="color: #009900">PROJECT_DESCRIPTION =</span> Small<span style="color: #990000">,</span> fast<span style="color: #990000">,</span> modular HTTP server<span style="color: #990000">.</span> +<span style="color: #009900">PROJECT_VERSION =</span> 2.0.0-pre.2 +<span style="color: #009900">PROJECT_REGISTERED =</span> cowboy_clock + +<span style="color: #009900">LOCAL_DEPS =</span> crypto +<span style="color: #009900">DEPS =</span> cowlib ranch</tt></pre></div></div> +<div class="paragraph"><p>Any space before and after the value is dropped.</p></div> +<div class="paragraph"><p><a href="../deps">Dependencies</a> are covered in details in +the next chapter.</p></div> +</div> +<div class="sect3"> +<h4 id="_legacy_method">Legacy method</h4> +<div class="paragraph"><p>The <em>src/$(PROJECT).app.src</em> file is a legacy method of +building Erlang applications. It was introduced by the original +<code>rebar</code> build tool, of which Erlang.mk owes a great deal as it +is its main inspiration.</p></div> +<div class="paragraph"><p>The <em>.app.src</em> file serves as a template to generate the <em>.app</em> +file. Erlang.mk will take it, fill in the <code>modules</code> value +dynamically, and save the result in <em>ebin/$(PROJECT).app</em>.</p></div> +<div class="paragraph"><p>When using this method, Erlang.mk cannot fill the <code>applications</code> +key from dependencies automatically, which means you need to +add them to Erlang.mk and to the <em>.app.src</em> at the same time, +duplicating the work.</p></div> +<div class="paragraph"><p>If you really can’t live without the legacy method, for one +reason or another, worry not; Erlang.mk will support it. And +if you need to create a new project that uses this method, you +just have to say so when bootstrapping:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib <span style="color: #009900">LEGACY</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_automatic_application_resource_file_values">Automatic application resource file values</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When building the application resource file, Erlang.mk may +automatically add an <code>id</code> key with information about the +Git commit (if using Git), or an empty string otherwise. +It will only do this under specific conditions:</p></div> +<div class="ulist"><ul> +<li> +<p> +The application was built as a dependency of another, or +</p> +</li> +<li> +<p> +The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>This value is most useful when you need to help your users, +as it allows you to know which version they run exactly by +asking them to look in the file, or by running a simple +command on their production server:</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="color: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:get_all_key</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span> +{<span style="color: #FF6600">ok</span>,[{<span style="color: #FF6600">description</span>,<span style="color: #FF0000">"Small, fast, modular HTTP server."</span>}, + {<span style="color: #FF6600">id</span>,<span style="color: #FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</span>},</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_file_formats">File formats</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports a variety of different source file formats. +The following formats are supported natively:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Extension </th> +<th align="center" valign="top"> Location </th> +<th align="center" valign="top"> Description </th> +<th align="center" valign="top"> Output</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">.erl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Erlang source</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.core</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Core Erlang source</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.xrl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Leex source</p></td> +<td align="center" valign="top"><p class="table">src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.yrl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Yecc source</p></td> +<td align="center" valign="top"><p class="table">src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.asn1</p></td> +<td align="center" valign="top"><p class="table">asn1/</p></td> +<td align="center" valign="top"><p class="table">ASN.1 files</p></td> +<td align="center" valign="top"><p class="table">include/<strong>.hrl include/</strong>.asn1db src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.mib</p></td> +<td align="center" valign="top"><p class="table">mibs/</p></td> +<td align="center" valign="top"><p class="table">SNMP MIB files</p></td> +<td align="center" valign="top"><p class="table">include/<strong>.hrl priv/mibs/</strong>.bin</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>Files are always searched recursively.</p></div> +<div class="paragraph"><p>The build is ordered, so that files that generate Erlang source +files are run before, and the resulting Erlang source files are +then built normally.</p></div> +<div class="paragraph"><p>In addition, Erlang.mk keeps track of header files (<code>.hrl</code>) +as described at the end of this chapter. It can also compile +C code, as described in the <a href="../ports">NIFs and port drivers</a> +chapter.</p></div> +<div class="paragraph"><p>Erlang.mk also comes with plugins for the following formats:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Extension </th> +<th align="center" valign="top"> Location </th> +<th align="center" valign="top"> Description </th> +<th align="center" valign="top"> Output</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">.dtl</p></td> +<td align="center" valign="top"><p class="table">templates/</p></td> +<td align="center" valign="top"><p class="table">Django templates</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.proto</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Protocol buffers</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_compilation_options">Compilation options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a few variables that you can use to customize +the build process and the resulting files.</p></div> +<div class="sect3"> +<h4 id="_erlc_opts">ERLC_OPTS</h4> +<div class="paragraph"><p><code>ERLC_OPTS</code> can be used to pass some options to <code>erlc</code>, the Erlang +compiler. Erlang.mk does not restrict any option. Please refer to +the <a href="http://www.erlang.org/doc/man/erlc.html">erlc Manual</a> for the +full list.</p></div> +<div class="paragraph"><p>By default, Erlang.mk will set the following options:</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="color: #009900">ERLC_OPTS =</span> -Werror <span style="color: #990000">+</span>debug_info <span style="color: #990000">+</span>warn_export_vars <span style="color: #990000">+</span>warn_shadow_vars <span style="color: #990000">+</span>warn_obsolete_guard</tt></pre></div></div> +<div class="paragraph"><p>In other words: warnings as errors, debug info (recommended) and +enable warnings for exported variables, shadow variables and +obsolete guard functions.</p></div> +<div class="paragraph"><p>You can redefine this variable in your Makefile to change it +completely, either before or after including Erlang.mk:</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="color: #009900">ERLC_OPTS =</span> <span style="color: #990000">+</span>debug_info</tt></pre></div></div> +<div class="paragraph"><p>You can also filter out some options from the defaults Erlang.mk +sets, by defining ERLC_OPTS after including Erlang.mk using the +<code>:=</code> operator.</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>include erlang.mk + +<span style="color: #990000">ERLC_OPTS :=</span> <span style="color: #009900">$(</span>filter-out -Werror<span style="color: #990000">,</span><span style="color: #009900">$(ERLC_OPTS))</span></tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_erlc_asn1_opts">ERLC_ASN1_OPTS</h4> +<div class="paragraph"><p><code>ERLC_ASN1_OPTS</code> can be used to pass compiler options when compiling +ASN.1 files. Please refer to the +<a href="http://erlang.org/doc/man/asn1ct.html">asn1ct manual</a> for the full list.</p></div> +<div class="paragraph"><p>By default, Erlang.mk will leave this empty.</p></div> +<div class="paragraph"><p>You can redefine this variable in your Makefile. +Please see the <code>ERLC_OPTS</code> section for instructions.</p></div> +</div> +<div class="sect3"> +<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4> +<div class="paragraph"><p><code>ERLC_EXCLUDE</code> can be used to exclude some modules from the +compilation. It’s there for handling special cases, you should +not normally need it.</p></div> +<div class="paragraph"><p>To exclude a module, simply list it in the variable, either +before or after including Erlang.mk:</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="color: #009900">ERLC_EXCLUDE =</span> cowboy_http2</tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_cold_and_hot_builds">Cold and hot builds</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first time you run <code>make</code>, Erlang.mk will build everything.</p></div> +<div class="paragraph"><p>The second time you run <code>make</code>, and all subsequent times, Erlang.mk +will only rebuild what changed. Erlang.mk has been optimized for +this use case, as it is the most common during development.</p></div> +<div class="paragraph"><p>Erlang.mk figures out what changed by using the dependency tracking +feature of Make. Make automatically rebuilds a target if one of its +dependency has changed (for example if a header file has changed, +all the source files that include it will be rebuilt), and Erlang.mk +leverages this feature to cut down on rebuild times.</p></div> +<div class="paragraph"><p>Note that this applies only to building; some other features of +Erlang.mk will run every time they are called regardless of files +changed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependency_tracking">Dependency tracking</h2> +<div class="sectionbody"> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content">This section is about the dependency tracking between files +inside your project, not application dependencies.</td> +</tr></table> +</div> +<div class="paragraph"><p>Erlang.mk keeps track of the dependencies between the different +files in your project. This information is kept in the <em>$(PROJECT).d</em> +file in your directory. It is generated if missing, and will be +generated again after every file change, by default.</p></div> +<div class="paragraph"><p>Dependency tracking is what allows Erlang.mk to know when to +rebuild Erlang files when header files, behaviors or parse +transforms have changed. Erlang.mk also automatically keeps +track of which files should be compiled first, for example +when you have behaviors used by other modules in your project.</p></div> +<div class="paragraph"><p>If your project is stable, you may want to disable generating +the dependency tracking file every time you compile. You can +do this by adding the following line to your <em>Makefile</em>:</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>NO_MAKEDEP <span style="color: #990000">?=</span> <span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>As you can see, the snippet above uses <code>?=</code> instead of a +simple equal sign. This is to allow you to temporarily override +this value when you do make substantial changes to your project +(including a new header file, new module with dependencies, etc.) +and want to rebuild the dependency tracking file. You’ll be +able to use the following command:</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="color: #009900">NO_MAKEDEP</span><span style="color: #990000">=</span> make</tt></pre></div></div> +<div class="paragraph"><p>Otherwise, <code>make clean app</code> will of course force the +recompilation of your project.</p></div> +<div class="paragraph"><p>Erlang.mk can also keep track of the source files generated +by other means, for example if you generate code from a data +file in your repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_erlang_source">Generating Erlang source</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides hooks at different stages of the build process. +When your goal is to generate Erlang source files, you can +add your own rules before or after the dependency tracking +file is generated. To do this, you would add your hook before +or after including the <em>erlang.mk</em> file.</p></div> +<div class="paragraph"><p>The easiest way is after:</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="color: #009900">PROJECT =</span> example + +include erlang.mk + +<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl + +src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh + <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div> +<div class="paragraph"><p>In this case we use <code>$(gen_verbose)</code> to hide the details of +the build by default. Erlang.mk will simply say what file +is it currently generating.</p></div> +<div class="paragraph"><p>When using an external script to generate the Erlang source +file, it is recommended to depend on that script, so that +the source file gets generated again when the script gets +modified.</p></div> +<div class="paragraph"><p>If for whatever reason you prefer to hook before including +Erlang.mk, don’t forget to set the <code>.DEFAULT_GOAL</code> variable, +otherwise nothing will get built:</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="color: #009900">PROJECT =</span> example + +.DEFAULT_GOAL <span style="color: #990000">=</span> all + +<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl + +include erlang.mk + +src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh + <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_cleaning">Cleaning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Building typically involves creating a lot of new files. Some +are reused in rebuilds, some are simply replaced. All can be +removed safely.</p></div> +<div class="paragraph"><p>Erlang.mk provides two commands to remove them: <code>clean</code> and +<code>distclean</code>. <code>clean</code> removes all the intermediate files that +were created as a result of building, including the BEAM files, +the dependency tracking file and the generated documentation. +<code>distclean</code> removes these and more, including the downloaded +dependencies, Dialyzer’s PLT file and the generated release, +putting your directory back to the state it was before you +started working on it.</p></div> +<div class="paragraph"><p>To clean:</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>$ make clean</tt></pre></div></div> +<div class="paragraph"><p>Or distclean:</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>$ make distclean</tt></pre></div></div> +<div class="paragraph"><p>That is the question.</p></div> +<div class="paragraph"><p>Note that Erlang.mk will automatically clean some files as +part of other targets, but it will never run <code>distclean</code> if +you don’t explicitly use it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/asciidoc/index.html b/docs/en/erlang.mk/1/guide/asciidoc/index.html index f188ff6f..e0a10d20 100644 --- a/docs/en/erlang.mk/1/guide/asciidoc/index.html +++ b/docs/en/erlang.mk/1/guide/asciidoc/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: AsciiDoc documentation</title> @@ -67,106 +67,109 @@ <h1 class="lined-header"><span>AsciiDoc documentation</span></h1> -<div class="paragraph"><p>Erlang.mk provides rules for generating documentation from
-AsciiDoc files. It can automatically build a user guide PDF,
-chunked HTML documentation and Unix manual pages.</p></div>
-<div class="sect1">
-<h2 id="_requirements">Requirements</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>,
-<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and
-<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your
-system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="http://asciidoc.org/">AsciiDoc</a> is a text document format for
-writing notes, documentation, articles, books, ebooks, slideshows,
-web pages, man pages and blogs. AsciiDoc files can be translated
-to many formats including HTML, PDF, EPUB, man page.</p></div>
-<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a>
-describes the AsciiDoc syntax.</p></div>
-<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a>
-is written in AsciiDoc and can be used as an example. The entry
-file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div>
-<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific
-location. This is <em>doc/src/guide/</em> for the user guide, and
-<em>doc/src/manual/</em> for the function reference. In the case of
-the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div>
-<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for
-modules, and section 7 for the application itself.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly
-inside the files themselves.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build all documentation:</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>$ make docs</tt></pre></div></div>
-<div class="paragraph"><p>To build only the AsciiDoc documentation:</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>$ make asciidoc</tt></pre></div></div>
-<div class="paragraph"><p>To build only the user guide:</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>$ make asciidoc-guide</tt></pre></div></div>
-<div class="paragraph"><p>To build only the manual:</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>$ make asciidoc-manual</tt></pre></div></div>
-<div class="paragraph"><p>To install man pages on Unix:</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>$ make install-docs</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections
-of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable
-defines where man pages will be installed. It defaults to
-<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines
-which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div>
-<div class="paragraph"><p>To install man pages to a custom location:</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>$ make install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div>
-<div class="paragraph"><p>Note that you may need to run the install commands using
-<code>sudo</code> or equivalent if the location is not writeable by
-your user.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides rules for generating documentation from +AsciiDoc files. It can automatically build a user guide PDF, +chunked HTML documentation and Unix manual pages.</p></div> +<div class="sect1"> +<h2 id="_requirements">Requirements</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>, +<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and +<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="http://asciidoc.org/">AsciiDoc</a> is a text document format for +writing notes, documentation, articles, books, ebooks, slideshows, +web pages, man pages and blogs. AsciiDoc files can be translated +to many formats including HTML, PDF, EPUB, man page.</p></div> +<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a> +describes the AsciiDoc syntax.</p></div> +<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a> +is written in AsciiDoc and can be used as an example. The entry +file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div> +<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific +location. This is <em>doc/src/guide/</em> for the user guide, and +<em>doc/src/manual/</em> for the function reference. In the case of +the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div> +<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for +modules, and section 7 for the application itself.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly +inside the files themselves.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build all documentation:</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>$ make docs</tt></pre></div></div> +<div class="paragraph"><p>To build only the AsciiDoc documentation:</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>$ make asciidoc</tt></pre></div></div> +<div class="paragraph"><p>To build only the user guide:</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>$ make asciidoc-guide</tt></pre></div></div> +<div class="paragraph"><p>To build only the manual:</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>$ make asciidoc-manual</tt></pre></div></div> +<div class="paragraph"><p>To install man pages on Unix:</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>$ make install-docs</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections +of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable +defines where man pages will be installed. It defaults to +<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines +which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div> +<div class="paragraph"><p>To install man pages to a custom location:</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>$ make install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div> +<div class="paragraph"><p>Note that you may need to run the install commands using +<code>sudo</code> or equivalent if the location is not writeable by +your user.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/ci.asciidoc b/docs/en/erlang.mk/1/guide/ci.asciidoc index 24cfc053..2b69e282 100644 --- a/docs/en/erlang.mk/1/guide/ci.asciidoc +++ b/docs/en/erlang.mk/1/guide/ci.asciidoc @@ -1,6 +1,66 @@ [[ci]] == Continuous integration -// @todo Write it. +Erlang.mk comes with some support for continuous integration, +aimed at open source projects that need to support more than +one specific Erlang/OTP release. (If you target one specific +release, check the xref:otp_version_pinning[OTP version pinning] +section of the xref:kerl[OTP version management] chapter.) -Placeholder chapter. +=== Configuring Erlang/OTP versions to test + +To use the CI plugin you must first configure which versions +of Erlang/OTP will be used. Erlang.mk provides three separate +configuration variables depending on whether you need a normal +OTP release, a HiPE-enabled release or an ErLLVM-enabled release. + +At the time of writing, this is how you would test against all +the most recent patch releases of Erlang/OTP 19 and above: + +[source,make] +CI_OTP = OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4 + +If you want to test against HiPE and ErLLVM but only with the +latest version of Erlang/OTP, the following could work: + +[source,make] +CI_HIPE = $(lastword $(CI_OTP)) +CI_ERLLVM = $(CI_HIPE) + +Consult the xref:kerl[OTP version management] chapter for more +information about Erlang/OTP versions and customization of the +Erlang/OTP builds. + +=== Running tests across all configured versions + +The recommended way to run the `ci` target is with the option +`-k`. It will ensure that tests are run for all configured +Erlang/OTP versions, even if there are errors: + +[source,bash] +$ make ci -k + +=== Extending the CI targets + +The `ci` target can be extended. For example to run Dialyzer +at the end of CI: + +[source,make] +---- +ci:: dialyze +---- + +Additional setup can be done by extending the `ci-setup` +target. This target is ran before testing each individual +Erlang/OTP version. + +For example, to ensure dependencies are re-fetched/built +before testing individual Erlang/OTP releases: + +[source,make] +---- +ci-setup:: distclean +---- + +Similarly, the `ci-extra` target can be extended to run +extra commands after an Erlang/OTP version has been tested. diff --git a/docs/en/erlang.mk/1/guide/ci/index.html b/docs/en/erlang.mk/1/guide/ci/index.html index e4db9a8a..e73333f6 100644 --- a/docs/en/erlang.mk/1/guide/ci/index.html +++ b/docs/en/erlang.mk/1/guide/ci/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Continuous integration</title> @@ -67,13 +67,89 @@ <h1 class="lined-header"><span>Continuous integration</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Erlang.mk comes with some support for continuous integration, +aimed at open source projects that need to support more than +one specific Erlang/OTP release. (If you target one specific +release, check the <a href="../otp_version_pinning">OTP version pinning</a> +section of the <a href="../kerl">OTP version management</a> chapter.)</p></div> +<div class="sect1"> +<h2 id="_configuring_erlang_otp_versions_to_test">Configuring Erlang/OTP versions to test</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To use the CI plugin you must first configure which versions +of Erlang/OTP will be used. Erlang.mk provides three separate +configuration variables depending on whether you need a normal +OTP release, a HiPE-enabled release or an ErLLVM-enabled release.</p></div> +<div class="paragraph"><p>At the time of writing, this is how you would test against all +the most recent patch releases of Erlang/OTP 19 and above:</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="color: #009900">CI_OTP =</span> OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4</tt></pre></div></div> +<div class="paragraph"><p>If you want to test against HiPE and ErLLVM but only with the +latest version of Erlang/OTP, the following could work:</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="color: #009900">CI_HIPE =</span> <span style="color: #009900">$(</span>lastword <span style="color: #009900">$(CI_OTP))</span> +<span style="color: #009900">CI_ERLLVM =</span> <span style="color: #009900">$(CI_HIPE)</span></tt></pre></div></div> +<div class="paragraph"><p>Consult the <a href="../kerl">OTP version management</a> chapter for more +information about Erlang/OTP versions and customization of the +Erlang/OTP builds.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_tests_across_all_configured_versions">Running tests across all configured versions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The recommended way to run the <code>ci</code> target is with the option +<code>-k</code>. It will ensure that tests are run for all configured +Erlang/OTP versions, even if there are errors:</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>$ make ci -k</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_extending_the_ci_targets">Extending the CI targets</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ci</code> target can be extended. For example to run Dialyzer +at the end of CI:</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="color: #990000">ci::</span> dialyze</tt></pre></div></div> +<div class="paragraph"><p>Additional setup can be done by extending the <code>ci-setup</code> +target. This target is ran before testing each individual +Erlang/OTP version.</p></div> +<div class="paragraph"><p>For example, to ensure dependencies are re-fetched/built +before testing individual Erlang/OTP releases:</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="color: #990000">ci-setup::</span> distclean</tt></pre></div></div> +<div class="paragraph"><p>Similarly, the <code>ci-extra</code> target can be extended to run +extra commands after an Erlang/OTP version has been tested.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/common_test/index.html b/docs/en/erlang.mk/1/guide/common_test/index.html index 74e9c912..7933d41a 100644 --- a/docs/en/erlang.mk/1/guide/common_test/index.html +++ b/docs/en/erlang.mk/1/guide/common_test/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Common Test</title> @@ -67,121 +67,136 @@ <h1 class="lined-header"><span>Common Test</span></h1> -<div class="paragraph"><p>Common Test is Erlang’s functional testing framework.
-Erlang.mk automates the discovery and running of Common
-Test suites.</p></div>
-<div class="sect1">
-<h2 id="_writing_tests">Writing tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/common_test/write_test_chapter.html">Common Test user guide</a>
-is the best place to learn how to write tests. Erlang.mk
-requires that file names for test suites end with <em>_SUITE.erl</em>
-and that the files be located in the <em>$(TEST_DIR)</em> directory.
-This defaults to <em>test/</em>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>CT_OPTS</code> variable allows you to set extra Common Test
-options. Options are documented in the
-<a href="http://www.erlang.org/doc/apps/common_test/run_test_chapter.html">Common Test user guide</a>.
-You can use it to set Common Test hooks, for example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>CT_SUITES</code> variable can be used to override what
-Common Test suites Erlang.mk will be aware of. It does
-not normally need to be set as Erlang.mk will find the
-test suites automatically.</p></div>
-<div class="paragraph"><p>The name of the suite is the part before <code>_SUITE.erl</code>.
-If the file is named <em>http_SUITE.erl</em>, the test suite
-is <code>http</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>CT_LOGS_DIR</code> variable can be used to set where HTML
-log files are to be written. This defaults to <em>logs/</em>.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To run all tests (including Common Test):</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>$ make tests</tt></pre></div></div>
-<div class="paragraph"><p>To run all tests and static checks (including Common Test):</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>$ make check</tt></pre></div></div>
-<div class="paragraph"><p>You can also run Common Test separately:</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>$ make ct</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will create targets for all test suites it finds.
-If you have a file named <em>test/http_SUITE.erl</em>, then the
-target <code>ct-http</code> will run that specific test suite:</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>$ make ct-http</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk provides a convenient way to run a specific
-group or a specific test case within a specific group,
-using the variable <code>t</code>. Note that this only applies to
-suite-specific targets, like the <code>ct-http</code> example above.</p></div>
-<div class="paragraph"><p>To run all tests from the <code>http_compress</code> group in the
-<code>http_SUITE</code> test suite, write:</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>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div>
-<div class="paragraph"><p>Similarly, to run a specific test case in that group:</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>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress<span style="color: #990000">:</span>headers_dupe</tt></pre></div></div>
-<div class="paragraph"><p>To do the same against a multi-application repository,
-you can use the <code>-C</code> option:</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>$ make -C apps/my_app ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>my_group<span style="color: #990000">:</span>my_case</tt></pre></div></div>
-<div class="paragraph"><p>Note that this also applies to dependencies. When using Cowboy
-as a dependency, you can run the following directly:</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>$ make -C deps/cowboy ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div>
-<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available,
-but covered in its own chapter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Common Test is Erlang’s functional testing framework. +Erlang.mk automates the discovery and running of Common +Test suites.</p></div> +<div class="sect1"> +<h2 id="_writing_tests">Writing tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/common_test/write_test_chapter.html">Common Test user guide</a> +is the best place to learn how to write tests. Erlang.mk +requires that file names for test suites end with <em>_SUITE.erl</em> +and that the files be located in the <em>$(TEST_DIR)</em> directory. +This defaults to <em>test/</em>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>CT_OPTS</code> variable allows you to set extra Common Test +options. Options are documented in the +<a href="http://www.erlang.org/doc/apps/common_test/run_test_chapter.html">Common Test user guide</a>. +You can use it to set Common Test hooks, for example:</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="color: #009900">CT_OPTS =</span> -ct_hooks cowboy_ct_hook</tt></pre></div></div> +<div class="paragraph"><p>The <code>CT_SUITES</code> variable can be used to override what +Common Test suites Erlang.mk will be aware of. It does +not normally need to be set as Erlang.mk will find the +test suites automatically.</p></div> +<div class="paragraph"><p>The name of the suite is the part before <code>_SUITE.erl</code>. +If the file is named <em>http_SUITE.erl</em>, the test suite +is <code>http</code>:</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="color: #009900">CT_SUITES =</span> http ws</tt></pre></div></div> +<div class="paragraph"><p>The <code>CT_LOGS_DIR</code> variable can be used to set where HTML +log files are to be written. This defaults to <em>logs/</em>.</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="color: #009900">CT_LOGS_DIR =</span> ct_output_log_dir</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To run all tests (including Common Test):</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>$ make tests</tt></pre></div></div> +<div class="paragraph"><p>To run all tests and static checks (including Common Test):</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>$ make check</tt></pre></div></div> +<div class="paragraph"><p>You can also run Common Test separately:</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>$ make ct</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will create targets for all test suites it finds. +If you have a file named <em>test/http_SUITE.erl</em>, then the +target <code>ct-http</code> will run that specific test suite:</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>$ make ct-http</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk provides a convenient way to run a specific +group or a specific test case within a specific group, +using the variable <code>t</code>. Note that this only applies to +suite-specific targets, like the <code>ct-http</code> example above.</p></div> +<div class="paragraph"><p>To run all tests from the <code>http_compress</code> group in the +<code>http_SUITE</code> test suite, write:</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>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Similarly, to run a specific test case in that group:</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>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress<span style="color: #990000">:</span>headers_dupe</tt></pre></div></div> +<div class="paragraph"><p>To do the same against a multi-application repository, +you can use the <code>-C</code> option:</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>$ make -C apps/my_app ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>my_group<span style="color: #990000">:</span>my_case</tt></pre></div></div> +<div class="paragraph"><p>Note that this also applies to dependencies. When using Cowboy +as a dependency, you can run the following directly:</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>$ make -C deps/cowboy ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available, +but covered in its own chapter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/compat/index.html b/docs/en/erlang.mk/1/guide/compat/index.html index da880762..d257d9ee 100644 --- a/docs/en/erlang.mk/1/guide/compat/index.html +++ b/docs/en/erlang.mk/1/guide/compat/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Compatibility with other build tools</title> @@ -67,97 +67,104 @@ <h1 class="lined-header"><span>Compatibility with other build tools</span></h1> -<div class="paragraph"><p>Erlang.mk tries its best to be compatible with the other Erlang
-build tools. It can use dependencies written with other build
-tools in mind, and can also make your projects usable by those
-build tools as well. Erlang.mk is like the cool kid that gets
-along with everybody.</p></div>
-<div class="paragraph"><p>In this chapter I will use the term <em>Rebar project</em> to refer
-to a project built using Rebar 2, Rebar 3 or Mad. These three
-build tools are very similar and share the same configuration
-file.</p></div>
-<div class="sect1">
-<h2 id="_rebar_projects_as_erlang_mk_dependencies">Rebar projects as Erlang.mk dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk comes with a feature called <em>Autoload</em> which will
-use Rebar 2 to patch any Rebar project and make it compatible
-with Erlang.mk. This feature essentially patches Rebar out
-and adds a Makefile to the project that Erlang.mk can then
-use for building:</p></div>
-<div class="paragraph"><p><em>Autoload</em> is documented in more details in the
-<a href="../deps">Packages and dependencies</a> chapter.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_projects_as_rebar_dependencies">Erlang.mk projects as Rebar dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk projects can be made compatible with the Rebar family
-of build tools pretty easily, as Erlang.mk will generate
-all the files they require for building.</p></div>
-<div class="paragraph"><p>The Rebar family requires two files: a <em>rebar.config</em> file
-containing compilation options and the list of dependencies,
-and the application resource file, found either at
-<em>ebin/$(PROJECT).app</em> or at <em>src/$(PROJECT).app.src</em>.</p></div>
-<div class="sect3">
-<h4 id="_rebar_configuration">Rebar configuration</h4>
-<div class="paragraph"><p>Erlang.mk comes with a target that generates a <em>rebar.config</em>
-file when invoked:</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>$ make rebar<span style="color: #990000">.</span>config</tt></pre></div></div>
-<div class="paragraph"><p>Careful! This will build the file even if it already existed
-before.</p></div>
-<div class="paragraph"><p>To build this file, Erlang.mk uses information it finds in
-the <code>DEPS</code> and <code>ERLC_OPTS</code> variables, among others. This
-means that the Rebar family builds your project much the
-same way as Erlang.mk.</p></div>
-<div class="paragraph"><p>Careful though! Different build tools have different fetching
-strategies. If some applications provide differing dependencies,
-they might be fetched differently by other build tools. Check
-the upcoming Sanity check chapter to find out how to detect such
-issues.</p></div>
-<div class="paragraph"><p>You can automatically generate this file when you build
-your application, by making it a dependency of the <code>app</code>
-target:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Don’t forget to commit the file when it changes!</p></div>
-<div class="paragraph"><p>If you run into other issues, it’s probably because you use a
-feature specific to Erlang.mk, like the <code>cp</code> fetch method.
-It could also be that we forgot to handle something! Sorry.
-We are of course interested to hear about any compatibility
-problems you may have, just open a ticket!</p></div>
-</div>
-<div class="sect3">
-<h4 id="_application_resource_file">Application resource file</h4>
-<div class="paragraph"><p>Erlang.mk has two ways to generate an application resource
-file: from the information found in the Makefile, or from
-the information found in the <em>src/$(PROJECT).app.src</em> file.
-Needless to say, if you have this file in your repository,
-then you don’t need to worry about compatibility with other
-build tools.</p></div>
-<div class="paragraph"><p>If you don’t, however, it’s not much harder. Every time
-Erlang.mk will compile your application, it will produce
-a new <em>ebin/$(PROJECT).app</em> file. Simply commit this file
-when it changes. It will only change when you modify the
-configuration, add or remove modules.</p></div>
-</div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk tries its best to be compatible with the other Erlang +build tools. It can use dependencies written with other build +tools in mind, and can also make your projects usable by those +build tools as well. Erlang.mk is like the cool kid that gets +along with everybody.</p></div> +<div class="paragraph"><p>In this chapter I will use the term <em>Rebar project</em> to refer +to a project built using Rebar 2, Rebar 3 or Mad. These three +build tools are very similar and share the same configuration +file.</p></div> +<div class="sect1"> +<h2 id="_rebar_projects_as_erlang_mk_dependencies">Rebar projects as Erlang.mk dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk comes with a feature called <em>Autoload</em> which will +use Rebar 2 to patch any Rebar project and make it compatible +with Erlang.mk. This feature essentially patches Rebar out +and adds a Makefile to the project that Erlang.mk can then +use for building:</p></div> +<div class="paragraph"><p><em>Autoload</em> is documented in more details in the +<a href="../deps">Packages and dependencies</a> chapter.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_projects_as_rebar_dependencies">Erlang.mk projects as Rebar dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk projects can be made compatible with the Rebar family +of build tools pretty easily, as Erlang.mk will generate +all the files they require for building.</p></div> +<div class="paragraph"><p>The Rebar family requires two files: a <em>rebar.config</em> file +containing compilation options and the list of dependencies, +and the application resource file, found either at +<em>ebin/$(PROJECT).app</em> or at <em>src/$(PROJECT).app.src</em>.</p></div> +<div class="sect3"> +<h4 id="_rebar_configuration">Rebar configuration</h4> +<div class="paragraph"><p>Erlang.mk comes with a target that generates a <em>rebar.config</em> +file when invoked:</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>$ make rebar<span style="color: #990000">.</span>config</tt></pre></div></div> +<div class="paragraph"><p>Careful! This will build the file even if it already existed +before.</p></div> +<div class="paragraph"><p>To build this file, Erlang.mk uses information it finds in +the <code>DEPS</code> and <code>ERLC_OPTS</code> variables, among others. This +means that the Rebar family builds your project much the +same way as Erlang.mk.</p></div> +<div class="paragraph"><p>Careful though! Different build tools have different fetching +strategies. If some applications provide differing dependencies, +they might be fetched differently by other build tools. Check +the upcoming Sanity check chapter to find out how to detect such +issues.</p></div> +<div class="paragraph"><p>You can automatically generate this file when you build +your application, by making it a dependency of the <code>app</code> +target:</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="color: #990000">app::</span> rebar.config</tt></pre></div></div> +<div class="paragraph"><p>Don’t forget to commit the file when it changes!</p></div> +<div class="paragraph"><p>If you run into other issues, it’s probably because you use a +feature specific to Erlang.mk, like the <code>cp</code> fetch method. +It could also be that we forgot to handle something! Sorry. +We are of course interested to hear about any compatibility +problems you may have, just open a ticket!</p></div> +</div> +<div class="sect3"> +<h4 id="_application_resource_file">Application resource file</h4> +<div class="paragraph"><p>Erlang.mk has two ways to generate an application resource +file: from the information found in the Makefile, or from +the information found in the <em>src/$(PROJECT).app.src</em> file. +Needless to say, if you have this file in your repository, +then you don’t need to worry about compatibility with other +build tools.</p></div> +<div class="paragraph"><p>If you don’t, however, it’s not much harder. Every time +Erlang.mk will compile your application, it will produce +a new <em>ebin/$(PROJECT).app</em> file. Simply commit this file +when it changes. It will only change when you modify the +configuration, add or remove modules.</p></div> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> - <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/"> - Escripts + <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/"> + OTP version management </a> diff --git a/docs/en/erlang.mk/1/guide/contributing/index.html b/docs/en/erlang.mk/1/guide/contributing/index.html index 0d549029..c6719e0c 100644 --- a/docs/en/erlang.mk/1/guide/contributing/index.html +++ b/docs/en/erlang.mk/1/guide/contributing/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Contributing</title> @@ -67,137 +67,140 @@ <h1 class="lined-header"><span>Contributing</span></h1> -<div class="paragraph"><p>You are welcome and encouraged to contribute.</p></div>
-<div class="paragraph"><p>This is how.</p></div>
-<div class="sect1">
-<h2 id="_priorities">Priorities</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>From the most important to the least important:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Bugs
-</p>
-</li>
-<li>
-<p>
-Package issues/additions
-</p>
-</li>
-<li>
-<p>
-Refactoring
-</p>
-</li>
-<li>
-<p>
-Features
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_bugs">Bugs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you have found a bug, you should open a ticket. Include
-everything relevant including the command you used, output,
-a link to the code that triggers the issue, why you think
-this is a bug, etc.</p></div>
-<div class="paragraph"><p>If you think you have found a bug but you are not sure, you
-should open a ticket as previously explained.</p></div>
-<div class="paragraph"><p>If you have found a bug and you need it to be solved RIGHT
-NOW, open a ticket as previously explained.</p></div>
-<div class="paragraph"><p>Once you have opened a ticket, be patient, try to answer
-questions in a timely manner and confirm that the bug was
-indeed fixed when it is.</p></div>
-<div class="paragraph"><p>If you can’t be patient, either try to solve the bug and
-contribute the fix back or become a paying customer.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_code">Code</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The code is located in the <em>core/*.mk</em> and <em>plugins/*.mk</em> files.
-The tests are located in the <em>test/Makefile</em> and <em>test/*.mk</em> files.</p></div>
-<div class="paragraph"><p>If you have a fix or a hack for a bug, you should open a
-pull request. Any fix should include a test case that fails
-before the fix and is working after.</p></div>
-<div class="paragraph"><p>If you have a test case that reproduces a bug, but no fix for
-it, you should open a pull request.</p></div>
-<div class="paragraph"><p>Changes need to be tested with at least the <code>make check</code>
-command. A specific test case can be tested using <code>make check c=CASE</code>
-with <code>CASE</code> the name of the target to run. Output can be
-modulated using the <code>V</code> variable, which is an integer
-from 0 to 4. A typical use would be <code>make check c=dialyzer V=3</code>.
-The value 4 is particular and shows expanded commands right
-before they are executed.</p></div>
-<div class="paragraph"><p>To run tests in parallel, use the <code>-j</code> option. It is generally
-a good idea to also use the <code>-k</code> option to run all tests even
-if one fails. For example: <code>make check -j 32 -k</code>.</p></div>
-<div class="paragraph"><p>Some changes should be tested against all packages. Continue
-reading for more details on testing them.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_packages">Packages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can search existing packages using the <code>make search q=STRING</code>
-command. This can be done both from an Erlang.mk project or
-directly from the Erlang.mk repository.</p></div>
-<div class="paragraph"><p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</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>$ git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com<span style="color: #990000">/</span><span style="color: #009900">$YOURUSERNAME</span>/erlang<span style="color: #990000">.</span>mk
-$ cd erlang<span style="color: #990000">.</span>mk
-$ <span style="color: #990000">.</span>/pkg_add<span style="color: #990000">.</span>sh cowboy git https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/cowboy <span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span>
- http<span style="color: #990000">:</span>//ninenines<span style="color: #990000">.</span>eu <span style="color: #FF0000">"Small, fast and modular HTTP server."</span>
-$ git push origin master</tt></pre></div></div>
-<div class="paragraph"><p>Before sending a pull request, you should test your package.
-You can use the following command: <code>make check p=PACKAGE</code>,
-where <code>PACKAGE</code> is the name of the package, for example
-<code>cowboy</code>.</p></div>
-<div class="paragraph"><p>To test all packages, the <code>make packages</code> command can be used.
-This can take a long time. Some packages will fail with certain
-versions of Erlang, or if a prerequisite is missing from your system.
-You can of course speed things up using the <code>-j</code> and <code>-k</code> flags.</p></div>
-<div class="paragraph"><p>After all packages have been tested, you can run the command
-<code>make summary</code> to know what changed since the previous run.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_documentation">Documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The documentation is always right.</p></div>
-<div class="paragraph"><p>If you think you have found a mistake in the documentation,
-this is a bug. You can either open a ticket or send a pull
-request.</p></div>
-<div class="paragraph"><p>To make sure that the documentation changes work, install
-the listed <a href="../asciidoc">Requirements</a> on your system and
-run <code>make docs</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_feature_requests">Feature requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you have an awesome idea or need something that Erlang.mk
-doesn’t provide yet, open a ticket. Provide as much detail as
-possible.</p></div>
-<div class="paragraph"><p>If you have code, great! Open a pull request as previously
-explained.</p></div>
-<div class="paragraph"><p>If not, you can still improve your feature request by writing
-the related documentation.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>You are welcome and encouraged to contribute.</p></div> +<div class="paragraph"><p>This is how.</p></div> +<div class="sect1"> +<h2 id="_priorities">Priorities</h2> +<div class="sectionbody"> +<div class="paragraph"><p>From the most important to the least important:</p></div> +<div class="ulist"><ul> +<li> +<p> +Bugs +</p> +</li> +<li> +<p> +Package issues/additions +</p> +</li> +<li> +<p> +Refactoring +</p> +</li> +<li> +<p> +Features +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_bugs">Bugs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have found a bug, you should open a ticket. Include +everything relevant including the command you used, output, +a link to the code that triggers the issue, why you think +this is a bug, etc.</p></div> +<div class="paragraph"><p>If you think you have found a bug but you are not sure, you +should open a ticket as previously explained.</p></div> +<div class="paragraph"><p>If you have found a bug and you need it to be solved RIGHT +NOW, open a ticket as previously explained.</p></div> +<div class="paragraph"><p>Once you have opened a ticket, be patient, try to answer +questions in a timely manner and confirm that the bug was +indeed fixed when it is.</p></div> +<div class="paragraph"><p>If you can’t be patient, either try to solve the bug and +contribute the fix back or become a paying customer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_code">Code</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The code is located in the <em>core/*.mk</em> and <em>plugins/*.mk</em> files. +The tests are located in the <em>test/Makefile</em> and <em>test/*.mk</em> files.</p></div> +<div class="paragraph"><p>If you have a fix or a hack for a bug, you should open a +pull request. Any fix should include a test case that fails +before the fix and is working after.</p></div> +<div class="paragraph"><p>If you have a test case that reproduces a bug, but no fix for +it, you should open a pull request.</p></div> +<div class="paragraph"><p>Changes need to be tested with at least the <code>make check</code> +command. A specific test case can be tested using <code>make check c=CASE</code> +with <code>CASE</code> the name of the target to run. Output can be +modulated using the <code>V</code> variable, which is an integer +from 0 to 4. A typical use would be <code>make check c=dialyzer V=3</code>. +The value 4 is particular and shows expanded commands right +before they are executed.</p></div> +<div class="paragraph"><p>To run tests in parallel, use the <code>-j</code> option. It is generally +a good idea to also use the <code>-k</code> option to run all tests even +if one fails. For example: <code>make check -j 32 -k</code>.</p></div> +<div class="paragraph"><p>Some changes should be tested against all packages. Continue +reading for more details on testing them.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_packages">Packages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can search existing packages using the <code>make search q=STRING</code> +command. This can be done both from an Erlang.mk project or +directly from the Erlang.mk repository.</p></div> +<div class="paragraph"><p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</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>$ git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com<span style="color: #990000">/</span><span style="color: #009900">$YOURUSERNAME</span>/erlang<span style="color: #990000">.</span>mk +$ cd erlang<span style="color: #990000">.</span>mk +$ <span style="color: #990000">.</span>/pkg_add<span style="color: #990000">.</span>sh cowboy git https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/cowboy <span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span> + http<span style="color: #990000">:</span>//ninenines<span style="color: #990000">.</span>eu <span style="color: #FF0000">"Small, fast and modular HTTP server."</span> +$ git push origin master</tt></pre></div></div> +<div class="paragraph"><p>Before sending a pull request, you should test your package. +You can use the following command: <code>make check p=PACKAGE</code>, +where <code>PACKAGE</code> is the name of the package, for example +<code>cowboy</code>.</p></div> +<div class="paragraph"><p>To test all packages, the <code>make packages</code> command can be used. +This can take a long time. Some packages will fail with certain +versions of Erlang, or if a prerequisite is missing from your system. +You can of course speed things up using the <code>-j</code> and <code>-k</code> flags.</p></div> +<div class="paragraph"><p>After all packages have been tested, you can run the command +<code>make summary</code> to know what changed since the previous run.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_documentation">Documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The documentation is always right.</p></div> +<div class="paragraph"><p>If you think you have found a mistake in the documentation, +this is a bug. You can either open a ticket or send a pull +request.</p></div> +<div class="paragraph"><p>To make sure that the documentation changes work, install +the listed <a href="../asciidoc">Requirements</a> on your system and +run <code>make docs</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_feature_requests">Feature requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have an awesome idea or need something that Erlang.mk +doesn’t provide yet, open a ticket. Provide as much detail as +possible.</p></div> +<div class="paragraph"><p>If you have code, great! Open a pull request as previously +explained.</p></div> +<div class="paragraph"><p>If not, you can still improve your feature request by writing +the related documentation.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/coverage/index.html b/docs/en/erlang.mk/1/guide/coverage/index.html index 39cfde17..d341f6f5 100644 --- a/docs/en/erlang.mk/1/guide/coverage/index.html +++ b/docs/en/erlang.mk/1/guide/coverage/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Code coverage</title> @@ -67,13 +67,16 @@ <h1 class="lined-header"><span>Code coverage</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Placeholder chapter.</p></div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/deps/index.html b/docs/en/erlang.mk/1/guide/deps/index.html index 330146d6..c5a1904a 100644 --- a/docs/en/erlang.mk/1/guide/deps/index.html +++ b/docs/en/erlang.mk/1/guide/deps/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Packages and dependencies</title> @@ -67,610 +67,717 @@ <h1 class="lined-header"><span>Packages and dependencies</span></h1> -<div class="paragraph"><p>Erlang.mk can fetch and compile the dependencies that your
-project requires. Erlang.mk improves upon the concepts
-introduced by Rebar, so they should be familiar to many
-seasoned Erlang developers.</p></div>
-<div class="paragraph"><p>Erlang.mk is not a package manager, nor is it trying to be,
-but it does include an index of Erlang packages to make
-discovering useful projects easier.</p></div>
-<div class="paragraph"><p>This chapter will explain how to use packages, add
-dependencies to your project or bundle them directly
-in a single repository.</p></div>
-<div class="sect1">
-<h2 id="_searching_packages">Searching packages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk gives you access to nearly 500 packages, with more
-being added regularly.</p></div>
-<div class="paragraph"><p>To find a package, search for 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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>pool</tt></pre></div></div>
-<div class="paragraph"><p>This will return all packages matching this word, like worker
-pool and acceptor pool projects.</p></div>
-<div class="paragraph"><p>You can also list everything and use regular command line
-tools to find what you need, for example:</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>$ make search <span style="color: #990000">|</span> less</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_adding_dependencies_to_your_project">Adding dependencies to your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Once you find the package you need, adding it as a dependency
-to your project is a one-liner:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>And that’s it! The next time you run <code>make</code>, Erlang.mk will
-fetch and compile Cowboy. Erlang.mk will also ensure Cowboy
-is available whenever you use the shell, run tests and any
-other operations.</p></div>
-<div class="paragraph"><p>Erlang.mk will fill in the application resource file with
-all applications found in <code>DEPS</code>. But not all dependencies
-are Erlang applications, and not all dependencies need to
-be a runtime dependency. That’s where the <code>BUILD_DEPS</code>
-variable comes in: it works just like <code>DEPS</code>, except the
-dependencies listed there will not be added as runtime
-dependencies.</p></div>
-<div class="paragraph"><p>For example, you could add a parse transform project like
-this to make it available only at build time:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Or you could depend on a C project directly, if you are
-building a NIF:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This dependency will be built before your application, so
-you could easily copy the resulting shared file into your
-<em>priv/</em> directory as part of the build process. More information
-about that in the <a href="../ports">NIFs and port drivers</a>
-chapter.</p></div>
-<div class="paragraph"><p>Another variable, <code>LOCAL_DEPS</code>, allows specifying runtime
-dependencies which are part of Erlang/OTP itself, but also
-dependencies that are included in the repository. Since they
-are already on your system, there is no need to fetch them.
-Do note that there is no way to choose the version, the
-application used will be the one already on your system.</p></div>
-<div class="paragraph"><p>You could depend on the Crypto application, for example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Erlang.mk comes with additional types of dependencies.
-It has <code>TEST_DEPS</code> for dependencies used only for testing:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p><code>DOC_DEPS</code> for dependencies used only when building documentation:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p><code>REL_DEPS</code> for dependencies required to build the release,
-or to include extra applications in the release:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>And <code>SHELL_DEPS</code> for dependencies to make available when running
-the <code>make shell</code> command:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>All these will be documented in more details in their respective
-chapters.</p></div>
-<div class="sect3">
-<h4 id="_modifying_the_dependency_source_or_version">Modifying the dependency source or version</h4>
-<div class="paragraph"><p>By default, Erlang.mk will look into its package index to
-find the project you are looking for, if you only provide
-its name. This is this case:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>If you need a different version, you need to define another
-variable. There are two ways to do this, each being useful
-for different reasons.</p></div>
-<div class="paragraph"><p>If you simply want to change the commit number, all you
-need to do is to define the <code>dep_$(DEP_NAME)_commit</code>
-variable. In the case of Cowboy, this would look like this:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Erlang.mk will use the package index to get all information
-about Cowboy, except the commit number which will be overriden.</p></div>
-<div class="paragraph"><p>If you need to set the fetch method or repository information
-too, for example because you want to use your own fork, or
-simply because the project is missing from the index, you
-can define the <code>dep_$(DEP_NAME)</code> variable with everything:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This will fetch Cowboy from your fork at the given commit.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_fetch_methods">Fetch methods</h4>
-<div class="paragraph"><p>Erlang.mk comes with a number of different fetch methods.
-You can fetch from Git, Mercurial, SVN, to name a few.
-There are fetch methods that will work everywhere, and
-fetch methods that will only work in a given environment.</p></div>
-<div class="paragraph"><p>The following table lists all existing methods:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Name </th>
-<th align="center" valign="top"> Format </th>
-<th align="center" valign="top"> Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">git</p></td>
-<td align="center" valign="top"><p class="table">git repo commit</p></td>
-<td align="center" valign="top"><p class="table">Clone the Git repository and checkout the given version</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">git-submodule</p></td>
-<td align="center" valign="top"><p class="table">git-submodule</p></td>
-<td align="center" valign="top"><p class="table">Initialize and update the Git submodule</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">hg</p></td>
-<td align="center" valign="top"><p class="table">hg repo commit</p></td>
-<td align="center" valign="top"><p class="table">Clone the Mercurial repository and update to the given version</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">svn</p></td>
-<td align="center" valign="top"><p class="table">svn repo</p></td>
-<td align="center" valign="top"><p class="table">Checkout the given SVN repository</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">cp</p></td>
-<td align="center" valign="top"><p class="table">cp path/to/repo</p></td>
-<td align="center" valign="top"><p class="table">Recursively copy a local directory</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">ln</p></td>
-<td align="center" valign="top"><p class="table">ln path/to/repo</p></td>
-<td align="center" valign="top"><p class="table">Symbolically link a local directory</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">hex</p></td>
-<td align="center" valign="top"><p class="table">hex version</p></td>
-<td align="center" valign="top"><p class="table">Download the given project version from hex.pm</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">fail</p></td>
-<td align="center" valign="top"><p class="table">N/A</p></td>
-<td align="center" valign="top"><p class="table">Always fail, reserved for internal use</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">legacy</p></td>
-<td align="center" valign="top"><p class="table">N/A</p></td>
-<td align="center" valign="top"><p class="table">Legacy Erlang.mk fetcher, reserved for internal use</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>The <code>git</code> and <code>hg</code> methods both have a repository and commit.
-You can use any valid commit, tag or branch in that repository
-for the commit value.</p></div>
-<div class="paragraph"><p>For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Or to fetch Ehsa tag 4.0.3 from Mercurial:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Git also comes with a concept of submodules. Erlang.mk can
-automatically initializes and updates submodules for dependencies,
-as long as they were added beforehand using <code>git submodule add</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>svn</code> method only has a repository value, but that’s
-simply because the SVN repository URL can also contain
-the path and commit.</p></div>
-<div class="paragraph"><p>This would fetch an example project from the trunk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>And this would fetch a separate example project from a
-specific commit:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can copy a directory from your machine using the <code>cp</code> method.
-It only takes the path to copy from:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Finally, you can use a package from the
-<a href="https://hex.pm/">Hex repository</a>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-<div class="sect3">
-<h4 id="_custom_fetch_methods">Custom fetch methods</h4>
-<div class="paragraph"><p>If none of the existing methods fit your use, you can simply
-define your own. Erlang.mk will consider all variables that
-are named as <code>dep_fetch_$(METHOD)</code> to be available fetch
-methods. You can do anything inside this variable, as long
-as you create a folder named <em>$(DEPS_DIR)/$(call dep_name,$1)</em>.
-Or in layman terms, if your dependency is Cowboy, this would
-become <em>deps/cowboy</em>.</p></div>
-<div class="paragraph"><p>To give an example, this is what the Git method does:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Note that, like dependency information, this custom fetch method
-must be written before including <em>erlang.mk</em>.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_how_deps_are_fetched_and_built">How deps are fetched and built</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The order in which dependencies are fetched and built is well
-defined. This means that Erlang.mk will get the same applications
-regardless of the command or options being used.</p></div>
-<div class="paragraph"><p>In tree traversal terms, where the list of dependencies is a
-tree, Erlang.mk fetches everything using the pre-order traversal
-method. The steps can be summarized like this, starting from
-the root application:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Fetch all dependencies for the application
-</p>
-</li>
-<li>
-<p>
-Build first dependency
-</p>
-</li>
-<li>
-<p>
-Build Nth dependency
-</p>
-</li>
-<li>
-<p>
-Build last dependency
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>Every time a dependency is built, these same steps are followed,
-recursively.</p></div>
-<div class="paragraph"><p>Do note that the first step, fetching all dependencies of
-an application, is not guaranteed to be ordered. The reason
-for this is that it is not possible to have the same dependency
-listed twice in a single application, and therefore there can
-be no conflicts. Remember, this step only fetches, at no point
-are different applications built in parallel.</p></div>
-<div class="paragraph"><p>What about conflicts between the dependencies of different
-applications? Simple. Since builds are ordered, this means
-that the first version of an application that is fetched
-will be the one that wins.</p></div>
-<div class="paragraph"><p>This means that if project A depends on projects B and C,
-in this order, and that both B and C depend on a different
-version of D, it will always be B’s version of D that wins,
-because we fetch the dependencies of B before fetching
-those from C.</p></div>
-<div class="paragraph"><p>Similarly, if project A depends on projects B, C and D,
-regardless of the order, and A, B and C depend on a
-different version of D, it will always be A’s version
-that wins, because we fetch all dependencies of A before
-fetching those from B or C.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_fetching_and_listing_dependencies_only">Fetching and listing dependencies only</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can fetch all dependencies recursively without building anything,
-with the <code>make fetch-deps</code> command. It follows the same rules described
-in the section above.</p></div>
-<div class="paragraph"><p>You can list all dependencies recursively, again without building
-anything, with the <code>make list-deps</code> command. It will obviously need
-to fetch all dependencies exactly like <code>make fetch-deps</code>. Once
-everything is fetched, it prints a sorted list of absolute paths to the
-dependencies.</p></div>
-<div class="paragraph"><p>By default, <code>fetch-deps</code> and <code>list-deps</code> work on the <code>BUILD_DEPS</code>
-and <code>DEPS</code> lists only. To also fetch/list <code>TEST_DEPS</code>, <code>DOC_DEPS</code>,
-<code>REL_DEPS</code> and/or <code>SHELL_DEPS</code>, you have two possibilities:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-You can use <code>make fetch-test-deps</code>, <code>make fetch-doc-deps</code>, <code>make
- fetch-rel-deps</code> and <code>make fetch-shell-deps</code> commands respectively.
- If you want to list them, you can use <code>make list-test-deps</code>, <code>make
- list-doc-deps</code>, <code>make list-rel-deps</code> and <code>make list-shell-deps</code>
- respectively.
-</p>
-</li>
-<li>
-<p>
-You can use <code>make fetch-deps</code> or <code>make list-deps</code> with the Makefile
- variable <code>DEP_TYPES</code> set to a list of dependency types you want.
- The types are <code>test</code>, <code>doc</code>, <code>rel</code> and <code>shell</code> respectively. For
- example, you can list test and doc dependencies with <code>make list-deps
- DEP_TYPES='test doc'</code>.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Note that only first level ‘TEST_DEPS<code>, `DOC_DEPS</code>, <code>REL_DEPS</code> and
-<code>SHELL_DEPS</code> are included, not dependencies’ one. In other word,
-<code>make list-test-deps</code> lists the <code>TEST_DEPS</code> of your project, but not
-<code>TEST_DEPS</code> of the projects yours depend on.</p></div>
-<div class="paragraph"><p>No matter which method you use, <code>BUILD_DEPS</code> and <code>DEPS</code> are always
-included.</p></div>
-<div class="paragraph"><p>Internally, the <code>make fetch-*</code> commands store the complete list of
-dependencies in files named <code>$(ERLANG_MK_RECURSIVE_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST)</code> and
-<code>$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST)</code>. Those files are simply printed
-by the <code>make list-*</code> commands.</p></div>
-<div class="paragraph"><p><code>make list-*</code> commands are made for human beings. If you need the list
-of dependencies in a Makefile or a script, you should use the content
-of those files directly instead. The reason is that <code>make fetch-*</code> and
-<code>make list-*</code> may have unwanted content in their output, such as actual
-fetching of dependencies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ignoring_unwanted_dependencies">Ignoring unwanted dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Sometimes, you may want to ignore dependencies entirely.
-Not even fetch them. You may want to do this because a
-project you depend on depends on an application you do
-not need (like a dependency for building documentation
-or testing). Or maybe the dependency is already installed
-on your system.</p></div>
-<div class="paragraph"><p>To ignore a dependency, simply add it to the <code>IGNORE_DEPS</code>
-variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This will only ignore dependencies that are needed for
-building. It is therefore safe to write:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The PropEr application will be fetched as intended when
-running <code>make tests</code> or <code>make check</code>. It will however
-not be fetched when running <code>make</code> or <code>make deps</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies_directory">Dependencies directory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Dependencies are fetched in <em>$(DEPS_DIR)</em>. By default this is
-the <em>deps</em> directory. You can change this default, but you
-should only do so if it was not defined previously. Erlang.mk
-uses this variable to tell dependencies where to fetch their
-own dependencies.</p></div>
-<div class="paragraph"><p>You will therefore need to use <code>?=</code> instead of <code>=</code>. Of course,
-if you know you will never use this project as a dependency,
-<code>=</code> will work. But to avoid it biting you later on, do this:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>$(CURDIR)</code> part is important, otherwise dependencies of
-dependencies will be fetched in the wrong directory.</p></div>
-<div class="paragraph"><p>Erlang.mk will also export the <code>REBAR_DEPS_DIR</code> variable for
-compatibility with Rebar build tools, as long as they are
-recent enough.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_many_applications_in_one_repository">Many applications in one repository</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In addition to the dependencies that are fetched, Erlang.mk
-also allows you to have dependencies local to your repository.
-This kind of layout is sometimes called multi-application
-repositories, or repositories with multiple applications.</p></div>
-<div class="paragraph"><p>They work exactly the same as remote dependencies, except:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-They are not fetched
-</p>
-</li>
-<li>
-<p>
-They are not autopatched
-</p>
-</li>
-<li>
-<p>
-They are not deleted on <code>make distclean</code>
-</p>
-</li>
-<li>
-<p>
-They are not automatically added to the application resource file
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>To properly fill the application resource file and compile apps in
-the right order, you will need to define the <code>LOCAL_DEPS</code> variable
-for each relevant application, the same as for OTP applications. Apps
-can depend on each other in this way, and their compilation order
-will follow the same rules as regular dependencies in <code>DEPS</code>.</p></div>
-<div class="paragraph"><p>The top-level <code>LOCAL_DEPS</code> variable, if defined, will determine which
-apps (along with their dependencies) to build, and also which apps
-should be added to the top-level application resource file, if there
-is one. This may be useful, for example, for specifying a different
-set of apps to build for different releases. If <code>LOCAL_DEPS</code> is not
-defined, then all apps in the <em>$(APPS_DIR)</em> will be built, but none
-will be automatically added to the top-level application resource
-file.</p></div>
-<div class="paragraph"><p>If there is a conflict between a local dependency and a
-remote dependency, then the local dependency always wins;
-an error will be triggered when trying to fetch the
-conflicting remote dependency.</p></div>
-<div class="paragraph"><p>To start using dependencies local to the repository, simply
-create a folder named <em>$(APPS_DIR)</em>. By default, this folder
-is the <em>apps/</em> directory.</p></div>
-<div class="paragraph"><p>You can use Erlang.mk to bootstrap local dependencies by
-using the command <code>make new-app</code> or <code>make new-lib</code>. This
-command will create the necessary directories and bootstrap
-the application.</p></div>
-<div class="paragraph"><p>For example, to create a full fledged OTP application as
-a local dependency:</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>$ make new-app <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-<div class="paragraph"><p>Or, the same as an OTP library:</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>$ make new-lib <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-<div class="paragraph"><p>Templates also work with local dependencies, from the root
-directory of the project. You do need however to tell
-Erlang.mk to create the files in the correct application:</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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_repositories_with_no_application_at_the_root_level">Repositories with no application at the root level</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It’s possible to use Erlang.mk with only applications in
-<em>$(APPS_DIR)</em>, and nothing at the root of the repository.
-Just create a folder, put the <em>erlang.mk</em> file in it,
-write a Makefile that includes it, and start creating
-your applications.</p></div>
-<div class="paragraph"><p>Similarly, it’s possible to have a repository with only
-dependencies found in <em>$(DEPS_DIR)</em>. You just need to
-create a Makefile and specify the dependencies you want.
-This allows you to create a repository for handling the
-building of releases, for example.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_autopatch">Autopatch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will automatically patch all the dependencies it
-fetches. It needs to do this to ensure that the dependencies
-become compatible with not only Erlang.mk, but also with
-the version of Erlang.mk that is currently used.</p></div>
-<div class="paragraph"><p>When fetching a dependency, the following operations are
-performed:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Fetch the dependency using the configured fetch method
-</p>
-</li>
-<li>
-<p>
-If it contains a <em>configure.ac</em> or <em>configure.in</em> file, run <code>autoreconf -Wall -vif -I m4</code>
-</p>
-</li>
-<li>
-<p>
-If it contains a <em>configure</em> script, run it
-</p>
-</li>
-<li>
-<p>
-Run autopatch on the project
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Autopatch first checks if there is any project-specific patch
-enabled. There are currently two: <code>RABBITMQ_CLIENT_PATCH</code> for
-the <code>amqp_client</code> dependency, and <code>RABBITMQ_SERVER_PATCH</code> for
-the <code>rabbit</code> dependency. These are needed only for RabbitMQ
-versions before 3.6.0 (assuming you are using upstream RabbitMQ,
-and not a fork).</p></div>
-<div class="paragraph"><p>Otherwise, autopatch performs different operations depending
-on the kind of project it finds the dependency to be.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Rebar projects are automatically converted to use Erlang.mk
-as their build tool. This essentially patches Rebar out, and
-fixes and converts the project to be compatible with Erlang.mk.
-</p>
-</li>
-<li>
-<p>
-Erlang.mk projects have their <em>Makefile</em> patched, if necessary,
-to include the top-level project’s Erlang.mk. This is to ensure
-that functionality works across all dependencies, even if the
-dependency’s Erlang.mk is outdated. The patched Makefile
-can be safely committed if necessary.
-</p>
-</li>
-<li>
-<p>
-Other Erlang projects get a small Erlang.mk Makefile
-generated automatically.
-</p>
-</li>
-<li>
-<p>
-Projects with no source directory and no Makefile get an
-empty Makefile generated, for compatibility purposes.
-</p>
-</li>
-<li>
-<p>
-Other projects with no Makefile are left untouched.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>You can disable the replacing of the <em>erlang.mk</em> file by
-defining the <code>NO_AUTOPATCH_ERLANG_MK</code> variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can also disable autopatch entirely for a few select
-projects using the <code>NO_AUTOPATCH</code> variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_skipping_deps">Skipping deps</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is possible to temporarily skip all dependency operations.
-This is done by defining the <code>SKIP_DEPS</code> variable. Use cases
-include being somewhere with no connection to download them,
-or perhaps a peculiar setup.</p></div>
-<div class="paragraph"><p>A typical usage would be:</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>$ make <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>When the variable is defined:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Dependencies will not be compiled or downloaded when required
-</p>
-</li>
-<li>
-<p>
-The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This variable only applies to remote dependencies.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can fetch and compile the dependencies that your +project requires. Erlang.mk improves upon the concepts +introduced by Rebar, so they should be familiar to many +seasoned Erlang developers.</p></div> +<div class="paragraph"><p>Erlang.mk is not a package manager, nor is it trying to be, +but it does include an index of Erlang packages to make +discovering useful projects easier.</p></div> +<div class="paragraph"><p>This chapter will explain how to use packages, add +dependencies to your project or bundle them directly +in a single repository.</p></div> +<div class="sect1"> +<h2 id="_searching_packages">Searching packages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk gives you access to nearly 500 packages, with more +being added regularly.</p></div> +<div class="paragraph"><p>To find a package, search for 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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>pool</tt></pre></div></div> +<div class="paragraph"><p>This will return all packages matching this word, like worker +pool and acceptor pool projects.</p></div> +<div class="paragraph"><p>You can also list everything and use regular command line +tools to find what you need, for example:</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>$ make search <span style="color: #990000">|</span> less</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_adding_dependencies_to_your_project">Adding dependencies to your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Once you find the package you need, adding it as a dependency +to your project is a one-liner:</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="color: #009900">DEPS =</span> cowboy</tt></pre></div></div> +<div class="paragraph"><p>And that’s it! The next time you run <code>make</code>, Erlang.mk will +fetch and compile Cowboy. Erlang.mk will also ensure Cowboy +is available whenever you use the shell, run tests and any +other operations.</p></div> +<div class="paragraph"><p>Erlang.mk will fill in the application resource file with +all applications found in <code>DEPS</code>. But not all dependencies +are Erlang applications, and not all dependencies need to +be a runtime dependency. That’s where the <code>BUILD_DEPS</code> +variable comes in: it works just like <code>DEPS</code>, except the +dependencies listed there will not be added as runtime +dependencies.</p></div> +<div class="paragraph"><p>For example, you could add a parse transform project like +this to make it available only at build time:</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="color: #009900">BUILD_DEPS =</span> erlando</tt></pre></div></div> +<div class="paragraph"><p>Or you could depend on a C project directly, if you are +building a NIF:</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="color: #009900">BUILD_DEPS =</span> leveldb +<span style="color: #009900">dep_leveldb =</span> git https<span style="color: #990000">:</span>//github.com/basho/leveldb 2.1.3</tt></pre></div></div> +<div class="paragraph"><p>This dependency will be built before your application, so +you could easily copy the resulting shared file into your +<em>priv/</em> directory as part of the build process. More information +about that in the <a href="../ports">NIFs and port drivers</a> +chapter.</p></div> +<div class="paragraph"><p>Another variable, <code>LOCAL_DEPS</code>, allows specifying runtime +dependencies which are part of Erlang/OTP itself, but also +dependencies that are included in the repository. Since they +are already on your system, there is no need to fetch them. +Do note that there is no way to choose the version, the +application used will be the one already on your system.</p></div> +<div class="paragraph"><p>You could depend on the Crypto application, for example:</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="color: #009900">LOCAL_DEPS =</span> crypto</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk comes with additional types of dependencies. +It has <code>TEST_DEPS</code> for dependencies used only for testing:</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="color: #009900">TEST_DEPS =</span> ct_helper +<span style="color: #009900">dep_ct_helper =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/ct_helper master</tt></pre></div></div> +<div class="paragraph"><p><code>DOC_DEPS</code> for dependencies used only when building documentation:</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="color: #009900">DOC_DEPS =</span> edown</tt></pre></div></div> +<div class="paragraph"><p><code>REL_DEPS</code> for dependencies required to build the release, +or to include extra applications in the release:</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="color: #009900">REL_DEPS =</span> recon</tt></pre></div></div> +<div class="paragraph"><p>And <code>SHELL_DEPS</code> for dependencies to make available when running +the <code>make shell</code> command:</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="color: #009900">SHELL_DEPS =</span> tddreloader</tt></pre></div></div> +<div class="paragraph"><p>All these will be documented in more details in their respective +chapters.</p></div> +<div class="sect3"> +<h4 id="_modifying_the_dependency_source_or_version">Modifying the dependency source or version</h4> +<div class="paragraph"><p>By default, Erlang.mk will look into its package index to +find the project you are looking for, if you only provide +its name. This is this case:</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="color: #009900">DEPS =</span> cowboy</tt></pre></div></div> +<div class="paragraph"><p>If you need a different version, you need to define another +variable. There are two ways to do this, each being useful +for different reasons.</p></div> +<div class="paragraph"><p>If you simply want to change the commit number, all you +need to do is to define the <code>dep_$(DEP_NAME)_commit</code> +variable. In the case of Cowboy, this would look like this:</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="color: #009900">DEPS =</span> cowboy +<span style="color: #009900">dep_cowboy_commit =</span> 2.0.0-pre.2</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will use the package index to get all information +about Cowboy, except the commit number which will be overriden.</p></div> +<div class="paragraph"><p>If you need to set the fetch method or repository information +too, for example because you want to use your own fork, or +simply because the project is missing from the index, you +can define the <code>dep_$(DEP_NAME)</code> variable with everything:</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="color: #009900">DEPS =</span> cowboy +<span style="color: #009900">dep_cowboy =</span> git https<span style="color: #990000">:</span>//github.com/essen/cowboy 2.0.0-pre.2</tt></pre></div></div> +<div class="paragraph"><p>This will fetch Cowboy from your fork at the given commit.</p></div> +</div> +<div class="sect3"> +<h4 id="_fetch_methods">Fetch methods</h4> +<div class="paragraph"><p>Erlang.mk comes with a number of different fetch methods. +You can fetch from Git, Mercurial, SVN, to name a few. +There are fetch methods that will work everywhere, and +fetch methods that will only work in a given environment.</p></div> +<div class="paragraph"><p>The following table lists all existing methods:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="33%" /> +<col width="33%" /> +<col width="33%" /> +<thead> +<tr> +<th align="left" valign="top"> Name </th> +<th align="center" valign="top"> Format </th> +<th align="center" valign="top"> Description</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">git</p></td> +<td align="center" valign="top"><p class="table">git repo commit</p></td> +<td align="center" valign="top"><p class="table">Clone the Git repository and checkout the given version</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">git-submodule</p></td> +<td align="center" valign="top"><p class="table">git-submodule</p></td> +<td align="center" valign="top"><p class="table">Initialize and update the Git submodule</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">hg</p></td> +<td align="center" valign="top"><p class="table">hg repo commit</p></td> +<td align="center" valign="top"><p class="table">Clone the Mercurial repository and update to the given version</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">svn</p></td> +<td align="center" valign="top"><p class="table">svn repo</p></td> +<td align="center" valign="top"><p class="table">Checkout the given SVN repository</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">cp</p></td> +<td align="center" valign="top"><p class="table">cp path/to/repo</p></td> +<td align="center" valign="top"><p class="table">Recursively copy a local directory</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">ln</p></td> +<td align="center" valign="top"><p class="table">ln path/to/repo</p></td> +<td align="center" valign="top"><p class="table">Symbolically link a local directory</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">hex</p></td> +<td align="center" valign="top"><p class="table">hex version</p></td> +<td align="center" valign="top"><p class="table">Download the given project version from hex.pm</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">fail</p></td> +<td align="center" valign="top"><p class="table">N/A</p></td> +<td align="center" valign="top"><p class="table">Always fail, reserved for internal use</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">legacy</p></td> +<td align="center" valign="top"><p class="table">N/A</p></td> +<td align="center" valign="top"><p class="table">Legacy Erlang.mk fetcher, reserved for internal use</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>The <code>git</code> and <code>hg</code> methods both have a repository and commit. +You can use any valid commit, tag or branch in that repository +for the commit value.</p></div> +<div class="paragraph"><p>For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:</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="color: #009900">dep_cowboy =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/cowboy 2.0.0-pre.2</tt></pre></div></div> +<div class="paragraph"><p>Or to fetch Ehsa tag 4.0.3 from Mercurial:</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="color: #009900">dep_ehsa =</span> hg https<span style="color: #990000">:</span>//bitbucket.org/a12n/ehsa 4.0.3</tt></pre></div></div> +<div class="paragraph"><p>Git also comes with a concept of submodules. Erlang.mk can +automatically initializes and updates submodules for dependencies, +as long as they were added beforehand using <code>git submodule add</code>:</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="color: #009900">dep_cowboy =</span> git-submodule</tt></pre></div></div> +<div class="paragraph"><p>The <code>svn</code> method only has a repository value, but that’s +simply because the SVN repository URL can also contain +the path and commit.</p></div> +<div class="paragraph"><p>This would fetch an example project from the trunk:</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="color: #009900">dep_ex1 =</span> svn https<span style="color: #990000">:</span>//example.com/svn/trunk/project/ex<span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>And this would fetch a separate example project from a +specific commit:</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="color: #009900">dep_ex2 =</span> svn svn<span style="color: #990000">:</span>//example.com/svn/branches/erlang-proj/ex<span style="color: #993399">2</span>@<span style="color: #993399">264</span></tt></pre></div></div> +<div class="paragraph"><p>You can copy a directory from your machine using the <code>cp</code> method. +It only takes the path to copy from:</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="color: #009900">dep_cowboy =</span> cp <span style="color: #009900">$(HOME)</span>/ninenines/cowboy</tt></pre></div></div> +<div class="paragraph"><p>Finally, you can use a package from the +<a href="https://hex.pm/">Hex repository</a>:</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="color: #009900">dep_cowboy =</span> hex 1.0.3</tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_custom_fetch_methods">Custom fetch methods</h4> +<div class="paragraph"><p>If none of the existing methods fit your use, you can simply +define your own. Erlang.mk will consider all variables that +are named as <code>dep_fetch_$(METHOD)</code> to be available fetch +methods. You can do anything inside this variable, as long +as you create a folder named <em>$(DEPS_DIR)/$(call dep_name,$1)</em>. +Or in layman terms, if your dependency is Cowboy, this would +become <em>deps/cowboy</em>.</p></div> +<div class="paragraph"><p>To give an example, this is what the Git method does:</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>define dep_fetch_git + git clone -q -n -- <span style="color: #009900">$(</span>call dep_repo<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">)</span> <span style="color: #009900">$(DEPS_DIR)</span><span style="color: #990000">/</span><span style="color: #009900">$(</span>call dep_name<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">);</span> <span style="color: #990000">\</span> + cd <span style="color: #009900">$(DEPS_DIR)</span><span style="color: #990000">/</span><span style="color: #009900">$(</span>call dep_name<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">)</span> <span style="color: #990000">&&</span> git checkout -q <span style="color: #009900">$(</span>call dep_commit<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">);</span> +endef</tt></pre></div></div> +<div class="paragraph"><p>Note that, like dependency information, this custom fetch method +must be written before including <em>erlang.mk</em>.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_how_deps_are_fetched_and_built">How deps are fetched and built</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The order in which dependencies are fetched and built is well +defined. This means that Erlang.mk will get the same applications +regardless of the command or options being used.</p></div> +<div class="paragraph"><p>In tree traversal terms, where the list of dependencies is a +tree, Erlang.mk fetches everything using the pre-order traversal +method. The steps can be summarized like this, starting from +the root application:</p></div> +<div class="olist arabic"><ol class="arabic"> +<li> +<p> +Fetch all dependencies for the application +</p> +</li> +<li> +<p> +Build first dependency +</p> +</li> +<li> +<p> +Build Nth dependency +</p> +</li> +<li> +<p> +Build last dependency +</p> +</li> +</ol></div> +<div class="paragraph"><p>Every time a dependency is built, these same steps are followed, +recursively.</p></div> +<div class="paragraph"><p>Do note that the first step, fetching all dependencies of +an application, is not guaranteed to be ordered. The reason +for this is that it is not possible to have the same dependency +listed twice in a single application, and therefore there can +be no conflicts. Remember, this step only fetches, at no point +are different applications built in parallel.</p></div> +<div class="paragraph"><p>What about conflicts between the dependencies of different +applications? Simple. Since builds are ordered, this means +that the first version of an application that is fetched +will be the one that wins.</p></div> +<div class="paragraph"><p>This means that if project A depends on projects B and C, +in this order, and that both B and C depend on a different +version of D, it will always be B’s version of D that wins, +because we fetch the dependencies of B before fetching +those from C.</p></div> +<div class="paragraph"><p>Similarly, if project A depends on projects B, C and D, +regardless of the order, and A, B and C depend on a +different version of D, it will always be A’s version +that wins, because we fetch all dependencies of A before +fetching those from B or C.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_fetching_and_listing_dependencies_only">Fetching and listing dependencies only</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can fetch all dependencies recursively without building anything, +with the <code>make fetch-deps</code> command. It follows the same rules described +in the section above.</p></div> +<div class="paragraph"><p>You can list all dependencies recursively, again without building +anything, with the <code>make list-deps</code> command. It will obviously need +to fetch all dependencies exactly like <code>make fetch-deps</code>. Once +everything is fetched, it prints a sorted list of absolute paths to the +dependencies.</p></div> +<div class="paragraph"><p>By default, <code>fetch-deps</code> and <code>list-deps</code> work on the <code>BUILD_DEPS</code> +and <code>DEPS</code> lists only. To also fetch/list <code>TEST_DEPS</code>, <code>DOC_DEPS</code>, +<code>REL_DEPS</code> and/or <code>SHELL_DEPS</code>, you have two possibilities:</p></div> +<div class="ulist"><ul> +<li> +<p> +You can use <code>make fetch-test-deps</code>, <code>make fetch-doc-deps</code>, <code>make + fetch-rel-deps</code> and <code>make fetch-shell-deps</code> commands respectively. + If you want to list them, you can use <code>make list-test-deps</code>, <code>make + list-doc-deps</code>, <code>make list-rel-deps</code> and <code>make list-shell-deps</code> + respectively. +</p> +</li> +<li> +<p> +You can use <code>make fetch-deps</code> or <code>make list-deps</code> with the Makefile + variable <code>DEP_TYPES</code> set to a list of dependency types you want. + The types are <code>test</code>, <code>doc</code>, <code>rel</code> and <code>shell</code> respectively. For + example, you can list test and doc dependencies with <code>make list-deps + DEP_TYPES='test doc'</code>. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Note that only first level ‘TEST_DEPS<code>, `DOC_DEPS</code>, <code>REL_DEPS</code> and +<code>SHELL_DEPS</code> are included, not dependencies’ one. In other word, +<code>make list-test-deps</code> lists the <code>TEST_DEPS</code> of your project, but not +<code>TEST_DEPS</code> of the projects yours depend on.</p></div> +<div class="paragraph"><p>No matter which method you use, <code>BUILD_DEPS</code> and <code>DEPS</code> are always +included.</p></div> +<div class="paragraph"><p>Internally, the <code>make fetch-*</code> commands store the complete list of +dependencies in files named <code>$(ERLANG_MK_RECURSIVE_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST)</code> and +<code>$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST)</code>. Those files are simply printed +by the <code>make list-*</code> commands.</p></div> +<div class="paragraph"><p><code>make list-*</code> commands are made for human beings. If you need the list +of dependencies in a Makefile or a script, you should use the content +of those files directly instead. The reason is that <code>make fetch-*</code> and +<code>make list-*</code> may have unwanted content in their output, such as actual +fetching of dependencies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ignoring_unwanted_dependencies">Ignoring unwanted dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Sometimes, you may want to ignore dependencies entirely. +Not even fetch them. You may want to do this because a +project you depend on depends on an application you do +not need (like a dependency for building documentation +or testing). Or maybe the dependency is already installed +on your system.</p></div> +<div class="paragraph"><p>To ignore a dependency, simply add it to the <code>IGNORE_DEPS</code> +variable:</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>IGNORE_DEPS <span style="color: #990000">+=</span> edown proper</tt></pre></div></div> +<div class="paragraph"><p>This will only ignore dependencies that are needed for +building. It is therefore safe to write:</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>IGNORE_DEPS <span style="color: #990000">+=</span> edown proper +<span style="color: #009900">TEST_DEPS =</span> proper</tt></pre></div></div> +<div class="paragraph"><p>The PropEr application will be fetched as intended when +running <code>make tests</code> or <code>make check</code>. It will however +not be fetched when running <code>make</code> or <code>make deps</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies_directory">Dependencies directory</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Dependencies are fetched in <em>$(DEPS_DIR)</em>. By default this is +the <em>deps</em> directory. You can change this default, but you +should only do so if it was not defined previously. Erlang.mk +uses this variable to tell dependencies where to fetch their +own dependencies.</p></div> +<div class="paragraph"><p>You will therefore need to use <code>?=</code> instead of <code>=</code>. Of course, +if you know you will never use this project as a dependency, +<code>=</code> will work. But to avoid it biting you later on, do this:</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>DEPS_DIR <span style="color: #990000">?=</span> <span style="color: #009900">$(CURDIR)</span>/libs</tt></pre></div></div> +<div class="paragraph"><p>The <code>$(CURDIR)</code> part is important, otherwise dependencies of +dependencies will be fetched in the wrong directory.</p></div> +<div class="paragraph"><p>Erlang.mk will also export the <code>REBAR_DEPS_DIR</code> variable for +compatibility with Rebar build tools, as long as they are +recent enough.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_many_applications_in_one_repository">Many applications in one repository</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In addition to the dependencies that are fetched, Erlang.mk +also allows you to have dependencies local to your repository. +This kind of layout is sometimes called multi-application +repositories, or repositories with multiple applications.</p></div> +<div class="paragraph"><p>They work exactly the same as remote dependencies, except:</p></div> +<div class="ulist"><ul> +<li> +<p> +They are not fetched +</p> +</li> +<li> +<p> +They are not autopatched +</p> +</li> +<li> +<p> +They are not deleted on <code>make distclean</code> +</p> +</li> +<li> +<p> +They are not automatically added to the application resource file +</p> +</li> +</ul></div> +<div class="paragraph"><p>To properly fill the application resource file and compile apps in +the right order, you will need to define the <code>LOCAL_DEPS</code> variable +for each relevant application, the same as for OTP applications. Apps +can depend on each other in this way, and their compilation order +will follow the same rules as regular dependencies in <code>DEPS</code>.</p></div> +<div class="paragraph"><p>The top-level <code>LOCAL_DEPS</code> variable, if defined, will determine which +apps (along with their dependencies) to build, and also which apps +should be added to the top-level application resource file, if there +is one. This may be useful, for example, for specifying a different +set of apps to build for different releases. If <code>LOCAL_DEPS</code> is not +defined, then all apps in the <em>$(APPS_DIR)</em> will be built, but none +will be automatically added to the top-level application resource +file.</p></div> +<div class="paragraph"><p>If there is a conflict between a local dependency and a +remote dependency, then the local dependency always wins; +an error will be triggered when trying to fetch the +conflicting remote dependency.</p></div> +<div class="paragraph"><p>To start using dependencies local to the repository, simply +create a folder named <em>$(APPS_DIR)</em>. By default, this folder +is the <em>apps/</em> directory.</p></div> +<div class="paragraph"><p>You can use Erlang.mk to bootstrap local dependencies by +using the command <code>make new-app</code> or <code>make new-lib</code>. This +command will create the necessary directories and bootstrap +the application.</p></div> +<div class="paragraph"><p>For example, to create a full fledged OTP application as +a local dependency:</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>$ make new-app <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +<div class="paragraph"><p>Or, the same as an OTP library:</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>$ make new-lib <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +<div class="paragraph"><p>Templates also work with local dependencies, from the root +directory of the project. You do need however to tell +Erlang.mk to create the files in the correct application:</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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_repositories_with_no_application_at_the_root_level">Repositories with no application at the root level</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It’s possible to use Erlang.mk with only applications in +<em>$(APPS_DIR)</em>, and nothing at the root of the repository. +Just create a folder, put the <em>erlang.mk</em> file in it, +write a Makefile that includes it, and start creating +your applications.</p></div> +<div class="paragraph"><p>Similarly, it’s possible to have a repository with only +dependencies found in <em>$(DEPS_DIR)</em>. You just need to +create a Makefile and specify the dependencies you want. +This allows you to create a repository for handling the +building of releases, for example.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_autopatch">Autopatch</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will automatically patch all the dependencies it +fetches. It needs to do this to ensure that the dependencies +become compatible with not only Erlang.mk, but also with +the version of Erlang.mk that is currently used.</p></div> +<div class="paragraph"><p>When fetching a dependency, the following operations are +performed:</p></div> +<div class="ulist"><ul> +<li> +<p> +Fetch the dependency using the configured fetch method +</p> +</li> +<li> +<p> +If it contains a <em>configure.ac</em> or <em>configure.in</em> file, run <code>autoreconf -Wall -vif -I m4</code> +</p> +</li> +<li> +<p> +If it contains a <em>configure</em> script, run it +</p> +</li> +<li> +<p> +Run autopatch on the project +</p> +</li> +</ul></div> +<div class="paragraph"><p>Autopatch first checks if there is any project-specific patch +enabled. There are currently two: <code>RABBITMQ_CLIENT_PATCH</code> for +the <code>amqp_client</code> dependency, and <code>RABBITMQ_SERVER_PATCH</code> for +the <code>rabbit</code> dependency. These are needed only for RabbitMQ +versions before 3.6.0 (assuming you are using upstream RabbitMQ, +and not a fork).</p></div> +<div class="paragraph"><p>Otherwise, autopatch performs different operations depending +on the kind of project it finds the dependency to be.</p></div> +<div class="ulist"><ul> +<li> +<p> +Rebar projects are automatically converted to use Erlang.mk +as their build tool. This essentially patches Rebar out, and +fixes and converts the project to be compatible with Erlang.mk. +</p> +</li> +<li> +<p> +Erlang.mk projects have their <em>Makefile</em> patched, if necessary, +to include the top-level project’s Erlang.mk. This is to ensure +that functionality works across all dependencies, even if the +dependency’s Erlang.mk is outdated. The patched Makefile +can be safely committed if necessary. +</p> +</li> +<li> +<p> +Other Erlang projects get a small Erlang.mk Makefile +generated automatically. +</p> +</li> +<li> +<p> +Projects with no source directory and no Makefile get an +empty Makefile generated, for compatibility purposes. +</p> +</li> +<li> +<p> +Other projects with no Makefile are left untouched. +</p> +</li> +</ul></div> +<div class="paragraph"><p>You can disable the replacing of the <em>erlang.mk</em> file by +defining the <code>NO_AUTOPATCH_ERLANG_MK</code> variable:</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="color: #009900">NO_AUTOPATCH_ERLANG_MK =</span> <span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>You can also disable autopatch entirely for a few select +projects using the <code>NO_AUTOPATCH</code> variable:</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="color: #009900">NO_AUTOPATCH =</span> cowboy ranch cowlib</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_skipping_deps">Skipping deps</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is possible to temporarily skip all dependency operations. +This is done by defining the <code>SKIP_DEPS</code> variable. Use cases +include being somewhere with no connection to download them, +or perhaps a peculiar setup.</p></div> +<div class="paragraph"><p>A typical usage would be:</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>$ make <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>When the variable is defined:</p></div> +<div class="ulist"><ul> +<li> +<p> +Dependencies will not be compiled or downloaded when required +</p> +</li> +<li> +<p> +The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>This variable only applies to remote dependencies.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/dialyzer/index.html b/docs/en/erlang.mk/1/guide/dialyzer/index.html index d6c7a467..5d8779f8 100644 --- a/docs/en/erlang.mk/1/guide/dialyzer/index.html +++ b/docs/en/erlang.mk/1/guide/dialyzer/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Dialyzer</title> @@ -67,83 +67,86 @@ <h1 class="lined-header"><span>Dialyzer</span></h1> -<div class="paragraph"><p>Dialyzer is a tool that will detect discrepancies in your
-program. It does so using a technique known as success
-typing analysis which has the advantage of providing no
-false positives. Dialyzer is able to detect type errors,
-dead code and more.</p></div>
-<div class="paragraph"><p>Erlang.mk provides a wrapper around Dialyzer.</p></div>
-<div class="sect1">
-<h2 id="_how_it_works">How it works</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Dialyzer requires a PLT file to work. The PLT file contains
-the analysis information from all applications which are not
-expected to change, or rarely do. These would be all the
-dependencies of the application or applications you are
-currently working on, including standard applications in
-Erlang/OTP itself.</p></div>
-<div class="paragraph"><p>Dialyzer can generate this PLT file. Erlang.mk includes rules
-to automatically generate the PLT file when it is missing.</p></div>
-<div class="paragraph"><p>Once the PLT file is generated, Dialyzer can perform the
-analysis in record time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In a typical usage scenario, no variable needs to be set.
-The defaults should be enough. Do note however that the
-dependencies need to be set properly using the <code>DEPS</code> and
-<code>LOCAL_DEPS</code> variables.</p></div>
-<div class="paragraph"><p>The <code>DIALYZER_PLT</code> file indicates where the PLT file will
-be written to (and read from). By default this is
-<em>$(PROJECT).plt</em> in the project’s directory. Note that
-the <code>DIALYZER_PLT</code> variable is exported and is understood
-by Dialyzer directly.</p></div>
-<div class="paragraph"><p>The <code>PLT_APPS</code> variable can be used to add additional
-applications to the PLT. You can either list application
-names or paths to these applications.</p></div>
-<div class="paragraph"><p>Erlang.mk defines two variables for specifying options
-for the analysis: <code>DIALYZER_DIRS</code> and <code>DIALYZER_OPTS</code>.
-The former one defines which directories should be part
-of the analysis. The latter defines what extra warnings
-Dialyzer should report.</p></div>
-<div class="paragraph"><p>Note that Erlang.mk enables the race condition warnings
-by default. As it can take considerably large resources
-to run, you may want to disable it on larger projects.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To perform an analysis, run the following command:</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>$ make dialyze</tt></pre></div></div>
-<div class="paragraph"><p>This will create the PLT file if it doesn’t exist.</p></div>
-<div class="paragraph"><p>The analysis will also be performed when you run the
-following command, alongside tests:</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>$ make check</tt></pre></div></div>
-<div class="paragraph"><p>You can use the <code>plt</code> target to create the PLT file if
-it doesn’t exist. This is normally not necessary as
-Dialyzer creates it automatically.</p></div>
-<div class="paragraph"><p>The PLT file will be removed when you run <code>make distclean</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Dialyzer is a tool that will detect discrepancies in your +program. It does so using a technique known as success +typing analysis which has the advantage of providing no +false positives. Dialyzer is able to detect type errors, +dead code and more.</p></div> +<div class="paragraph"><p>Erlang.mk provides a wrapper around Dialyzer.</p></div> +<div class="sect1"> +<h2 id="_how_it_works">How it works</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Dialyzer requires a PLT file to work. The PLT file contains +the analysis information from all applications which are not +expected to change, or rarely do. These would be all the +dependencies of the application or applications you are +currently working on, including standard applications in +Erlang/OTP itself.</p></div> +<div class="paragraph"><p>Dialyzer can generate this PLT file. Erlang.mk includes rules +to automatically generate the PLT file when it is missing.</p></div> +<div class="paragraph"><p>Once the PLT file is generated, Dialyzer can perform the +analysis in record time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In a typical usage scenario, no variable needs to be set. +The defaults should be enough. Do note however that the +dependencies need to be set properly using the <code>DEPS</code> and +<code>LOCAL_DEPS</code> variables.</p></div> +<div class="paragraph"><p>The <code>DIALYZER_PLT</code> file indicates where the PLT file will +be written to (and read from). By default this is +<em>$(PROJECT).plt</em> in the project’s directory. Note that +the <code>DIALYZER_PLT</code> variable is exported and is understood +by Dialyzer directly.</p></div> +<div class="paragraph"><p>The <code>PLT_APPS</code> variable can be used to add additional +applications to the PLT. You can either list application +names or paths to these applications.</p></div> +<div class="paragraph"><p>Erlang.mk defines two variables for specifying options +for the analysis: <code>DIALYZER_DIRS</code> and <code>DIALYZER_OPTS</code>. +The former one defines which directories should be part +of the analysis. The latter defines what extra warnings +Dialyzer should report.</p></div> +<div class="paragraph"><p>Note that Erlang.mk enables the race condition warnings +by default. As it can take considerably large resources +to run, you may want to disable it on larger projects.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To perform an analysis, run the following command:</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>$ make dialyze</tt></pre></div></div> +<div class="paragraph"><p>This will create the PLT file if it doesn’t exist.</p></div> +<div class="paragraph"><p>The analysis will also be performed when you run the +following command, alongside tests:</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>$ make check</tt></pre></div></div> +<div class="paragraph"><p>You can use the <code>plt</code> target to create the PLT file if +it doesn’t exist. This is normally not necessary as +Dialyzer creates it automatically.</p></div> +<div class="paragraph"><p>The PLT file will be removed when you run <code>make distclean</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/edoc/index.html b/docs/en/erlang.mk/1/guide/edoc/index.html index bc6befd3..6fcaeeed 100644 --- a/docs/en/erlang.mk/1/guide/edoc/index.html +++ b/docs/en/erlang.mk/1/guide/edoc/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: EDoc comments</title> @@ -67,60 +67,72 @@ <h1 class="lined-header"><span>EDoc comments</span></h1> -<div class="paragraph"><p>Erlang.mk provides a thin wrapper on top of EDoc, an application
-that generates documentation based on comments found in modules.</p></div>
-<div class="sect1">
-<h2 id="_writing_edoc_comments">Writing EDoc comments</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/edoc/chapter.html">EDoc user guide</a>
-explains everything you need to know about EDoc comments.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>EDOC_OPTS</code> variable allows you to specify additional
-EDoc options. Options are documented in the
-<a href="http://www.erlang.org/doc/man/edoc.html#run-2">EDoc manual</a>.</p></div>
-<div class="paragraph"><p>A common use for this variable is to enable Markdown in doc
-comments, using the <code>edown</code> application:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build all documentation, you would typically use:</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>$ make docs</tt></pre></div></div>
-<div class="paragraph"><p>Do note, however, that EDoc comments will only be generated
-automatically if the <em>doc/overview.edoc</em> file exists. If you
-do not want that file and still want to generate doc comments,
-two solutions are available.</p></div>
-<div class="paragraph"><p>You can generate EDoc documentation directly:</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>$ make edoc</tt></pre></div></div>
-<div class="paragraph"><p>You can enable automatic generation on <code>make docs</code> by adding
-the following to your Makefile:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides a thin wrapper on top of EDoc, an application +that generates documentation based on comments found in modules.</p></div> +<div class="sect1"> +<h2 id="_writing_edoc_comments">Writing EDoc comments</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/edoc/chapter.html">EDoc user guide</a> +explains everything you need to know about EDoc comments.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>EDOC_OPTS</code> variable allows you to specify additional +EDoc options. Options are documented in the +<a href="http://www.erlang.org/doc/man/edoc.html#run-2">EDoc manual</a>.</p></div> +<div class="paragraph"><p>A common use for this variable is to enable Markdown in doc +comments, using the <code>edown</code> application:</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="color: #009900">DOC_DEPS =</span> edown +<span style="color: #009900">EDOC_OPTS =</span> {doclet<span style="color: #990000">,</span> edown_doclet}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build all documentation, you would typically use:</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>$ make docs</tt></pre></div></div> +<div class="paragraph"><p>Do note, however, that EDoc comments will only be generated +automatically if the <em>doc/overview.edoc</em> file exists. If you +do not want that file and still want to generate doc comments, +two solutions are available.</p></div> +<div class="paragraph"><p>You can generate EDoc documentation directly:</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>$ make edoc</tt></pre></div></div> +<div class="paragraph"><p>You can enable automatic generation on <code>make docs</code> by adding +the following to your Makefile:</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="color: #990000">docs::</span> edoc</tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/escripts/index.html b/docs/en/erlang.mk/1/guide/escripts/index.html index 2bdc36bf..89cffc80 100644 --- a/docs/en/erlang.mk/1/guide/escripts/index.html +++ b/docs/en/erlang.mk/1/guide/escripts/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Escripts</title> @@ -67,97 +67,105 @@ <h1 class="lined-header"><span>Escripts</span></h1> -<div class="paragraph"><p>Escripts are an alternative to release. They are meant to be
-used for small command line executables written in Erlang.</p></div>
-<div class="paragraph"><p>They are not self-contained, unlike <a href="../relx">releases</a>.
-Erlang must be installed for them to run. This however means
-that they are fairly small compared to releases.</p></div>
-<div class="paragraph"><p>For self-contained executables, check <a href="../sfx">self-extracting releases</a>.</p></div>
-<div class="sect1">
-<h2 id="_requirements">Requirements</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk uses <code>p7zip</code> by default to generate the escript
-archive. Make sure it is installed. On most systems the
-package is named <code>p7zip</code>; on Ubuntu you need <code>p7zip-full</code>.</p></div>
-<div class="paragraph"><p>If <code>p7zip</code> is unavailable, <code>zip</code> may be used by setting
-the <code>ESCRIPT_ZIP</code> variable. For example:</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>$ make escript <span style="color: #009900">ESCRIPT_ZIP</span><span style="color: #990000">=</span>zip</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_an_escript">Generating an escript</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Run the following command to generate an escript:</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>$ make escript</tt></pre></div></div>
-<div class="paragraph"><p>This will by default create an escript with the same name as
-the project, in the project’s directory. If the project is
-called <code>relx</code> then the escript will be in <code>./relx</code>.</p></div>
-<div class="paragraph"><p>You can run the escript as you would any executable:</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="color: #990000">.</span>/relx</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can change the name of the escript by setting <code>ESCRIPT_NAME</code>.
-The name determines both the default output file name and the
-entry module containing the function <code>main/1</code>.</p></div>
-<div class="paragraph"><p><code>ESCRIPT_FILE</code> can be set if you need a different file name
-or location.</p></div>
-<div class="paragraph"><p>The escript header can be entirely customized. The first line
-is the shebang, set by <code>ESCRIPT_SHEBANG</code>. The second line is
-a comment, set by <code>ESCRIPT_COMMENT</code>. The third line is the
-arguments the VM will use when running the escript, set by
-<code>ESCRIPT_EMU_ARGS</code>.</p></div>
-<div class="paragraph"><p>Finally, <code>ESCRIPT_ZIP</code> can be set to customize the command used
-to create the zip file. Read on for more information.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_extra_files">Extra files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Generating an escript is a two-part process. First, a zip file
-is created with the contents of the escript. Then a header is
-added to this file to create the escript.</p></div>
-<div class="paragraph"><p>It is possible to add commands that will be executed between
-the two steps. You can for example add extra files to the zip
-archive:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>ESCRIPT_ZIP</code> variable contains the command to run to add
-files to the zip archive <code>ESCRIPT_ZIP_FILE</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_optimizing_for_size">Optimizing for size</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will by default compile BEAM files with debug
-information. You may want to disable this behavior to obtain
-smaller escript files. Simply set <code>ERLC_OPTS</code> to a value that
-does not include <code>+debug_info</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Escripts are an alternative to release. They are meant to be +used for small command line executables written in Erlang.</p></div> +<div class="paragraph"><p>They are not self-contained, unlike <a href="../relx">releases</a>. +Erlang must be installed for them to run. This however means +that they are fairly small compared to releases.</p></div> +<div class="paragraph"><p>For self-contained executables, check <a href="../sfx">self-extracting releases</a>.</p></div> +<div class="sect1"> +<h2 id="_requirements">Requirements</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk uses <code>p7zip</code> by default to generate the escript +archive. Make sure it is installed. On most systems the +package is named <code>p7zip</code>; on Ubuntu you need <code>p7zip-full</code>.</p></div> +<div class="paragraph"><p>If <code>p7zip</code> is unavailable, <code>zip</code> may be used by setting +the <code>ESCRIPT_ZIP</code> variable. For example:</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>$ make escript <span style="color: #009900">ESCRIPT_ZIP</span><span style="color: #990000">=</span>zip</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_an_escript">Generating an escript</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Run the following command to generate an escript:</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>$ make escript</tt></pre></div></div> +<div class="paragraph"><p>This will by default create an escript with the same name as +the project, in the project’s directory. If the project is +called <code>relx</code> then the escript will be in <code>./relx</code>.</p></div> +<div class="paragraph"><p>You can run the escript as you would any executable:</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="color: #990000">.</span>/relx</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can change the name of the escript by setting <code>ESCRIPT_NAME</code>. +The name determines both the default output file name and the +entry module containing the function <code>main/1</code>.</p></div> +<div class="paragraph"><p><code>ESCRIPT_FILE</code> can be set if you need a different file name +or location.</p></div> +<div class="paragraph"><p>The escript header can be entirely customized. The first line +is the shebang, set by <code>ESCRIPT_SHEBANG</code>. The second line is +a comment, set by <code>ESCRIPT_COMMENT</code>. The third line is the +arguments the VM will use when running the escript, set by +<code>ESCRIPT_EMU_ARGS</code>.</p></div> +<div class="paragraph"><p>Finally, <code>ESCRIPT_ZIP</code> can be set to customize the command used +to create the zip file. Read on for more information.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_extra_files">Extra files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Generating an escript is a two-part process. First, a zip file +is created with the contents of the escript. Then a header is +added to this file to create the escript.</p></div> +<div class="paragraph"><p>It is possible to add commands that will be executed between +the two steps. You can for example add extra files to the zip +archive:</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="color: #990000">escript-zip::</span> + <span style="color: #009900">$(verbose)</span> <span style="color: #009900">$(ESCRIPT_ZIP)</span> <span style="color: #009900">$(ESCRIPT_ZIP_FILE)</span> priv/templates<span style="color: #990000">/*</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>ESCRIPT_ZIP</code> variable contains the command to run to add +files to the zip archive <code>ESCRIPT_ZIP_FILE</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_optimizing_for_size">Optimizing for size</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will by default compile BEAM files with debug +information. You may want to disable this behavior to obtain +smaller escript files. Simply set <code>ERLC_OPTS</code> to a value that +does not include <code>+debug_info</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> @@ -167,8 +175,8 @@ does not include <code>+debug_info</code>.</p></div> - <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/"> - Compatibility with other build tools + <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/"> + OTP version management </a> </nav> diff --git a/docs/en/erlang.mk/1/guide/eunit/index.html b/docs/en/erlang.mk/1/guide/eunit/index.html index d3af8b7b..83435883 100644 --- a/docs/en/erlang.mk/1/guide/eunit/index.html +++ b/docs/en/erlang.mk/1/guide/eunit/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: EUnit</title> @@ -67,147 +67,158 @@ <h1 class="lined-header"><span>EUnit</span></h1> -<div class="paragraph"><p>EUnit is the tool of choice for unit testing. Erlang.mk
-automates a few things on top of EUnit, including the
-discovery and running of unit tests.</p></div>
-<div class="sect1">
-<h2 id="_writing_tests">Writing tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/eunit/chapter.html">EUnit user guide</a>
-is the best place to learn how to write tests. Of note is
-that all functions ending with <code>_test</code> or <code>_test_</code> will be
-picked up as EUnit test cases.</p></div>
-<div class="paragraph"><p>Erlang.mk will automatically pick up tests found in any of
-the Erlang modules of your application. It will also pick up
-tests located in the <em>$(TEST_DIR)</em> directory, which defaults
-to <em>test/</em>.</p></div>
-<div class="paragraph"><p>It is generally a good practice to hide test code from
-the code you ship to production. With Erlang.mk, you can
-do this thanks to the <code>TEST</code> macro. It is only defined
-when running tests:</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Insert tests here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000080">-endif</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Be careful, however, if you include the EUnit header file,
-as it also defines the <code>TEST</code> macro. Make sure to only include
-it inside an <code>ifdef</code> block, otherwise tests will always be
-compiled.</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-include_lib</span></span>(<span style="color: #990000">\</span><span style="color: #FF0000">"eunit/include/eunit.hrl\").</span>
-
-<span style="color: #FF0000">%% Insert tests here.</span>
-
-<span style="color: #FF0000">-endif.</span></tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will automatically recompile your code when you
-perform a normal build after running tests, and vice versa.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>EUNIT_OPTS</code> variable allows you to specify additional
-EUnit options. Options are documented in the
-<a href="http://www.erlang.org/doc/man/eunit.html#test-2">EUnit manual</a>.
-At the time of writing, the only available option is <code>verbose</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>EUNIT_ERL_OPTS</code> variable allows you to specify options
-to be passed to <code>erl</code> when running EUnit tests. For example,
-you can load the <em>vm.args</em> and <em>sys.config</em> files:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To run all tests (including EUnit):</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>$ make tests</tt></pre></div></div>
-<div class="paragraph"><p>To run all tests and static checks (including EUnit):</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>$ make check</tt></pre></div></div>
-<div class="paragraph"><p>You can also run EUnit separately:</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>$ make eunit</tt></pre></div></div>
-<div class="paragraph"><p>EUnit will be quiet by default, only outputting errors.
-You can easily make it verbose for a single invocation:</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>$ make eunit <span style="color: #009900">EUNIT_OPTS</span><span style="color: #990000">=</span>verbose</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk allows you to run all tests from a specific
-module, or a specific test case from that module, using
-the variable <code>t</code>.</p></div>
-<div class="paragraph"><p>For example, to run all tests from the <code>cow_http_hd</code>
-module (instead of all tests from the entire project),
-one could write:</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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div>
-<div class="paragraph"><p>Similarly, to run a specific test case:</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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd<span style="color: #990000">:</span>parse_accept_test_</tt></pre></div></div>
-<div class="paragraph"><p>To do the same against a multi-application repository,
-you can use the <code>-C</code> option:</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>$ make -C apps/my_app eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>my_module<span style="color: #990000">:</span>hello_test</tt></pre></div></div>
-<div class="paragraph"><p>Note that this also applies to dependencies. From Cowboy,
-you can run the following directly:</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>$ make -C deps/cowlib eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div>
-<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available,
-but covered in its own chapter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>EUnit is the tool of choice for unit testing. Erlang.mk +automates a few things on top of EUnit, including the +discovery and running of unit tests.</p></div> +<div class="sect1"> +<h2 id="_writing_tests">Writing tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/eunit/chapter.html">EUnit user guide</a> +is the best place to learn how to write tests. Of note is +that all functions ending with <code>_test</code> or <code>_test_</code> will be +picked up as EUnit test cases.</p></div> +<div class="paragraph"><p>Erlang.mk will automatically pick up tests found in any of +the Erlang modules of your application. It will also pick up +tests located in the <em>$(TEST_DIR)</em> directory, which defaults +to <em>test/</em>.</p></div> +<div class="paragraph"><p>It is generally a good practice to hide test code from +the code you ship to production. With Erlang.mk, you can +do this thanks to the <code>TEST</code> macro. It is only defined +when running tests:</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Insert tests here.</span></span> + +<span style="font-weight: bold"><span style="color: #000080">-endif</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Be careful, however, if you include the EUnit header file, +as it also defines the <code>TEST</code> macro. Make sure to only include +it inside an <code>ifdef</code> block, otherwise tests will always be +compiled.</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-include_lib</span></span>(<span style="color: #990000">\</span><span style="color: #FF0000">"eunit/include/eunit.hrl\").</span> + +<span style="color: #FF0000">%% Insert tests here.</span> + +<span style="color: #FF0000">-endif.</span></tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will automatically recompile your code when you +perform a normal build after running tests, and vice versa.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>EUNIT_OPTS</code> variable allows you to specify additional +EUnit options. Options are documented in the +<a href="http://www.erlang.org/doc/man/eunit.html#test-2">EUnit manual</a>. +At the time of writing, the only available option is <code>verbose</code>:</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="color: #009900">EUNIT_OPTS =</span> verbose</tt></pre></div></div> +<div class="paragraph"><p>The <code>EUNIT_ERL_OPTS</code> variable allows you to specify options +to be passed to <code>erl</code> when running EUnit tests. For example, +you can load the <em>vm.args</em> and <em>sys.config</em> files:</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="color: #009900">EUNIT_ERL_OPTS =</span> -args_file rel/vm.args -config rel/sys.config</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To run all tests (including EUnit):</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>$ make tests</tt></pre></div></div> +<div class="paragraph"><p>To run all tests and static checks (including EUnit):</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>$ make check</tt></pre></div></div> +<div class="paragraph"><p>You can also run EUnit separately:</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>$ make eunit</tt></pre></div></div> +<div class="paragraph"><p>EUnit will be quiet by default, only outputting errors. +You can easily make it verbose for a single invocation:</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>$ make eunit <span style="color: #009900">EUNIT_OPTS</span><span style="color: #990000">=</span>verbose</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk allows you to run all tests from a specific +module, or a specific test case from that module, using +the variable <code>t</code>.</p></div> +<div class="paragraph"><p>For example, to run all tests from the <code>cow_http_hd</code> +module (instead of all tests from the entire project), +one could write:</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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div> +<div class="paragraph"><p>Similarly, to run a specific test case:</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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd<span style="color: #990000">:</span>parse_accept_test_</tt></pre></div></div> +<div class="paragraph"><p>To do the same against a multi-application repository, +you can use the <code>-C</code> option:</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>$ make -C apps/my_app eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>my_module<span style="color: #990000">:</span>hello_test</tt></pre></div></div> +<div class="paragraph"><p>Note that this also applies to dependencies. From Cowboy, +you can run the following directly:</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>$ make -C deps/cowlib eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div> +<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available, +but covered in its own chapter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/external_plugins/index.html b/docs/en/erlang.mk/1/guide/external_plugins/index.html index 13d83701..6a901281 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: External plugins</title> @@ -67,116 +67,163 @@ <h1 class="lined-header"><span>External plugins</span></h1> -<div class="paragraph"><p>It is often convenient to be able to keep the build files
-used by all your projects in one place. Those files could
-be Makefiles, configuration files, templates and more.</p></div>
-<div class="paragraph"><p>Erlang.mk allows you to automatically load plugins from
-dependencies. Plugins can do anything, including defining
-new variables, defining file templates, hooking themselves
-inside the normal Erlang.mk processing or even adding new
-rules.</p></div>
-<div class="paragraph"><p>You can load plugins using one of two methods. You can
-either load all plugins from a dependency, or just one.
-We will also cover conventions about writing external
-plugins.</p></div>
-<div class="sect1">
-<h2 id="_loading_all_plugins_from_a_dependency">Loading all plugins from a dependency</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To load plugins from a dependency, all you need to do is add
-the dependency name to <code>DEP_PLUGINS</code> in addition to the list
-of dependencies.</p></div>
-<div class="paragraph"><p>For example, if you have <code>cowboy</code> in <code>DEPS</code>, add <code>cowboy</code> in
-<code>DEP_PLUGINS</code> also:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This will load the file <em>plugins.mk</em> in the root folder of
-the Cowboy repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_loading_one_plugin_from_a_dependency">Loading one plugin from a dependency</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Now that we know how to load all plugins, let’s take a look
-at how to load one specific plugin from a dependency.</p></div>
-<div class="paragraph"><p>To do this, instead of writing only the name of the dependency,
-we will write its name and the path to the plugin file. This
-means that writing <code>DEP_PLUGINS = cowboy</code> is equivalent to
-writing <code>DEP_PLUGINS = cowboy/plugins.mk</code>.</p></div>
-<div class="paragraph"><p>Knowing this, if we were to load the plugin <em>mk/dist.mk</em>
-from Cowboy and no other, we would write the following in
-our Makefile:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_external_plugins">Writing external plugins</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <em>plugins.mk</em> file is a convention. It is meant to load
-all the plugins from the dependency. The code for the plugin
-can be written directly in <em>plugins.mk</em> or be separate.</p></div>
-<div class="paragraph"><p>If you are providing more than one plugin with your repository,
-the recommended way is to create one file per plugin in the
-<em>mk/</em> folder in your repository, and then include those
-individual plugins in <em>plugins.mk</em>.</p></div>
-<div class="paragraph"><p>For example, if you have two plugins <em>mk/dist.mk</em> and
-<em>mk/templates.mk</em>, you could write the following <em>plugins.mk</em>
-file:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>THIS</code> variable is required to relatively include files.</p></div>
-<div class="paragraph"><p>This allows users to not only be able to select individual
-plugins, but also select all plugins from the dependency
-in one go if they wish to do so.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_early_stage_plugins">Early-stage plugins</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Plugins declared in <code>DEP_PLUGINS</code> are loaded near the end of Erlang.mk.
-That’s why you have access to all previously initialized variables.
-However, if you want your plugin to add common dependencies to
-your applications, a regular is loaded too late in the process.
-You need to use "Early-stage plugins". They are declared using the
-<code>DEP_EARLY_PLUGINS</code> variable instead. Plugins listed in this variable
-are loaded near the beginning of Erlang.mk Otherwise, they work exactly
-the same.</p></div>
-<div class="paragraph"><p>If you only give the name of a dependency, the default file loaded is
-<em>early-plugins.mk</em>. You can specify a filename exactly like you would
-have done it with regular plugins.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_loading_plugins_local_to_the_application">Loading plugins local to the application</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If the Erlang.mk plugin lives in the same directory or repository as your
-application or library, then you can load it exactly like an external
-plugin: the dependency name is simply the name of your application or
-library.</p></div>
-<div class="paragraph"><p>For example, the following Makefile loads a plugin in the <em>mk</em>
-subdirectory:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This also works with early-stage plugins:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Like external plugins, if you do not specify the path to the plugin, it
-defaults to <em>plugins.mk</em> or <em>early-plugins.mk</em>, located at the root of
-your application:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
+<div class="paragraph"><p>It is often convenient to be able to keep the build files +used by all your projects in one place. Those files could +be Makefiles, configuration files, templates and more.</p></div> +<div class="paragraph"><p>Erlang.mk allows you to automatically load plugins from +dependencies. Plugins can do anything, including defining +new variables, defining file templates, hooking themselves +inside the normal Erlang.mk processing or even adding new +rules.</p></div> +<div class="paragraph"><p>You can load plugins using one of two methods. You can +either load all plugins from a dependency, or just one. +We will also cover conventions about writing external +plugins.</p></div> +<div class="sect1"> +<h2 id="_loading_all_plugins_from_a_dependency">Loading all plugins from a dependency</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To load plugins from a dependency, all you need to do is add +the dependency name to <code>DEP_PLUGINS</code> in addition to the list +of dependencies.</p></div> +<div class="paragraph"><p>For example, if you have <code>cowboy</code> in <code>DEPS</code>, add <code>cowboy</code> in +<code>DEP_PLUGINS</code> also:</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="color: #009900">DEPS =</span> cowboy +<span style="color: #009900">DEP_PLUGINS =</span> cowboy</tt></pre></div></div> +<div class="paragraph"><p>This will load the file <em>plugins.mk</em> in the root folder of +the Cowboy repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_loading_one_plugin_from_a_dependency">Loading one plugin from a dependency</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Now that we know how to load all plugins, let’s take a look +at how to load one specific plugin from a dependency.</p></div> +<div class="paragraph"><p>To do this, instead of writing only the name of the dependency, +we will write its name and the path to the plugin file. This +means that writing <code>DEP_PLUGINS = cowboy</code> is equivalent to +writing <code>DEP_PLUGINS = cowboy/plugins.mk</code>.</p></div> +<div class="paragraph"><p>Knowing this, if we were to load the plugin <em>mk/dist.mk</em> +from Cowboy and no other, we would write the following in +our Makefile:</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="color: #009900">DEPS =</span> cowboy +<span style="color: #009900">DEP_PLUGINS =</span> cowboy/mk/dist.mk</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_external_plugins">Writing external plugins</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <em>plugins.mk</em> file is a convention. It is meant to load +all the plugins from the dependency. The code for the plugin +can be written directly in <em>plugins.mk</em> or be separate.</p></div> +<div class="paragraph"><p>If you are providing more than one plugin with your repository, +the recommended way is to create one file per plugin in the +<em>mk/</em> folder in your repository, and then include those +individual plugins in <em>plugins.mk</em>.</p></div> +<div class="paragraph"><p>For example, if you have two plugins <em>mk/dist.mk</em> and +<em>mk/templates.mk</em>, you could write the following <em>plugins.mk</em> +file:</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="color: #990000">THIS :=</span> <span style="color: #009900">$(</span>dir <span style="color: #009900">$(</span>realpath <span style="color: #009900">$(</span>lastword <span style="color: #009900">$(MAKEFILE_LIST))))</span> +include <span style="color: #009900">$(THIS)</span>/mk/dist.mk +include <span style="color: #009900">$(THIS)</span>/mk/templates.mk</tt></pre></div></div> +<div class="paragraph"><p>The <code>THIS</code> variable is required to relatively include files.</p></div> +<div class="paragraph"><p>This allows users to not only be able to select individual +plugins, but also select all plugins from the dependency +in one go if they wish to do so.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_early_stage_plugins">Early-stage plugins</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Plugins declared in <code>DEP_PLUGINS</code> are loaded near the end of Erlang.mk. +That’s why you have access to all previously initialized variables. +However, if you want your plugin to add common dependencies to +your applications, a regular is loaded too late in the process. +You need to use "Early-stage plugins". They are declared using the +<code>DEP_EARLY_PLUGINS</code> variable instead. Plugins listed in this variable +are loaded near the beginning of Erlang.mk Otherwise, they work exactly +the same.</p></div> +<div class="paragraph"><p>If you only give the name of a dependency, the default file loaded is +<em>early-plugins.mk</em>. You can specify a filename exactly like you would +have done it with regular plugins.</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-style: italic"><span style="color: #9A1900"># In your application's Makefile</span></span> +<span style="color: #009900">BUILD_DEPS =</span> common_deps +<span style="color: #009900">DEP_EARLY_PLUGINS =</span> common_deps</tt></pre></div></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-style: italic"><span style="color: #9A1900"># In the plugin's early-plugins.mk</span></span> +DEPS <span style="color: #990000">+=</span> cowboy +<span style="color: #009900">TEST_DEPS =</span> ct_helper +<span style="color: #009900">dep_ct_helper =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/ct_helper master</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_loading_plugins_local_to_the_application">Loading plugins local to the application</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If the Erlang.mk plugin lives in the same directory or repository as your +application or library, then you can load it exactly like an external +plugin: the dependency name is simply the name of your application or +library.</p></div> +<div class="paragraph"><p>For example, the following Makefile loads a plugin in the <em>mk</em> +subdirectory:</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="color: #009900">DEP_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span>/mk/dist.mk</tt></pre></div></div> +<div class="paragraph"><p>This also works with early-stage plugins:</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="color: #009900">DEP_EARLY_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span>/mk/variables.mk</tt></pre></div></div> +<div class="paragraph"><p>Like external plugins, if you do not specify the path to the plugin, it +defaults to <em>plugins.mk</em> or <em>early-plugins.mk</em>, located at the root of +your application:</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-style: italic"><span style="color: #9A1900"># Loads ./early-plugins.mk</span></span> +<span style="color: #009900">DEP_EARLY_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span> +<span style="font-style: italic"><span style="color: #9A1900"># Loads ./plugins.mk</span></span> +<span style="color: #009900">DEP_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html index 452edb39..694b0c58 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: List of plugins</title> @@ -67,93 +67,96 @@ <h1 class="lined-header"><span>List of plugins</span></h1> -<div class="paragraph"><p>This is a non-exhaustive list of Erlang.mk plugins, sorted
-alphabetically.</p></div>
-<div class="sect1">
-<h2 id="_efene_mk">efene.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/ninenines/efene.mk">Efene plugin</a> for Erlang.mk.
-<a href="http://efene.org/">Efene</a> is an alternative language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_elixir_mk">elixir.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/botsunit/elixir.mk">Elixir plugin</a> for
-Erlang.mk. <a href="http://elixir-lang.org/">Elixir</a> is an alternative
-language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_elvis_mk">elvis.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/inaka/elvis.mk">Elvis plugin</a> for Erlang.mk.
-Elvis is an <a href="https://github.com/inaka/elvis">Erlang style reviewer</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_geas">geas</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="https://github.com/crownedgrouse/geas">Geas</a> gives aggregated
-information on a project and its dependencies, and is available
-as an Erlang.mk plugin.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hexer_mk">hexer.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/inaka/hexer.mk">Hex plugin</a> for Erlang.mk
-using the <code>hexer</code> tool.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hexpm_mk">hexpm.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Another <a href="https://github.com/botsunit/hexpm.mk">Hex plugin</a> for
-Erlang.mk, with support for Hex dependency operators.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_jorel">jorel</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="https://github.com/emedia-project/jorel">Jorel</a> is Just anOther RELease
-assembler for Erlang/OTP, and is available as an Erlang.mk plugin.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_lfe_mk">lfe.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/ninenines/lfe.mk">LFE plugin</a> for Erlang.mk.
-LFE, or <a href="http://lfe.io/">Lisp Flavoured Erlang</a>, is an alternative
-language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_mix_mk">mix.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <a href="https://github.com/botsunit/mix.mk">Mix plugin</a> for Erlang.mk,
-to generate a compatible configuration file for
-<a href="http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html">Mix</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reload_mk">reload.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <a href="https://github.com/bullno1/reload.mk">live reload plugin</a> for Erlang.mk.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rust_mk">rust.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <a href="https://github.com/goertzenator/rust.mk">plugin</a> to build <a href="https://www.rust-lang.org/">Rust</a> crates and install binaries into <code>priv/</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically.</p></div> +<div class="sect1"> +<h2 id="_efene_mk">efene.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/ninenines/efene.mk">Efene plugin</a> for Erlang.mk. +<a href="http://efene.org/">Efene</a> is an alternative language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_elixir_mk">elixir.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/botsunit/elixir.mk">Elixir plugin</a> for +Erlang.mk. <a href="http://elixir-lang.org/">Elixir</a> is an alternative +language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_elvis_mk">elvis.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/inaka/elvis.mk">Elvis plugin</a> for Erlang.mk. +Elvis is an <a href="https://github.com/inaka/elvis">Erlang style reviewer</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_geas">geas</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="https://github.com/crownedgrouse/geas">Geas</a> gives aggregated +information on a project and its dependencies, and is available +as an Erlang.mk plugin.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hexer_mk">hexer.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/inaka/hexer.mk">Hex plugin</a> for Erlang.mk +using the <code>hexer</code> tool.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hexpm_mk">hexpm.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Another <a href="https://github.com/botsunit/hexpm.mk">Hex plugin</a> for +Erlang.mk, with support for Hex dependency operators.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_jorel">jorel</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="https://github.com/emedia-project/jorel">Jorel</a> is Just anOther RELease +assembler for Erlang/OTP, and is available as an Erlang.mk plugin.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_lfe_mk">lfe.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/ninenines/lfe.mk">LFE plugin</a> for Erlang.mk. +LFE, or <a href="http://lfe.io/">Lisp Flavoured Erlang</a>, is an alternative +language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_mix_mk">mix.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <a href="https://github.com/botsunit/mix.mk">Mix plugin</a> for Erlang.mk, +to generate a compatible configuration file for +<a href="http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html">Mix</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reload_mk">reload.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <a href="https://github.com/bullno1/reload.mk">live reload plugin</a> for Erlang.mk.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rust_mk">rust.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <a href="https://github.com/goertzenator/rust.mk">plugin</a> to build <a href="https://www.rust-lang.org/">Rust</a> crates and install binaries into <code>priv/</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html index 2652c05d..dc20db0c 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Getting started</title> @@ -67,364 +67,371 @@ <h1 class="lined-header"><span>Getting started</span></h1> -<div class="paragraph"><p>This chapter explains how to get started using Erlang.mk.</p></div>
-<div class="sect1">
-<h2 id="_creating_a_folder_for_your_project">Creating a folder for your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first step is always to create a new folder that will
-contain your project.</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>$ mkdir hello_joe
-$ cd hello_joe</tt></pre></div></div>
-<div class="paragraph"><p>Most people tend to put all their projects side by side in
-a common folder. We recommend keeping an organization similar
-to your remote repositories. For example, for GitHub users,
-put all your projects in a common folder with the same name
-as your username. For example <em>$HOME/ninenines/cowboy</em> for
-the Cowboy project.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_downloading_erlang_mk">Downloading Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>At the time of writing, Erlang.mk is unlikely to be present
-in your Erlang distribution, or even in your OS packages.</p></div>
-<div class="paragraph"><p>The next step is therefore to download 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>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
-<div class="paragraph"><p>Or:</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>$ curl -O https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
-<div class="paragraph"><p>Alternatively, just <a href="https://erlang.mk/erlang.mk">click on this link</a>.</p></div>
-<div class="paragraph"><p>Make sure you put the file inside the folder we created previously.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_applications">Getting started with OTP applications</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP application is an Erlang application that has a supervision
-tree. In other words, it will always have processes running.</p></div>
-<div class="paragraph"><p>This kind of project can be automatically generated by Erlang.mk.
-All you need to do is use the <code>bootstrap</code> target:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap</tt></pre></div></div>
-<div class="paragraph"><p>Something similar to the following snippet will then appear
-on your screen:</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>git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build
-Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span>
-remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span>
-Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">784.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
-cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span>
-awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span>
- <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span>
-cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk
-rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div>
-<div class="paragraph"><p>This is Erlang.mk bootstrapping itself. Indeed, the file you
-initially downloaded contains nothing more than the code needed
-to bootstrap. This operation is done only once. Consult the
-<a href="../updating">Updating Erlang.mk</a> chapter for more
-information.</p></div>
-<div class="paragraph"><p>Of course, the generated project can now be compiled:</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>$ make</tt></pre></div></div>
-<div class="paragraph"><p>Cheers!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_libraries">Getting started with OTP libraries</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP library is an Erlang application that has no supervision
-tree. In other words, it is nothing but modules.</p></div>
-<div class="paragraph"><p>This kind of project can also be generated by Erlang.mk, using
-the <code>bootstrap-lib</code> target:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will once again bootstrap itself and generate all
-the files for your project. You can now compile 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>$ make</tt></pre></div></div>
-<div class="paragraph"><p>Enjoy!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_releases">Getting started with OTP releases</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP release is the combination of the Erlang RunTime System (ERTS)
-along with all the libraries and files that your node will need
-to run. It is entirely self contained, and can often be sent as-is
-to your production system and run without any extra setup.</p></div>
-<div class="paragraph"><p>Erlang.mk can of course bootstrap your project to generate releases.
-You can use the <code>bootstrap-rel</code> target for this purpose:</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>$ make bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>This target can be combined with <code>bootstrap</code> or <code>bootstrap-lib</code> to
-create a project that will build a release:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>It is often very useful to keep the top-level project for
-commands useful during operations, and put the components
-of the system in separate applications that you will then
-depend on. Consult the <a href="../deps">Packages and dependencies</a>
-chapter for more information.</p></div>
-<div class="paragraph"><p>When you run <code>make</code> from now on, Erlang.mk will compile your
-project and build the release:</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>$ make
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src
- GEN distclean-relx-rel
- GEN /home/essen/tmp/hello_joe/relx
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/essen/tmp/hello_joe/ebin
- /usr/lib/erlang/lib
- /home/essen/tmp/hello_joe/deps
-<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span>
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span></tt></pre></div></div>
-<div class="paragraph"><p>The first time you run this command, Erlang.mk will download
-<em>relx</em>, the release building tool. So don’t worry if you see
-more output than above.</p></div>
-<div class="paragraph"><p>If building the release is slow, no need to upgrade your
-hardware just yet. Just consult the <a href="../relx">Releases</a>
-chapter for various tips to speed up build time during
-development.</p></div>
-<div class="paragraph"><p>You can start the release using the <em>./_rel/hello_joe_release/bin/hello_joe_release</em>
-script, or simply run <code>make run</code>. The latter will also compile
-your project and build the release if it wasn’t already:</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>$ make run
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src
- GEN distclean-relx-rel
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/essen/tmp/hello_joe/ebin
- /usr/lib/erlang/lib
- /home/essen/tmp/hello_joe/deps
-<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span>
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span>
-Exec<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span>/bin/erlexec -boot /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span><span style="color: #990000">/..</span>/lib -env ERL_LIBS /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/lib -config /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/sys<span style="color: #990000">.</span>config -args_file /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/vm<span style="color: #990000">.</span>args -- console
-Root<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release
-/home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release
-heart_beat_kill_pid <span style="color: #990000">=</span> <span style="color: #993399">16389</span>
-Erlang/OTP <span style="color: #993399">18</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">7.0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">10</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span>
-
-Eshell V7<span style="color: #990000">.</span><span style="color: #993399">0</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span>
-<span style="color: #990000">(</span>hello_joe@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div>
-<div class="paragraph"><p>Simple as that!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_from_scratch">Getting started from scratch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you already have an application, or you want to have full
-control over what files will be created, you can setup Erlang.mk
-manually.</p></div>
-<div class="paragraph"><p>Erlang.mk is very easy to setup: all that you need to do is to
-create a folder, put Erlang.mk in it, and write a one line
-Makefile containing:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>For a step by step:</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>$ mkdir hello_joe
-$ cd hello_joe
-$ curl https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk -o erlang<span style="color: #990000">.</span>mk
-$ echo <span style="color: #FF0000">"include erlang.mk"</span> <span style="color: #990000">></span> Makefile
-$ make</tt></pre></div></div>
-<div class="paragraph"><p>From that point onward you can create an <code>src/</code> folder or start
-using templates.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_spaces_instead_of_tabs">Using spaces instead of tabs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk defaults to tabs when creating files from templates.
-This is in part because of a personal preference, and in part
-because it is much easier to convert tabs to spaces than the
-opposite.</p></div>
-<div class="paragraph"><p>Use the <code>SP</code> variable if you prefer spaces. Set it to the number
-of spaces per indentation level you want.</p></div>
-<div class="paragraph"><p>For example, if you prefer two spaces per indentation level:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">SP</span><span style="color: #990000">=</span><span style="color: #993399">2</span></tt></pre></div></div>
-<div class="paragraph"><p>When you bootstrap the project initially, the variable automatically
-gets added to the Makefile, so you only need to provide it when
-you get started.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_templates">Using templates</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is no secret that Erlang’s OTP behaviors tend to have some
-boilerplate. It is rarely an issue of course, except when
-creating new modules. That’s why Erlang.mk not only comes with
-templates for generating projects, but also individual modules!</p></div>
-<div class="paragraph"><p>You can list all available templates with the <code>list-templates</code>
-target:</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>$ make list-templates
-Available templates<span style="color: #990000">:</span> cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor</tt></pre></div></div>
-<div class="paragraph"><p>To generate a module, let’s say a <code>gen_server</code>, all you need to
-do is to call <code>make new</code> with the appropriate arguments:</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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server</tt></pre></div></div>
-<div class="paragraph"><p>This will create a module located in <em>src/my_server.erl</em>
-using the <code>gen_server</code> template.</p></div>
-<div class="paragraph"><p>This module is automatically compiled the next time you run
-<code>make</code>:</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>$ make
- ERLC my_server<span style="color: #990000">.</span>erl
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src</tt></pre></div></div>
-<div class="paragraph"><p>All that’s left to do is to open it in your favorite editor
-and make it do something!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hiding_erlang_mk_from_git">Hiding Erlang.mk from git</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a large text file. It can easily take a large part of
-a <code>git diff</code> or a <code>git grep</code> command. You can avoid this by telling
-Git that <em>erlang.mk</em> is a binary file.</p></div>
-<div class="paragraph"><p>Add this to your <em>.gitattributes</em> file. This is a file that you
-can create at the root of your repository:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>erlang.mk -diff</code></pre>
-</div></div>
-<div class="paragraph"><p>The <em>erlang.mk</em> file will still appear in diffs and greps, but
-as a binary file, meaning its contents won’t be shown by default
-anymore.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_help">Getting help</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>During development, if you don’t remember the name of a target,
-you can always run <code>make help</code>:</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>$ make <span style="font-weight: bold"><span style="color: #0000FF">help</span></span>
-erlang<span style="color: #990000">.</span>mk <span style="color: #990000">(</span>version <span style="color: #993399">1.2</span><span style="color: #990000">.</span><span style="color: #993399">0</span>-<span style="color: #993399">642</span>-gccd2b9f<span style="color: #990000">)</span> is distributed under the terms of the ISC License<span style="color: #990000">.</span>
-Copyright <span style="color: #990000">(</span>c<span style="color: #990000">)</span> <span style="color: #993399">2013</span>-<span style="color: #993399">2016</span> Loïc Hoguin <span style="color: #990000"><</span>essen@ninenines<span style="color: #990000">.</span>eu<span style="color: #990000">></span>
-
-Usage<span style="color: #990000">:</span> <span style="color: #990000">[</span><span style="color: #009900">V</span><span style="color: #990000">=</span><span style="color: #993399">1</span><span style="color: #990000">]</span> make <span style="color: #990000">[</span>target<span style="color: #990000">]...</span>
-
-Core targets<span style="color: #990000">:</span>
- all Run deps<span style="color: #990000">,</span> app and rel targets <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> that order
- app Compile the project
- deps Fetch dependencies <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">if</span></span> needed<span style="color: #990000">)</span> and compile them
- search <span style="color: #009900">q</span><span style="color: #990000">=...</span> Search <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> a package <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> the built-in index
- rel Build a release <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> applicable
- docs Build the documentation <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- install-docs Install the man pages <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- check Compile and run all tests and analysis <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- tests Run the tests <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- clean Delete temporary and output files from most targets
- distclean Delete all temporary and output files
- <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> Display this <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> and <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span>
- erlang-mk Update erlang<span style="color: #990000">.</span>mk to the latest version
-
-Bootstrap targets<span style="color: #990000">:</span>
- bootstrap Generate a skeleton of an OTP application
- bootstrap-lib Generate a skeleton of an OTP library
- bootstrap-rel Generate the files needed to build a release
- new <span style="color: #009900">t</span><span style="color: #990000">=</span>TPL <span style="color: #009900">n</span><span style="color: #990000">=</span>NAME Generate a module NAME based on the template TPL
- list-templates List available templates
-<span style="color: #990000">...</span></tt></pre></div></div>
-<div class="paragraph"><p>This guide should provide any other answer. If not, please
-open a ticket on <a href="https://github.com/ninenines/erlang.mk/issues">the official repository</a>
-and we will work on improving the guide.</p></div>
-<div class="paragraph"><p>Commercial support is available through Nine Nines. Please contact
-Loïc Hoguin by sending an email to <a href="mailto:[email protected]">[email protected]</a>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter explains how to get started using Erlang.mk.</p></div> +<div class="sect1"> +<h2 id="_creating_a_folder_for_your_project">Creating a folder for your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first step is always to create a new folder that will +contain your project.</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>$ mkdir hello_joe +$ cd hello_joe</tt></pre></div></div> +<div class="paragraph"><p>Most people tend to put all their projects side by side in +a common folder. We recommend keeping an organization similar +to your remote repositories. For example, for GitHub users, +put all your projects in a common folder with the same name +as your username. For example <em>$HOME/ninenines/cowboy</em> for +the Cowboy project.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_downloading_erlang_mk">Downloading Erlang.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>At the time of writing, Erlang.mk is unlikely to be present +in your Erlang distribution, or even in your OS packages.</p></div> +<div class="paragraph"><p>The next step is therefore to download 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>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div> +<div class="paragraph"><p>Or:</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>$ curl -O https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div> +<div class="paragraph"><p>Alternatively, just <a href="https://erlang.mk/erlang.mk">click on this link</a>.</p></div> +<div class="paragraph"><p>Make sure you put the file inside the folder we created previously.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_applications">Getting started with OTP applications</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP application is an Erlang application that has a supervision +tree. In other words, it will always have processes running.</p></div> +<div class="paragraph"><p>This kind of project can be automatically generated by Erlang.mk. +All you need to do is use the <code>bootstrap</code> target:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap</tt></pre></div></div> +<div class="paragraph"><p>Something similar to the following snippet will then appear +on your screen:</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>git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build +Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span> +remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span> +Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">784.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span> +cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span> +awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span> + <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span> +cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk +rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div> +<div class="paragraph"><p>This is Erlang.mk bootstrapping itself. Indeed, the file you +initially downloaded contains nothing more than the code needed +to bootstrap. This operation is done only once. Consult the +<a href="../updating">Updating Erlang.mk</a> chapter for more +information.</p></div> +<div class="paragraph"><p>Of course, the generated project can now be compiled:</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>$ make</tt></pre></div></div> +<div class="paragraph"><p>Cheers!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_libraries">Getting started with OTP libraries</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP library is an Erlang application that has no supervision +tree. In other words, it is nothing but modules.</p></div> +<div class="paragraph"><p>This kind of project can also be generated by Erlang.mk, using +the <code>bootstrap-lib</code> target:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will once again bootstrap itself and generate all +the files for your project. You can now compile 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>$ make</tt></pre></div></div> +<div class="paragraph"><p>Enjoy!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_releases">Getting started with OTP releases</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP release is the combination of the Erlang RunTime System (ERTS) +along with all the libraries and files that your node will need +to run. It is entirely self contained, and can often be sent as-is +to your production system and run without any extra setup.</p></div> +<div class="paragraph"><p>Erlang.mk can of course bootstrap your project to generate releases. +You can use the <code>bootstrap-rel</code> target for this purpose:</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>$ make bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>This target can be combined with <code>bootstrap</code> or <code>bootstrap-lib</code> to +create a project that will build a release:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>It is often very useful to keep the top-level project for +commands useful during operations, and put the components +of the system in separate applications that you will then +depend on. Consult the <a href="../deps">Packages and dependencies</a> +chapter for more information.</p></div> +<div class="paragraph"><p>When you run <code>make</code> from now on, Erlang.mk will compile your +project and build the release:</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>$ make + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src + GEN distclean-relx-rel + GEN /home/essen/tmp/hello_joe/relx +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span> +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span></tt></pre></div></div> +<div class="paragraph"><p>The first time you run this command, Erlang.mk will download +<em>relx</em>, the release building tool. So don’t worry if you see +more output than above.</p></div> +<div class="paragraph"><p>If building the release is slow, no need to upgrade your +hardware just yet. Just consult the <a href="../relx">Releases</a> +chapter for various tips to speed up build time during +development.</p></div> +<div class="paragraph"><p>You can start the release using the <em>./_rel/hello_joe_release/bin/hello_joe_release</em> +script, or simply run <code>make run</code>. The latter will also compile +your project and build the release if it wasn’t already:</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>$ make run + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src + GEN distclean-relx-rel +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span> +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span> +Exec<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span>/bin/erlexec -boot /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span><span style="color: #990000">/..</span>/lib -env ERL_LIBS /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/lib -config /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/sys<span style="color: #990000">.</span>config -args_file /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/vm<span style="color: #990000">.</span>args -- console +Root<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release +/home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release +heart_beat_kill_pid <span style="color: #990000">=</span> <span style="color: #993399">16389</span> +Erlang/OTP <span style="color: #993399">18</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">7.0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">10</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span> + +Eshell V7<span style="color: #990000">.</span><span style="color: #993399">0</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span> +<span style="color: #990000">(</span>hello_joe@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div> +<div class="paragraph"><p>Simple as that!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_from_scratch">Getting started from scratch</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you already have an application, or you want to have full +control over what files will be created, you can setup Erlang.mk +manually.</p></div> +<div class="paragraph"><p>Erlang.mk is very easy to setup: all that you need to do is to +create a folder, put Erlang.mk in it, and write a one line +Makefile containing:</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>include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>For a step by step:</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>$ mkdir hello_joe +$ cd hello_joe +$ curl https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk -o erlang<span style="color: #990000">.</span>mk +$ echo <span style="color: #FF0000">"include erlang.mk"</span> <span style="color: #990000">></span> Makefile +$ make</tt></pre></div></div> +<div class="paragraph"><p>From that point onward you can create an <code>src/</code> folder or start +using templates.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_spaces_instead_of_tabs">Using spaces instead of tabs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk defaults to tabs when creating files from templates. +This is in part because of a personal preference, and in part +because it is much easier to convert tabs to spaces than the +opposite.</p></div> +<div class="paragraph"><p>Use the <code>SP</code> variable if you prefer spaces. Set it to the number +of spaces per indentation level you want.</p></div> +<div class="paragraph"><p>For example, if you prefer two spaces per indentation level:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">SP</span><span style="color: #990000">=</span><span style="color: #993399">2</span></tt></pre></div></div> +<div class="paragraph"><p>When you bootstrap the project initially, the variable automatically +gets added to the Makefile, so you only need to provide it when +you get started.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_templates">Using templates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is no secret that Erlang’s OTP behaviors tend to have some +boilerplate. It is rarely an issue of course, except when +creating new modules. That’s why Erlang.mk not only comes with +templates for generating projects, but also individual modules!</p></div> +<div class="paragraph"><p>You can list all available templates with the <code>list-templates</code> +target:</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>$ make list-templates +Available templates<span style="color: #990000">:</span> cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor</tt></pre></div></div> +<div class="paragraph"><p>To generate a module, let’s say a <code>gen_server</code>, all you need to +do is to call <code>make new</code> with the appropriate arguments:</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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server</tt></pre></div></div> +<div class="paragraph"><p>This will create a module located in <em>src/my_server.erl</em> +using the <code>gen_server</code> template.</p></div> +<div class="paragraph"><p>This module is automatically compiled the next time you run +<code>make</code>:</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>$ make + ERLC my_server<span style="color: #990000">.</span>erl + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src</tt></pre></div></div> +<div class="paragraph"><p>All that’s left to do is to open it in your favorite editor +and make it do something!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hiding_erlang_mk_from_git">Hiding Erlang.mk from git</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a large text file. It can easily take a large part of +a <code>git diff</code> or a <code>git grep</code> command. You can avoid this by telling +Git that <em>erlang.mk</em> is a binary file.</p></div> +<div class="paragraph"><p>Add this to your <em>.gitattributes</em> file. This is a file that you +can create at the root of your repository:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>erlang.mk -diff</code></pre> +</div></div> +<div class="paragraph"><p>The <em>erlang.mk</em> file will still appear in diffs and greps, but +as a binary file, meaning its contents won’t be shown by default +anymore.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_help">Getting help</h2> +<div class="sectionbody"> +<div class="paragraph"><p>During development, if you don’t remember the name of a target, +you can always run <code>make help</code>:</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>$ make <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> +erlang<span style="color: #990000">.</span>mk <span style="color: #990000">(</span>version <span style="color: #993399">1.2</span><span style="color: #990000">.</span><span style="color: #993399">0</span>-<span style="color: #993399">642</span>-gccd2b9f<span style="color: #990000">)</span> is distributed under the terms of the ISC License<span style="color: #990000">.</span> +Copyright <span style="color: #990000">(</span>c<span style="color: #990000">)</span> <span style="color: #993399">2013</span>-<span style="color: #993399">2016</span> Loïc Hoguin <span style="color: #990000"><</span>essen@ninenines<span style="color: #990000">.</span>eu<span style="color: #990000">></span> + +Usage<span style="color: #990000">:</span> <span style="color: #990000">[</span><span style="color: #009900">V</span><span style="color: #990000">=</span><span style="color: #993399">1</span><span style="color: #990000">]</span> make <span style="color: #990000">[</span>target<span style="color: #990000">]...</span> + +Core targets<span style="color: #990000">:</span> + all Run deps<span style="color: #990000">,</span> app and rel targets <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> that order + app Compile the project + deps Fetch dependencies <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">if</span></span> needed<span style="color: #990000">)</span> and compile them + search <span style="color: #009900">q</span><span style="color: #990000">=...</span> Search <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> a package <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> the built-in index + rel Build a release <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> applicable + docs Build the documentation <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + install-docs Install the man pages <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + check Compile and run all tests and analysis <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + tests Run the tests <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + clean Delete temporary and output files from most targets + distclean Delete all temporary and output files + <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> Display this <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> and <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span> + erlang-mk Update erlang<span style="color: #990000">.</span>mk to the latest version + +Bootstrap targets<span style="color: #990000">:</span> + bootstrap Generate a skeleton of an OTP application + bootstrap-lib Generate a skeleton of an OTP library + bootstrap-rel Generate the files needed to build a release + new <span style="color: #009900">t</span><span style="color: #990000">=</span>TPL <span style="color: #009900">n</span><span style="color: #990000">=</span>NAME Generate a module NAME based on the template TPL + list-templates List available templates +<span style="color: #990000">...</span></tt></pre></div></div> +<div class="paragraph"><p>This guide should provide any other answer. If not, please +open a ticket on <a href="https://github.com/ninenines/erlang.mk/issues">the official repository</a> +and we will work on improving the guide.</p></div> +<div class="paragraph"><p>Commercial support is available through Nine Nines. Please contact +Loïc Hoguin by sending an email to <a href="mailto:[email protected]">[email protected]</a>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/history/index.html b/docs/en/erlang.mk/1/guide/history/index.html index 07482cec..5bad3b62 100644 --- a/docs/en/erlang.mk/1/guide/history/index.html +++ b/docs/en/erlang.mk/1/guide/history/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Short history</title> @@ -67,67 +67,70 @@ <h1 class="lined-header"><span>Short history</span></h1> -<div class="paragraph"><p>This chapter aims to be a brief record of the life of the
-Erlang.mk project.</p></div>
-<div class="sect1">
-<h2 id="_before_erlang_mk">Before Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk originates from the Cowboy project. Cowboy started
-as a Rebar project and I, Loïc Hoguin, was very happy with it
-for a couple years. Over time however I started getting annoyed
-and frustrated by a number of things, including bad defaults,
-changing defaults and overall slowness.</p></div>
-<div class="paragraph"><p>In particular, at the time I gave up on Rebar, the Cowboy
-test suite was taking about five minutes to run. A quick experiment
-showed I could get much lower times by simply invoking <code>ct_run</code>
-directly. On January 4th, 2013, the Cowboy test suite took less
-than a minute to complete.</p></div>
-<div class="paragraph"><p>Following this success I started removing a little more and,
-on the fateful day of January 5th, 2013, removed the dependency
-on Rebar entirely. Rebar, and in particular the concept of
-dependencies, was, and still is, a pretty strong influence.</p></div>
-<div class="paragraph"><p>Erlang.mk was conceived.</p></div>
-<div class="paragraph"><p>A few months passed and, on May 1st, 2013, the Erlang.mk
-repository was created. Erlang.mk was born.</p></div>
-<div class="paragraph"><p>Little did I know how much it would grow.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_lifetime_of_the_project">Lifetime of the project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk would eventually become a much larger file able to
-deal with many more projects than just Cowboy. From the birth
-of the project, the biggest force for growth was user contributions,
-because Erlang.mk appealed to a variety of people with different
-needs, needs that Erlang.mk was not fulfilling yet.</p></div>
-<div class="paragraph"><p>The project was split into smaller files focused on a different
-feature each, and a build script was written to build the single
-Erlang.mk file.</p></div>
-<div class="paragraph"><p>A test suite was contributed by a user, and later taken as a basis
-for the current, much more complete test suite. Turns out testing
-a Makefile is pretty straightforward.</p></div>
-<div class="paragraph"><p>A package index was added to solve the problem of discovering
-Erlang projects.</p></div>
-<div class="paragraph"><p>After trying to see if Erlang build tools could cooperate, the
-decision was made to improve compatibility with existing Rebar
-projects by patching Rebar out, using Rebar. This feature, called
-autopatch, proved very successful and made Erlang.mk compatible
-with more than 90% of all Erlang projects.</p></div>
-<div class="paragraph"><p>Erlang.mk documentation was much improved and the Erlang.mk website
-was created in the summer of 2015.</p></div>
-<div class="paragraph"><p>Over the year of 2015, Erlang.mk went from curiosity to a serious
-alternative to other Erlang build tools. The user base increased
-immensely and large projects started using it, including RabbitMQ
-from the 3.6.0 release onward.</p></div>
-<div class="paragraph"><p>A bright future lies ahead.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter aims to be a brief record of the life of the +Erlang.mk project.</p></div> +<div class="sect1"> +<h2 id="_before_erlang_mk">Before Erlang.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk originates from the Cowboy project. Cowboy started +as a Rebar project and I, Loïc Hoguin, was very happy with it +for a couple years. Over time however I started getting annoyed +and frustrated by a number of things, including bad defaults, +changing defaults and overall slowness.</p></div> +<div class="paragraph"><p>In particular, at the time I gave up on Rebar, the Cowboy +test suite was taking about five minutes to run. A quick experiment +showed I could get much lower times by simply invoking <code>ct_run</code> +directly. On January 4th, 2013, the Cowboy test suite took less +than a minute to complete.</p></div> +<div class="paragraph"><p>Following this success I started removing a little more and, +on the fateful day of January 5th, 2013, removed the dependency +on Rebar entirely. Rebar, and in particular the concept of +dependencies, was, and still is, a pretty strong influence.</p></div> +<div class="paragraph"><p>Erlang.mk was conceived.</p></div> +<div class="paragraph"><p>A few months passed and, on May 1st, 2013, the Erlang.mk +repository was created. Erlang.mk was born.</p></div> +<div class="paragraph"><p>Little did I know how much it would grow.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_lifetime_of_the_project">Lifetime of the project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk would eventually become a much larger file able to +deal with many more projects than just Cowboy. From the birth +of the project, the biggest force for growth was user contributions, +because Erlang.mk appealed to a variety of people with different +needs, needs that Erlang.mk was not fulfilling yet.</p></div> +<div class="paragraph"><p>The project was split into smaller files focused on a different +feature each, and a build script was written to build the single +Erlang.mk file.</p></div> +<div class="paragraph"><p>A test suite was contributed by a user, and later taken as a basis +for the current, much more complete test suite. Turns out testing +a Makefile is pretty straightforward.</p></div> +<div class="paragraph"><p>A package index was added to solve the problem of discovering +Erlang projects.</p></div> +<div class="paragraph"><p>After trying to see if Erlang build tools could cooperate, the +decision was made to improve compatibility with existing Rebar +projects by patching Rebar out, using Rebar. This feature, called +autopatch, proved very successful and made Erlang.mk compatible +with more than 90% of all Erlang projects.</p></div> +<div class="paragraph"><p>Erlang.mk documentation was much improved and the Erlang.mk website +was created in the summer of 2015.</p></div> +<div class="paragraph"><p>Over the year of 2015, Erlang.mk went from curiosity to a serious +alternative to other Erlang build tools. The user base increased +immensely and large projects started using it, including RabbitMQ +from the 3.6.0 release onward.</p></div> +<div class="paragraph"><p>A bright future lies ahead.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/index.html b/docs/en/erlang.mk/1/guide/index.html index 5b8db024..0e1f31d0 100644 --- a/docs/en/erlang.mk/1/guide/index.html +++ b/docs/en/erlang.mk/1/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang.mk User Guide</title> @@ -67,173 +67,178 @@ <h1 class="lined-header"><span>Erlang.mk User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="installation/">Installation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="getting_started/">Getting started</a>
-</p>
-</li>
-<li>
-<p>
-<a href="overview/">Overview</a>
-</p>
-</li>
-<li>
-<p>
-<a href="updating/">Updating Erlang.mk</a>
-</p>
-</li>
-<li>
-<p>
-<a href="limitations/">Limitations</a>
-</p>
-</li>
-</ul></div>
-<div class="sect1">
-<h2 id="code">Code</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="app/">Building</a>
-</p>
-</li>
-<li>
-<p>
-<a href="deps/">Packages and dependencies</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ports/">NIFs and port drivers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="releases/">Releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="sfx/">Self-extracting releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="escripts/">Escripts</a>
-</p>
-</li>
-<li>
-<p>
-<a href="compat/">Compatibility with other build tools</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="docs">Documentation</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="asciidoc/">Asciidoc documentation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="edoc/">EDoc comments</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="tests">Tests</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="shell/">Erlang shell</a>
-</p>
-</li>
-<li>
-<p>
-<a href="eunit/">EUnit</a>
-</p>
-</li>
-<li>
-<p>
-<a href="common_test/">Common Test</a>
-</p>
-</li>
-<li>
-<p>
-<a href="coverage/">Code coverage</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ci/">Continuous integration</a>
-</p>
-</li>
-<li>
-<p>
-<a href="dialyzer/">Dialyzer</a>
-</p>
-</li>
-<li>
-<p>
-<a href="xref/">Xref</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="plugins">Third-party plugins</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="external_plugins/">External plugins</a>
-</p>
-</li>
-<li>
-<p>
-<a href="external_plugins_list/">List of plugins</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="about">About Erlang.mk</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="why/">Why erlang.mk?</a>
-</p>
-</li>
-<li>
-<p>
-<a href="history/">Short history</a>
-</p>
-</li>
-<li>
-<p>
-<a href="contributing/">Contributing</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="ulist"><ul> +<li> +<p> +<a href="installation/">Installation</a> +</p> +</li> +<li> +<p> +<a href="getting_started/">Getting started</a> +</p> +</li> +<li> +<p> +<a href="overview/">Overview</a> +</p> +</li> +<li> +<p> +<a href="updating/">Updating Erlang.mk</a> +</p> +</li> +<li> +<p> +<a href="limitations/">Limitations</a> +</p> +</li> +</ul></div> +<div class="sect1"> +<h2 id="code">Code</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="app/">Building</a> +</p> +</li> +<li> +<p> +<a href="deps/">Packages and dependencies</a> +</p> +</li> +<li> +<p> +<a href="ports/">NIFs and port drivers</a> +</p> +</li> +<li> +<p> +<a href="releases/">Releases</a> +</p> +</li> +<li> +<p> +<a href="sfx/">Self-extracting releases</a> +</p> +</li> +<li> +<p> +<a href="escripts/">Escripts</a> +</p> +</li> +<li> +<p> +<a href="kerl/">OTP version management</a> +</p> +</li> +<li> +<p> +<a href="compat/">Compatibility with other build tools</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="docs">Documentation</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="asciidoc/">Asciidoc documentation</a> +</p> +</li> +<li> +<p> +<a href="edoc/">EDoc comments</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="tests">Tests</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="shell/">Erlang shell</a> +</p> +</li> +<li> +<p> +<a href="eunit/">EUnit</a> +</p> +</li> +<li> +<p> +<a href="common_test/">Common Test</a> +</p> +</li> +<li> +<p> +<a href="coverage/">Code coverage</a> +</p> +</li> +<li> +<p> +<a href="ci/">Continuous integration</a> +</p> +</li> +<li> +<p> +<a href="dialyzer/">Dialyzer</a> +</p> +</li> +<li> +<p> +<a href="xref/">Xref</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="plugins">Third-party plugins</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="external_plugins/">External plugins</a> +</p> +</li> +<li> +<p> +<a href="external_plugins_list/">List of plugins</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="about">About Erlang.mk</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="why/">Why erlang.mk?</a> +</p> +</li> +<li> +<p> +<a href="history/">Short history</a> +</p> +</li> +<li> +<p> +<a href="contributing/">Contributing</a> +</p> +</li> +</ul></div> +</div> +</div> diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html index c909fec1..806b25e8 100644 --- a/docs/en/erlang.mk/1/guide/installation/index.html +++ b/docs/en/erlang.mk/1/guide/installation/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Installation</title> @@ -67,186 +67,189 @@ <h1 class="lined-header"><span>Installation</span></h1> -<div class="sect1">
-<h2 id="_on_unix">On Unix</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk requires GNU Make to be installed. While it will
-currently work with GNU Make 3.81, support for this version
-is deprecated and will be removed in 2017. We recommend
-GNU Make 4.1 or later.</p></div>
-<div class="paragraph"><p>Git and Erlang/OTP must also be installed.</p></div>
-<div class="paragraph"><p>Some functionality requires that Autoconf 2.59 or later be
-installed, in order to compile Erlang/OTP. Erlang/OTP may
-have further requirements depending on your needs.</p></div>
-<div class="paragraph"><p>Some packages may require additional libraries.</p></div>
-<div class="sect3">
-<h4 id="_linux">Linux</h4>
-<div class="paragraph"><p>The commands to install packages vary between distributions:</p></div>
-<div class="listingblock">
-<div class="title">Arch Linux</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>$ pacman -S erlang git make</tt></pre></div></div>
-</div>
-<div class="sect3">
-<h4 id="_freebsd">FreeBSD</h4>
-<div class="paragraph"><p>FreeBSD comes with binary and source packages:</p></div>
-<div class="listingblock">
-<div class="title">Install binary packages</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>$ pkg install erlang git gmake</tt></pre></div></div>
-<div class="paragraph"><p>On FreeBSD the <code>make</code> command is BSD Make. Use <code>gmake</code> instead.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_os_x_and_macos">OS X and macOS</h4>
-<div class="paragraph"><p>While Apple distributes their own GNU Make, their version is
-very old and plagued with numerous bugs. It is recommended
-to install a more recent version from either Homebrew or
-MacPorts:</p></div>
-<div class="listingblock">
-<div class="title">Homebrew</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>$ brew install erlang git homebrew/dupes/make</tt></pre></div></div>
-<div class="paragraph"><p>Homebrew installs GNU Make as <code>gmake</code>. The <code>make</code> command
-is the one provided by Apple.</p></div>
-<div class="listingblock">
-<div class="title">MacPorts</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>$ sudo port install erlang git gmake</tt></pre></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_on_windows">On Windows</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk can be used on Windows inside an MSYS2 environment.
-Cygwin, MSYS (the original) and native Windows (both Batch
-and PowerShell) are currently not supported.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">Erlang.mk expects Unix line breaks in most of the files
-(LF instead of CRLF). Make sure to configure your text editor
-adequately.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>The rest of this section details how to setup Erlang/OTP and
-MSYS2 in order to use Erlang.mk.</p></div>
-<div class="sect3">
-<h4 id="_installing_erlang_otp">Installing Erlang/OTP</h4>
-<div class="paragraph"><p>Erlang.mk requires Erlang/OTP to be installed. The OTP team
-provides binaries of Erlang/OTP for all major and minor releases,
-available from the <a href="http://www.erlang.org/download.html">official download page</a>.
-It is recommended that you use the 64-bit installer unless
-technically impossible. Please follow the instructions from
-the installer to complete the installation.</p></div>
-<div class="paragraph"><p>The OTP team also provides a short guide to
-<a href="http://www.erlang.org/download.html">installing Erlang/OTP on Windows</a>
-if you need additional references.</p></div>
-<div class="paragraph"><p>You can install Erlang/OTP silently using the <code>/S</code> switch
-on the command line:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\Users\essen\Downloads> otp_win64_18.0.exe /S</code></pre>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="_installing_msys2">Installing MSYS2</h4>
-<div class="paragraph"><p>The only supported environment on Windows is MSYS2. MSYS2 is
-a lightweight Unix-like environment for Windows that comes
-with the Arch Linux package manager, <code>pacman</code>.</p></div>
-<div class="paragraph"><p>The MSYS2 project provides a <a href="http://msys2.github.io">one click installer</a>
-and instructions to set things up post-installation.</p></div>
-<div class="paragraph"><p>It is currently not possible to use the installer silently.
-Thankfully, the MSYS2 project provides an archive that can
-be used in lieu of the installer. The archive however requires
-<em>7zip</em> to decompress it.</p></div>
-<div class="paragraph"><p>First, download the
-<a href="http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download">MSYS2 base archive</a>
-and extract it under <em>C:\</em>. Assuming you downloaded the
-archive as <em>msys2.tar.xz</em> and put it in <em>C:\</em>, you can
-use the following commands to extract it:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> 7z x msys2.tar.xz
-C:\> 7z x msys2.tar > NUL</code></pre>
-</div></div>
-<div class="paragraph"><p>Then you can run the two commands needed to perform the
-post-installation setup:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime"
-C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"</code></pre>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="_installing_the_required_msys2_packages">Installing the required MSYS2 packages</h4>
-<div class="paragraph"><p>After following these instructions, you can install GNU Make,
-Git and any other required softwares. From an MSYS2 shell,
-you can call <code>pacman</code> directly:</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>$ pacman -S git make</tt></pre></div></div>
-<div class="paragraph"><p>You can use <code>pacman -Ss</code> to search packages. For example,
-to find all packages related to GCC:</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>$ pacman -Ss gcc</tt></pre></div></div>
-<div class="paragraph"><p>If you are going to compile C/C++ code, you will need to
-install this package, as Erlang.mk cannot use the normal
-"gcc" package:</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>$ pacman -S mingw-w<span style="color: #993399">64</span>-x86_64-gcc</tt></pre></div></div>
-<div class="paragraph"><p>You can also run commands under the MSYS2 environment from
-the Windows command line or batch files. This command will
-install GNU Make and Git:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"</code></pre>
-</div></div>
-<div class="paragraph"><p>You can use similar <code>bash</code> commands if you need to run programs
-inside the MSYS2 environment from a batch file.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_gotchas">Gotchas</h4>
-<div class="paragraph"><p>While most of the basic functionality will just work, there are
-still some issues. Erlang.mk needs to be fixed to pass the
-right paths when running Erlang scripts. We are working on it.
-Erlang.mk is fully tested on both Linux and Windows, but is
-lacking tests in the areas not yet covered by this guide,
-so expect bugs to be fixed as more tests are added.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_on_unix">On Unix</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk requires GNU Make to be installed. While it will +currently work with GNU Make 3.81, support for this version +is deprecated and will be removed in 2017. We recommend +GNU Make 4.1 or later.</p></div> +<div class="paragraph"><p>Git and Erlang/OTP must also be installed.</p></div> +<div class="paragraph"><p>Some functionality requires that Autoconf 2.59 or later be +installed, in order to compile Erlang/OTP. Erlang/OTP may +have further requirements depending on your needs.</p></div> +<div class="paragraph"><p>Some packages may require additional libraries.</p></div> +<div class="sect3"> +<h4 id="_linux">Linux</h4> +<div class="paragraph"><p>The commands to install packages vary between distributions:</p></div> +<div class="listingblock"> +<div class="title">Arch Linux</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>$ pacman -S erlang git make</tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_freebsd">FreeBSD</h4> +<div class="paragraph"><p>FreeBSD comes with binary and source packages:</p></div> +<div class="listingblock"> +<div class="title">Install binary packages</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>$ pkg install erlang git gmake</tt></pre></div></div> +<div class="paragraph"><p>On FreeBSD the <code>make</code> command is BSD Make. Use <code>gmake</code> instead.</p></div> +</div> +<div class="sect3"> +<h4 id="_os_x_and_macos">OS X and macOS</h4> +<div class="paragraph"><p>While Apple distributes their own GNU Make, their version is +very old and plagued with numerous bugs. It is recommended +to install a more recent version from either Homebrew or +MacPorts:</p></div> +<div class="listingblock"> +<div class="title">Homebrew</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>$ brew install erlang git homebrew/dupes/make</tt></pre></div></div> +<div class="paragraph"><p>Homebrew installs GNU Make as <code>gmake</code>. The <code>make</code> command +is the one provided by Apple.</p></div> +<div class="listingblock"> +<div class="title">MacPorts</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>$ sudo port install erlang git gmake</tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_on_windows">On Windows</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can be used on Windows inside an MSYS2 environment. +Cygwin, MSYS (the original) and native Windows (both Batch +and PowerShell) are currently not supported.</p></div> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content">Erlang.mk expects Unix line breaks in most of the files +(LF instead of CRLF). Make sure to configure your text editor +adequately.</td> +</tr></table> +</div> +<div class="paragraph"><p>The rest of this section details how to setup Erlang/OTP and +MSYS2 in order to use Erlang.mk.</p></div> +<div class="sect3"> +<h4 id="_installing_erlang_otp">Installing Erlang/OTP</h4> +<div class="paragraph"><p>Erlang.mk requires Erlang/OTP to be installed. The OTP team +provides binaries of Erlang/OTP for all major and minor releases, +available from the <a href="http://www.erlang.org/download.html">official download page</a>. +It is recommended that you use the 64-bit installer unless +technically impossible. Please follow the instructions from +the installer to complete the installation.</p></div> +<div class="paragraph"><p>The OTP team also provides a short guide to +<a href="http://www.erlang.org/download.html">installing Erlang/OTP on Windows</a> +if you need additional references.</p></div> +<div class="paragraph"><p>You can install Erlang/OTP silently using the <code>/S</code> switch +on the command line:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\Users\essen\Downloads> otp_win64_18.0.exe /S</code></pre> +</div></div> +</div> +<div class="sect3"> +<h4 id="_installing_msys2">Installing MSYS2</h4> +<div class="paragraph"><p>The only supported environment on Windows is MSYS2. MSYS2 is +a lightweight Unix-like environment for Windows that comes +with the Arch Linux package manager, <code>pacman</code>.</p></div> +<div class="paragraph"><p>The MSYS2 project provides a <a href="http://msys2.github.io">one click installer</a> +and instructions to set things up post-installation.</p></div> +<div class="paragraph"><p>It is currently not possible to use the installer silently. +Thankfully, the MSYS2 project provides an archive that can +be used in lieu of the installer. The archive however requires +<em>7zip</em> to decompress it.</p></div> +<div class="paragraph"><p>First, download the +<a href="http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download">MSYS2 base archive</a> +and extract it under <em>C:\</em>. Assuming you downloaded the +archive as <em>msys2.tar.xz</em> and put it in <em>C:\</em>, you can +use the following commands to extract it:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> 7z x msys2.tar.xz +C:\> 7z x msys2.tar > NUL</code></pre> +</div></div> +<div class="paragraph"><p>Then you can run the two commands needed to perform the +post-installation setup:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime" +C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"</code></pre> +</div></div> +</div> +<div class="sect3"> +<h4 id="_installing_the_required_msys2_packages">Installing the required MSYS2 packages</h4> +<div class="paragraph"><p>After following these instructions, you can install GNU Make, +Git and any other required softwares. From an MSYS2 shell, +you can call <code>pacman</code> directly:</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>$ pacman -S git make</tt></pre></div></div> +<div class="paragraph"><p>You can use <code>pacman -Ss</code> to search packages. For example, +to find all packages related to GCC:</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>$ pacman -Ss gcc</tt></pre></div></div> +<div class="paragraph"><p>If you are going to compile C/C++ code, you will need to +install this package, as Erlang.mk cannot use the normal +"gcc" package:</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>$ pacman -S mingw-w<span style="color: #993399">64</span>-x86_64-gcc</tt></pre></div></div> +<div class="paragraph"><p>You can also run commands under the MSYS2 environment from +the Windows command line or batch files. This command will +install GNU Make and Git:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"</code></pre> +</div></div> +<div class="paragraph"><p>You can use similar <code>bash</code> commands if you need to run programs +inside the MSYS2 environment from a batch file.</p></div> +</div> +<div class="sect3"> +<h4 id="_gotchas">Gotchas</h4> +<div class="paragraph"><p>While most of the basic functionality will just work, there are +still some issues. Erlang.mk needs to be fixed to pass the +right paths when running Erlang scripts. We are working on it. +Erlang.mk is fully tested on both Linux and Windows, but is +lacking tests in the areas not yet covered by this guide, +so expect bugs to be fixed as more tests are added.</p></div> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/kerl.asciidoc b/docs/en/erlang.mk/1/guide/kerl.asciidoc new file mode 100644 index 00000000..c557d432 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/kerl.asciidoc @@ -0,0 +1,76 @@ +[[kerl]] +== OTP version management + +Erlang.mk comes with integrated support for +https://github.com/kerl/kerl[Kerl], a shell script that +automates the downloading, building and installing of +Erlang/OTP. It can be used to easily build a specific +Erlang/OTP version (with or without custom build options) +or maintain different versions side by side. + +=== Erlang versions + +Erlang.mk uses the Git tags from Erlang/OTP to identify +OTP versions. The most recent tag at the time of writing +is `OTP-20.0.4`, which is a patch release of `OTP-20.0`. +A patch release is a non-official release containing a +few fixes on top of the official release. + +Older versions used a slightly different versioning scheme +and tag format, for example: `OTP_R16B03`. Beware though, +there also was an `OTP_R16B03-1` release that fixed a +critical issue in the initial release. + +The README file for all official Erlang/OTP releases can +be found on http://www.erlang.org/downloads[erlang.org]. +To obtain information about patch releases when they are +released you need to be subscribed to the +http://erlang.org/mailman/listinfo/erlang-questions[erlang-questions mailing list]. + +[[otp_version_pinning]] +=== OTP version pinning + +Erlang.mk can use a specific version of Erlang/OTP when +interacting with your project. This can be very useful +when you are working with a team because you can define +the version you need in the Makefile and Erlang.mk will +ensure this version is used by everyone in your team. + +To pin the version all you need to do is to set the +`ERLANG_OTP` variable in your Makefile before including +Erlang.mk. For example, to use `OTP-20.0.4`: + +[source,make] +---- +ERLANG_OTP = OTP-20.0.4 + +include erlang.mk +---- + +The next time you run `make` Erlang.mk will build and +use the version you configured. + +Note that there has been reports that this functionality +is not compatible with the `.ONESHELL` feature from +GNU Make. + +=== Continuous integration + +Erlang.mk can automatically test your project against +many different Erlang/OTP versions. This functionality +is documented in the xref:ci[Continuous integration] chapter. + +=== Configuring Kerl + +All of the Kerl variables can be configured directly in the +Makefile. All you need to do is to export them. For example, +to change the installation directory for the Erlang/OTP +versions managed by Kerl, you could add the following to +your Makefile: + +[source,make] +export KERL_INSTALL_DIR = $(CURDIR)/erlang + +When configuring paths like this, always make sure to provide +an absolute path in the value. Erlang.mk will NOT expand them +automatically for you. diff --git a/docs/en/erlang.mk/1/guide/kerl/index.html b/docs/en/erlang.mk/1/guide/kerl/index.html new file mode 100644 index 00000000..d5474929 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/kerl/index.html @@ -0,0 +1,233 @@ +<!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.26" /> + + <title>Nine Nines: OTP version management</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>OTP version management</span></h1> + +<div class="paragraph"><p>Erlang.mk comes with integrated support for +<a href="https://github.com/kerl/kerl">Kerl</a>, a shell script that +automates the downloading, building and installing of +Erlang/OTP. It can be used to easily build a specific +Erlang/OTP version (with or without custom build options) +or maintain different versions side by side.</p></div> +<div class="sect1"> +<h2 id="_erlang_versions">Erlang versions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk uses the Git tags from Erlang/OTP to identify +OTP versions. The most recent tag at the time of writing +is <code>OTP-20.0.4</code>, which is a patch release of <code>OTP-20.0</code>. +A patch release is a non-official release containing a +few fixes on top of the official release.</p></div> +<div class="paragraph"><p>Older versions used a slightly different versioning scheme +and tag format, for example: <code>OTP_R16B03</code>. Beware though, +there also was an <code>OTP_R16B03-1</code> release that fixed a +critical issue in the initial release.</p></div> +<div class="paragraph"><p>The README file for all official Erlang/OTP releases can +be found on <a href="http://www.erlang.org/downloads">erlang.org</a>. +To obtain information about patch releases when they are +released you need to be subscribed to the +<a href="http://erlang.org/mailman/listinfo/erlang-questions">erlang-questions mailing list</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="otp_version_pinning">OTP version pinning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can use a specific version of Erlang/OTP when +interacting with your project. This can be very useful +when you are working with a team because you can define +the version you need in the Makefile and Erlang.mk will +ensure this version is used by everyone in your team.</p></div> +<div class="paragraph"><p>To pin the version all you need to do is to set the +<code>ERLANG_OTP</code> variable in your Makefile before including +Erlang.mk. For example, to use <code>OTP-20.0.4</code>:</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="color: #009900">ERLANG_OTP =</span> OTP-20.0.4 + +include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>The next time you run <code>make</code> Erlang.mk will build and +use the version you configured.</p></div> +<div class="paragraph"><p>Note that there has been reports that this functionality +is not compatible with the <code>.ONESHELL</code> feature from +GNU Make.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_continuous_integration">Continuous integration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can automatically test your project against +many different Erlang/OTP versions. This functionality +is documented in the <a href="../ci">Continuous integration</a> chapter.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuring_kerl">Configuring Kerl</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of the Kerl variables can be configured directly in the +Makefile. All you need to do is to export them. For example, +to change the installation directory for the Erlang/OTP +versions managed by Kerl, you could add the following to +your Makefile:</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">export</span></span> KERL_INSTALL_DIR <span style="color: #990000">=</span> <span style="color: #009900">$(CURDIR)</span>/erlang</tt></pre></div></div> +<div class="paragraph"><p>When configuring paths like this, always make sure to provide +an absolute path in the value. Erlang.mk will NOT expand them +automatically for you.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/"> + Escripts + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/"> + Compatibility with other build tools + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Erlang.mk + 1 + + User Guide +</h3> + +<ul> + + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/erlang.mk/1/guide">1</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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/erlang.mk/1/guide/limitations/index.html b/docs/en/erlang.mk/1/guide/limitations/index.html index abf19700..48561e8f 100644 --- a/docs/en/erlang.mk/1/guide/limitations/index.html +++ b/docs/en/erlang.mk/1/guide/limitations/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Limitations</title> @@ -67,55 +67,58 @@ <h1 class="lined-header"><span>Limitations</span></h1> -<div class="paragraph"><p>No software is perfect.</p></div>
-<div class="paragraph"><p>It’s very important, when evaluating and when using a tool,
-to understand its limitations, so as to avoid making mistakes
-and wasting valuable time.</p></div>
-<div class="paragraph"><p>This chapter lists all known limitations of Erlang.mk.</p></div>
-<div class="sect1">
-<h2 id="_erlang_must_be_available">Erlang must be available</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Currently Erlang.mk requires you to install Erlang beforehand.
-Installing Erlang is not always easy, particularly if you need
-a specific version of Erlang for a specific project.</p></div>
-<div class="paragraph"><p>In addition, the Erlang being used must be in your <code>$PATH</code>
-before you use Erlang.mk.</p></div>
-<div class="paragraph"><p>In the future we envision, Erlang.mk could manage the Erlang
-version you need to use a project. Erlang.mk already does this
-for running tests when using <code>make ci</code>, so doing this during
-development is just a step away.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_spaces_in_path">Spaces in path</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will currently not work properly if the path to the
-project contains spaces. To check if that is the case, use the
-command <code>pwd</code>.</p></div>
-<div class="paragraph"><p>This issue is due to how Makefiles work. There might be ways
-to solve it, we have not given up on it, but it’s very low
-priority considering how simple the workaround is.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependency_tracking_and_modification_times">Dependency tracking and modification times</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang source files that depend on other files will have their
-modification time updated when they need to be recompiled due
-to a dependency having changed. This could cause some editors to
-think the file changed when it didn’t.</p></div>
-<div class="paragraph"><p>Erlang.mk must use this method in order to be able to compile
-files in one <code>erlc</code> invocation. The benefits greatly outweigh
-the issue in this case and so there are currently no plans to
-fix this behavior.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>No software is perfect.</p></div> +<div class="paragraph"><p>It’s very important, when evaluating and when using a tool, +to understand its limitations, so as to avoid making mistakes +and wasting valuable time.</p></div> +<div class="paragraph"><p>This chapter lists all known limitations of Erlang.mk.</p></div> +<div class="sect1"> +<h2 id="_erlang_must_be_available">Erlang must be available</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Currently Erlang.mk requires you to install Erlang beforehand. +Installing Erlang is not always easy, particularly if you need +a specific version of Erlang for a specific project.</p></div> +<div class="paragraph"><p>In addition, the Erlang being used must be in your <code>$PATH</code> +before you use Erlang.mk.</p></div> +<div class="paragraph"><p>In the future we envision, Erlang.mk could manage the Erlang +version you need to use a project. Erlang.mk already does this +for running tests when using <code>make ci</code>, so doing this during +development is just a step away.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_spaces_in_path">Spaces in path</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will currently not work properly if the path to the +project contains spaces. To check if that is the case, use the +command <code>pwd</code>.</p></div> +<div class="paragraph"><p>This issue is due to how Makefiles work. There might be ways +to solve it, we have not given up on it, but it’s very low +priority considering how simple the workaround is.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependency_tracking_and_modification_times">Dependency tracking and modification times</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang source files that depend on other files will have their +modification time updated when they need to be recompiled due +to a dependency having changed. This could cause some editors to +think the file changed when it didn’t.</p></div> +<div class="paragraph"><p>Erlang.mk must use this method in order to be able to compile +files in one <code>erlc</code> invocation. The benefits greatly outweigh +the issue in this case and so there are currently no plans to +fix this behavior.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/overview/index.html b/docs/en/erlang.mk/1/guide/overview/index.html index 5c072e64..2a6cbf1f 100644 --- a/docs/en/erlang.mk/1/guide/overview/index.html +++ b/docs/en/erlang.mk/1/guide/overview/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Overview</title> @@ -67,100 +67,103 @@ <h1 class="lined-header"><span>Overview</span></h1> -<div class="paragraph"><p>Now that you know how to get started, let’s take a look at
-what Erlang.mk can do for you.</p></div>
-<div class="sect1">
-<h2 id="_building_your_project">Building your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is first and foremost a build tool. It is especially
-tailored for Erlang developers and follows widely accepted
-practices in the Erlang community.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily build all <a href="../building">Erlang-specific files</a>
-you throw at it. Other kinds of files too, like C or C++ code
-when you are working on <a href="../ports">a NIF or a port driver</a>.</p></div>
-<div class="paragraph"><p>Erlang.mk embraces the concept of <a href="../deps">source dependencies</a>.
-It can fetch dependency source code using a variety of mechanisms,
-including fetching from Git, Mercurial or SVN.</p></div>
-<div class="paragraph"><p>Erlang.mk will automatically <a href="../relx">generate releases</a>
-when applicable. It can also <a href="../escript">generate escripts</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exploring_the_package_index">Exploring the package index</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk comes with a <a href="../deps">built-in package index</a>.
-It is built as an extension of the dependency system and is
-meant to be used for discovery purposes.</p></div>
-<div class="paragraph"><p>No package is ever installed, they are only used as dependencies
-and are always project-specific. They can be thought of as a
-shortcut over plain dependencies.</p></div>
-<div class="paragraph"><p>You can get a list of all packages known to Erlang.mk by using
-the <code>search</code> target:</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>$ make search</tt></pre></div></div>
-<div class="paragraph"><p>You can also use this target to search across all packages, for
-example to find all packages related to Cowboy:</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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>cowboy</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_documentation">Generating documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports <em>EDoc</em> and <em>Asciidoc</em>.</p></div>
-<div class="paragraph"><p><a href="../edoc">EDoc</a> generates HTML documentation directly from
-your source code.</p></div>
-<div class="paragraph"><p>While it is convenient, ask yourself: if all the documentation is
-inside the source code, why not just open the source code directly?
-That’s where <em>Asciidoc</em> comes in.</p></div>
-<div class="paragraph"><p>The <a href="../asciidoc">Asciidoc</a> plugin expects all documentation
-to be separate from source. It will generate HTML, PDF, man pages and
-more from the documentation you write in the <em>doc/src/</em> folder in
-your repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_tests">Running tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports a lot of different testing and static
-analysis tools.</p></div>
-<div class="paragraph"><p>The <a href="../shell">make shell</a> command allows you
-to test your project manually. You can automate these
-unit tests with <a href="../eunit">EUnit</a> and test
-your entire system with <a href="../ct">Common Test</a>.
-<a href="../coverage">Code coverage</a> can of course
-be enabled during tests.</p></div>
-<div class="paragraph"><p>Erlang.mk comes with features to make your life easier when
-setting up and using <a href="../ci">Continuous integration</a>.</p></div>
-<div class="paragraph"><p>On the static analysis side of things, Erlang.mk comes with
-support for <a href="../dialyzer">Dialyzer</a> and <a href="#xref">Xref</a>,
-to perform success typing analysis and cross referencing
-of the code.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_need_more">Need more?</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Not convinced yet? You can read about <a href="../why">why you should use Erlang.mk</a>
-and its <a href="../history">history</a>. And if you’re still not
-convinced after that, it’s OK! The world would be boring if
-everyone agreed on everything all the time.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Now that you know how to get started, let’s take a look at +what Erlang.mk can do for you.</p></div> +<div class="sect1"> +<h2 id="_building_your_project">Building your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is first and foremost a build tool. It is especially +tailored for Erlang developers and follows widely accepted +practices in the Erlang community.</p></div> +<div class="paragraph"><p>Erlang.mk will happily build all <a href="../building">Erlang-specific files</a> +you throw at it. Other kinds of files too, like C or C++ code +when you are working on <a href="../ports">a NIF or a port driver</a>.</p></div> +<div class="paragraph"><p>Erlang.mk embraces the concept of <a href="../deps">source dependencies</a>. +It can fetch dependency source code using a variety of mechanisms, +including fetching from Git, Mercurial or SVN.</p></div> +<div class="paragraph"><p>Erlang.mk will automatically <a href="../relx">generate releases</a> +when applicable. It can also <a href="../escript">generate escripts</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exploring_the_package_index">Exploring the package index</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk comes with a <a href="../deps">built-in package index</a>. +It is built as an extension of the dependency system and is +meant to be used for discovery purposes.</p></div> +<div class="paragraph"><p>No package is ever installed, they are only used as dependencies +and are always project-specific. They can be thought of as a +shortcut over plain dependencies.</p></div> +<div class="paragraph"><p>You can get a list of all packages known to Erlang.mk by using +the <code>search</code> target:</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>$ make search</tt></pre></div></div> +<div class="paragraph"><p>You can also use this target to search across all packages, for +example to find all packages related to Cowboy:</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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>cowboy</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_documentation">Generating documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports <em>EDoc</em> and <em>Asciidoc</em>.</p></div> +<div class="paragraph"><p><a href="../edoc">EDoc</a> generates HTML documentation directly from +your source code.</p></div> +<div class="paragraph"><p>While it is convenient, ask yourself: if all the documentation is +inside the source code, why not just open the source code directly? +That’s where <em>Asciidoc</em> comes in.</p></div> +<div class="paragraph"><p>The <a href="../asciidoc">Asciidoc</a> plugin expects all documentation +to be separate from source. It will generate HTML, PDF, man pages and +more from the documentation you write in the <em>doc/src/</em> folder in +your repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_tests">Running tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports a lot of different testing and static +analysis tools.</p></div> +<div class="paragraph"><p>The <a href="../shell">make shell</a> command allows you +to test your project manually. You can automate these +unit tests with <a href="../eunit">EUnit</a> and test +your entire system with <a href="../ct">Common Test</a>. +<a href="../coverage">Code coverage</a> can of course +be enabled during tests.</p></div> +<div class="paragraph"><p>Erlang.mk comes with features to make your life easier when +setting up and using <a href="../ci">Continuous integration</a>.</p></div> +<div class="paragraph"><p>On the static analysis side of things, Erlang.mk comes with +support for <a href="../dialyzer">Dialyzer</a> and <a href="#xref">Xref</a>, +to perform success typing analysis and cross referencing +of the code.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_need_more">Need more?</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Not convinced yet? You can read about <a href="../why">why you should use Erlang.mk</a> +and its <a href="../history">history</a>. And if you’re still not +convinced after that, it’s OK! The world would be boring if +everyone agreed on everything all the time.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/ports.asciidoc b/docs/en/erlang.mk/1/guide/ports.asciidoc index 02c636fd..907ee366 100644 --- a/docs/en/erlang.mk/1/guide/ports.asciidoc +++ b/docs/en/erlang.mk/1/guide/ports.asciidoc @@ -98,3 +98,37 @@ The source files are automatically gathered from the contents of '$(C_SRC_DIR)'. Erlang.mk looks for '.c', '.C', '.cc' and '.cpp' source files. You can define the variable `SOURCES` to manually list the files to compile. + +=== Propagating compile and linker flags to sub-Makefiles + +In some cases it might be necessary to propagate the flags +you just defined to the sub-Makefiles of your local project. +You generally can't just export those as this could impact +the building of dependencies. + +Makefiles allow you to export variables for specific targets. +When doing this, the variables will be exported only when +this target runs, and not for other targets. It is therefore +possible to export them when building the C code without +impacting other build steps. + +By adding this to your Makefile all five variables will be +made available to sub-Makefiles when building C code: + +[source,make] +---- +app-c_src: export CC += +app-c_src: export CFLAGS += +app-c_src: export CPPFLAGS += +app-c_src: export LDFLAGS += +app-c_src: export LDLIBS += +---- + +Appending an empty string to the existing value is necessary +because Makefiles expect an assignment for target-specific +exports. Alternatively you can set a new value: + +[source,make] +---- +app-c_src: export CFLAGS = -O3 +---- diff --git a/docs/en/erlang.mk/1/guide/ports/index.html b/docs/en/erlang.mk/1/guide/ports/index.html index 619cfb40..24fa8b15 100644 --- a/docs/en/erlang.mk/1/guide/ports/index.html +++ b/docs/en/erlang.mk/1/guide/ports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: NIFs and port drivers</title> @@ -67,148 +67,202 @@ <h1 class="lined-header"><span>NIFs and port drivers</span></h1> -<div class="paragraph"><p>Erlang.mk can not only build Erlang projects, but also the C code
-that some projects come with, like NIFs and port drivers.</p></div>
-<div class="paragraph"><p>There are two ways to build the C code: using a custom Makefile,
-or making Erlang.mk do it directly. The C code will be built
-as needed when you run <code>make</code>.</p></div>
-<div class="sect1">
-<h2 id="_c_source_code_location_and_erlang_environment">C source code location and Erlang environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The C source code should be located in the <em>$(C_SRC_DIR)</em> directory.
-It defaults to <em>c_src/</em>. Should you need to modify it, all you
-need to do is to set the variable in your Makefile before including
-Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>When this directory exists, Erlang.mk will automatically create a
-file named <em>$(C_SRC_ENV)</em>. This file defaults to <em>$(C_SRC_DIR)/env.mk</em>.
-This can also be changed:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>It contains a few variable definitions for the environment used for the build:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>ERTS_INCLUDE_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the ERTS include files (<em>erl_driver.h</em>, <em>erl_nif.h</em> and more).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ERL_INTERFACE_INCLUDE_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the Erl_Interface include files (<em>ei.h</em> and related).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ERL_INTERFACE_LIB_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the Erl_Interface static libraries.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_custom_makefile">Using a custom Makefile</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will automatically run <code>make</code> if it detects a Makefile
-in <em>$(C_SRC_DIR)/Makefile</em>.</p></div>
-<div class="paragraph"><p>The Makefile should have at least two targets: a default target
-(which can be anything, for example <code>all</code>) which is invoked when
-building the C code, and a <code>clean</code> target invoked when cleaning
-it.</p></div>
-<div class="paragraph"><p>You can include the <em>env.mk</em> file to benefit from the Erlang
-environment detection:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_erlang_mk_directly">Using Erlang.mk directly</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You don’t need to write a Makefile to build C source code, however.
-Erlang.mk comes with rules to build both shared libraries and
-executables, using the source files it finds in <em>$(C_SRC_DIR)</em>.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will create a shared library. To change
-this and create an executable instead, put this in your Makefile
-before including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The generated file name varies depending on the type of project
-you have (shared library or executable) and on the platform you
-build the project on.</p></div>
-<div class="paragraph"><p>For shared libraries, the generated file name will be
-<em>$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)</em>, with the default
-being <em>$(CURDIR)/priv/$(PROJECT)</em> followed by the extension:
-<code>.dll</code> on Windows, <code>.so</code> everywhere else.</p></div>
-<div class="paragraph"><p>For executables, the generated file name is
-<em>$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)</em>, with the same
-default except for the extension: <code>.exe</code> on Windows, and otherwise
-nothing.</p></div>
-<div class="paragraph"><p>Erlang.mk sets appropriate compile and linker flags by default.
-These flags vary depending on the platform, and can of course
-be overriden.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>CC</code>
-</dt>
-<dd>
-<p>
- The compiler to be used.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>CFLAGS</code>
-</dt>
-<dd>
-<p>
- C compiler flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>CXXFLAGS</code>
-</dt>
-<dd>
-<p>
- C++ compiler flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LDFLAGS</code>
-</dt>
-<dd>
-<p>
- Linker flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LDLIBS</code>
-</dt>
-<dd>
-<p>
- Libraries to link against.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The source files are automatically gathered from the contents
-of <em>$(C_SRC_DIR)</em>. Erlang.mk looks for <em>.c</em>, <em>.C</em>, <em>.cc</em> and <em>.cpp</em>
-source files. You can define the variable <code>SOURCES</code> to manually
-list the files to compile.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can not only build Erlang projects, but also the C code +that some projects come with, like NIFs and port drivers.</p></div> +<div class="paragraph"><p>There are two ways to build the C code: using a custom Makefile, +or making Erlang.mk do it directly. The C code will be built +as needed when you run <code>make</code>.</p></div> +<div class="sect1"> +<h2 id="_c_source_code_location_and_erlang_environment">C source code location and Erlang environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The C source code should be located in the <em>$(C_SRC_DIR)</em> directory. +It defaults to <em>c_src/</em>. Should you need to modify it, all you +need to do is to set the variable in your Makefile before including +Erlang.mk:</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="color: #009900">C_SRC_DIR =</span> <span style="color: #009900">$(CURDIR)</span>/my_nif_source</tt></pre></div></div> +<div class="paragraph"><p>When this directory exists, Erlang.mk will automatically create a +file named <em>$(C_SRC_ENV)</em>. This file defaults to <em>$(C_SRC_DIR)/env.mk</em>. +This can also be changed:</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="color: #009900">C_SRC_ENV =</span> <span style="color: #009900">$(C_SRC_DIR)</span>/erlang_env.mk</tt></pre></div></div> +<div class="paragraph"><p>It contains a few variable definitions for the environment used for the build:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>ERTS_INCLUDE_DIR</code> +</dt> +<dd> +<p> + Path to the ERTS include files (<em>erl_driver.h</em>, <em>erl_nif.h</em> and more). +</p> +</dd> +<dt class="hdlist1"> +<code>ERL_INTERFACE_INCLUDE_DIR</code> +</dt> +<dd> +<p> + Path to the Erl_Interface include files (<em>ei.h</em> and related). +</p> +</dd> +<dt class="hdlist1"> +<code>ERL_INTERFACE_LIB_DIR</code> +</dt> +<dd> +<p> + Path to the Erl_Interface static libraries. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_custom_makefile">Using a custom Makefile</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will automatically run <code>make</code> if it detects a Makefile +in <em>$(C_SRC_DIR)/Makefile</em>.</p></div> +<div class="paragraph"><p>The Makefile should have at least two targets: a default target +(which can be anything, for example <code>all</code>) which is invoked when +building the C code, and a <code>clean</code> target invoked when cleaning +it.</p></div> +<div class="paragraph"><p>You can include the <em>env.mk</em> file to benefit from the Erlang +environment detection:</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>include env.mk</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_erlang_mk_directly">Using Erlang.mk directly</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You don’t need to write a Makefile to build C source code, however. +Erlang.mk comes with rules to build both shared libraries and +executables, using the source files it finds in <em>$(C_SRC_DIR)</em>.</p></div> +<div class="paragraph"><p>By default, Erlang.mk will create a shared library. To change +this and create an executable instead, put this in your Makefile +before including Erlang.mk:</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="color: #009900">C_SRC_TYPE =</span> executable</tt></pre></div></div> +<div class="paragraph"><p>The generated file name varies depending on the type of project +you have (shared library or executable) and on the platform you +build the project on.</p></div> +<div class="paragraph"><p>For shared libraries, the generated file name will be +<em>$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)</em>, with the default +being <em>$(CURDIR)/priv/$(PROJECT)</em> followed by the extension: +<code>.dll</code> on Windows, <code>.so</code> everywhere else.</p></div> +<div class="paragraph"><p>For executables, the generated file name is +<em>$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)</em>, with the same +default except for the extension: <code>.exe</code> on Windows, and otherwise +nothing.</p></div> +<div class="paragraph"><p>Erlang.mk sets appropriate compile and linker flags by default. +These flags vary depending on the platform, and can of course +be overriden.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>CC</code> +</dt> +<dd> +<p> + The compiler to be used. +</p> +</dd> +<dt class="hdlist1"> +<code>CFLAGS</code> +</dt> +<dd> +<p> + C compiler flags. +</p> +</dd> +<dt class="hdlist1"> +<code>CXXFLAGS</code> +</dt> +<dd> +<p> + C++ compiler flags. +</p> +</dd> +<dt class="hdlist1"> +<code>LDFLAGS</code> +</dt> +<dd> +<p> + Linker flags. +</p> +</dd> +<dt class="hdlist1"> +<code>LDLIBS</code> +</dt> +<dd> +<p> + Libraries to link against. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>The source files are automatically gathered from the contents +of <em>$(C_SRC_DIR)</em>. Erlang.mk looks for <em>.c</em>, <em>.C</em>, <em>.cc</em> and <em>.cpp</em> +source files. You can define the variable <code>SOURCES</code> to manually +list the files to compile.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_propagating_compile_and_linker_flags_to_sub_makefiles">Propagating compile and linker flags to sub-Makefiles</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In some cases it might be necessary to propagate the flags +you just defined to the sub-Makefiles of your local project. +You generally can’t just export those as this could impact +the building of dependencies.</p></div> +<div class="paragraph"><p>Makefiles allow you to export variables for specific targets. +When doing this, the variables will be exported only when +this target runs, and not for other targets. It is therefore +possible to export them when building the C code without +impacting other build steps.</p></div> +<div class="paragraph"><p>By adding this to your Makefile all five variables will be +made available to sub-Makefiles when building C code:</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="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CC <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CPPFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> LDFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> LDLIBS <span style="color: #990000">+=</span></tt></pre></div></div> +<div class="paragraph"><p>Appending an empty string to the existing value is necessary +because Makefiles expect an assignment for target-specific +exports. Alternatively you can set a new value:</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="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CFLAGS <span style="color: #990000">=</span> -O<span style="color: #993399">3</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html index e3c46057..606c47e3 100644 --- a/docs/en/erlang.mk/1/guide/releases/index.html +++ b/docs/en/erlang.mk/1/guide/releases/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Releases</title> @@ -67,199 +67,226 @@ <h1 class="lined-header"><span>Releases</span></h1> -<div class="paragraph"><p>Erlang.mk relies on <em>Relx</em> for generating releases. This
-chapter covers the Erlang.mk-specific bits. Consult the
-<a href="https://erlware.github.io/relx/">Relx website</a> for more information.</p></div>
-<div class="sect1">
-<h2 id="_setup">Setup</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will create a release if it detects a Relx configuration
-file in the <em>$(RELX_CONFIG)</em> location. This defaults to
-<em>$(CURDIR)/relx.config</em>. You can override it by defining
-the variable before including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Relx does not need to be installed. Erlang.mk will download
-and build it automatically.</p></div>
-<div class="paragraph"><p>The Relx executable will be saved in the <em>$(RELX)</em> file. This
-location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can specify additional Relx options using the <code>RELX_OPTS</code>
-variable. For example, to enable <code>dev_mode</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>While you can specify the output directory for the release
-in the Relx options directly, Erlang.mk provides a specific
-variable for it: <code>RELX_OUTPUT_DIR</code>. It defaults to the <em>_rel</em>
-directory. You can also override it:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_the_release">Generating the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Now that you’re all set, all you need to do is generate the
-release. As mentioned before, Erlang.mk will automatically
-generate it when it detects the <em>$(RELX_CONFIG)</em> file. This
-means the following command will also build the release:</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>$ make</tt></pre></div></div>
-<div class="paragraph"><p>If you need to generate the release, and only the release,
-the <code>rel</code> target can be used:</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>$ make rel</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk always generates a tarball alongside the release,
-which can be directly uploaded to a server. The tarball is
-located at <code>$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_the_release">Running the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a convenience function for running the
-release with one simple command:</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>$ make run</tt></pre></div></div>
-<div class="paragraph"><p>This command will also build the project and generate the
-release if they weren’t already. It starts the release in
-<em>console mode</em>, meaning you will also have a shell ready to
-use to check things as needed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading_a_release">Upgrading a release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a <code>relup</code> target for generating release
-upgrades. Release upgrades allow updating the code and the
-state of a running release without restarting it.</p></div>
-<div class="paragraph"><p>Once your changes are done, you need to update the version
-of the application(s) that will be updated. You also need
-to update the version of the release.</p></div>
-<div class="paragraph"><p>For each application that needs to be updated, an
-<a href="http://erlang.org/doc/man/appup.html">appup file</a>
-must be written. Refer to the Erlang/OTP documentation
-for more details.</p></div>
-<div class="paragraph"><p>For the purpose of this section, assume the initial release
-version was <code>1</code>, and the new version is <code>2</code>. The name of the
-release will be <code>example</code>.</p></div>
-<div class="paragraph"><p>Once all this is done, you can build the tarball for the
-release upgrade:</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>$ make relup</tt></pre></div></div>
-<div class="paragraph"><p>This will create an archive at the root directory of the
-release, <code>$RELX_OUTPUT_DIR/example/example-2.tar.gz</code>.</p></div>
-<div class="paragraph"><p>Move the archive to the correct location on the running
-node. From the release’s root directory:</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>$ mkdir releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span>
-$ mv path/to/example-<span style="color: #993399">2</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, upgrade the release:</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>$ bin/example_release upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div>
-<div class="paragraph"><p>Or on Windows:</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>$ bin/example_release<span style="color: #990000">.</span>cmd upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div>
-<div class="paragraph"><p>Your release was upgraded!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_relx_semver_value">Getting Relx semver value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>There is a <strong>workaround</strong> to get the semver value which is
-generated by Relx based on VCS history.</p></div>
-<div class="paragraph"><p>Create a file <em>rel/version</em> with only one line inside:</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="color: #FF6600">release_version</span> }}</tt></pre></div></div>
-<div class="paragraph"><p>Add/Update the <code>overlay</code> section of your <code>relx.config</code>:</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="color: #FF6600">overlay</span>, [
- {<span style="color: #FF6600">template</span>, <span style="color: #FF0000">"rel/version"</span>, <span style="color: #FF0000">"version"</span>}
-]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>When you run <code>make rel</code> it creates the file <em>$(RELX_OUTPUT_DIR)/example/version</em>
-which contains the version value generated by Relx.</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>$ cat _rel/app/release
-<span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div>
-<div class="paragraph"><p>In your <code>Makefile</code> you can use this simple snippet to get the version,
-but please keep in mind that this should depend on the <code>rel</code> target:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>For example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Would output:</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>$ make myrecipe
-<span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/username/example/apps
- /home/username/example/deps
- /usr/lib/erlang/lib
- /home/username/example<span style="color: #990000">/</span>_rel
-<span style="color: #990000">===></span> Resolved example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span>
-<span style="color: #990000">===></span> tarball /home/username/example<span style="color: #990000">/</span>_rel/example/example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0<span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz successfully created<span style="color: #990000">!</span>
-echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0
-APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk relies on <em>Relx</em> for generating releases. This +chapter covers the Erlang.mk-specific bits. Consult the +<a href="https://erlware.github.io/relx/">Relx website</a> for more information.</p></div> +<div class="sect1"> +<h2 id="_setup">Setup</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will create a release if it detects a Relx configuration +file in the <em>$(RELX_CONFIG)</em> location. This defaults to +<em>$(CURDIR)/relx.config</em>. You can override it by defining +the variable before including Erlang.mk:</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="color: #009900">RELX_CONFIG =</span> <span style="color: #009900">$(CURDIR)</span>/webchat.config</tt></pre></div></div> +<div class="paragraph"><p>Relx does not need to be installed. Erlang.mk will download +and build it automatically.</p></div> +<div class="paragraph"><p>The Relx executable will be saved in the <em>$(RELX)</em> file. This +location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can specify additional Relx options using the <code>RELX_OPTS</code> +variable. For example, to enable <code>dev_mode</code>:</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="color: #009900">RELX_OPTS =</span> -d <span style="font-weight: bold"><span style="color: #0000FF">true</span></span></tt></pre></div></div> +<div class="paragraph"><p>While you can specify the output directory for the release +in the Relx options directly, Erlang.mk provides a specific +variable for it: <code>RELX_OUTPUT_DIR</code>. It defaults to the <em>_rel</em> +directory. You can also override 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="color: #009900">RELX_OUTPUT_DIR =</span> /path/to/staging/directory</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_the_release">Generating the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Now that you’re all set, all you need to do is generate the +release. As mentioned before, Erlang.mk will automatically +generate it when it detects the <em>$(RELX_CONFIG)</em> file. This +means the following command will also build the release:</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>$ make</tt></pre></div></div> +<div class="paragraph"><p>If you need to generate the release, and only the release, +the <code>rel</code> target can be used:</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>$ make rel</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk always generates a tarball alongside the release, +which can be directly uploaded to a server. The tarball is +located at <code>$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_the_release">Running the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a convenience function for running the +release with one simple command:</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>$ make run</tt></pre></div></div> +<div class="paragraph"><p>This command will also build the project and generate the +release if they weren’t already. It starts the release in +<em>console mode</em>, meaning you will also have a shell ready to +use to check things as needed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading_a_release">Upgrading a release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a <code>relup</code> target for generating release +upgrades. Release upgrades allow updating the code and the +state of a running release without restarting it.</p></div> +<div class="paragraph"><p>Once your changes are done, you need to update the version +of the application(s) that will be updated. You also need +to update the version of the release.</p></div> +<div class="paragraph"><p>For each application that needs to be updated, an +<a href="http://erlang.org/doc/man/appup.html">appup file</a> +must be written. Refer to the Erlang/OTP documentation +for more details.</p></div> +<div class="paragraph"><p>For the purpose of this section, assume the initial release +version was <code>1</code>, and the new version is <code>2</code>. The name of the +release will be <code>example</code>.</p></div> +<div class="paragraph"><p>Once all this is done, you can build the tarball for the +release upgrade:</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>$ make relup</tt></pre></div></div> +<div class="paragraph"><p>This will create an archive at the root directory of the +release, <code>$RELX_OUTPUT_DIR/example/example-2.tar.gz</code>.</p></div> +<div class="paragraph"><p>Move the archive to the correct location on the running +node. From the release’s root directory:</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>$ mkdir releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span> +$ mv path/to/example-<span style="color: #993399">2</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span></tt></pre></div></div> +<div class="paragraph"><p>Finally, upgrade the release:</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>$ bin/example_release upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div> +<div class="paragraph"><p>Or on Windows:</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>$ bin/example_release<span style="color: #990000">.</span>cmd upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div> +<div class="paragraph"><p>Your release was upgraded!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_relx_semver_value">Getting Relx semver value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>There is a <strong>workaround</strong> to get the semver value which is +generated by Relx based on VCS history.</p></div> +<div class="paragraph"><p>Create a file <em>rel/version</em> with only one line inside:</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="color: #FF6600">release_version</span> }}</tt></pre></div></div> +<div class="paragraph"><p>Add/Update the <code>overlay</code> section of your <code>relx.config</code>:</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="color: #FF6600">overlay</span>, [ + {<span style="color: #FF6600">template</span>, <span style="color: #FF0000">"rel/version"</span>, <span style="color: #FF0000">"version"</span>} +]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>When you run <code>make rel</code> it creates the file <em>$(RELX_OUTPUT_DIR)/example/version</em> +which contains the version value generated by Relx.</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>$ cat _rel/app/release +<span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div> +<div class="paragraph"><p>In your <code>Makefile</code> you can use this simple snippet to get the version, +but please keep in mind that this should depend on the <code>rel</code> target:</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="color: #009900">$(</span>shell cat <span style="color: #009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</span></tt></pre></div></div> +<div class="paragraph"><p>For example:</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>include erlang.mk + +<span style="color: #009900">APP_VERSION =</span> <span style="color: #009900">$(</span>shell cat <span style="color: #009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</span> +<span style="color: #990000">myrecipe:</span> all + echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #009900">$(APP_VERSION)</span></tt></pre></div></div> +<div class="paragraph"><p>Would output:</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>$ make myrecipe +<span style="color: #990000">...</span> +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/username/example/apps + /home/username/example/deps + /usr/lib/erlang/lib + /home/username/example<span style="color: #990000">/</span>_rel +<span style="color: #990000">===></span> Resolved example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0 +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span> +<span style="color: #990000">===></span> tarball /home/username/example<span style="color: #990000">/</span>_rel/example/example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0<span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz successfully created<span style="color: #990000">!</span> +echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0 +APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/sfx/index.html b/docs/en/erlang.mk/1/guide/sfx/index.html index 38a1f25b..a97c253f 100644 --- a/docs/en/erlang.mk/1/guide/sfx/index.html +++ b/docs/en/erlang.mk/1/guide/sfx/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Self-extracting releases</title> @@ -67,61 +67,64 @@ <h1 class="lined-header"><span>Self-extracting releases</span></h1> -<div class="paragraph"><p>Erlang.mk allows you to package <a href="../relx">Relx releases</a> as
-self-extracting archives. These archives contain all the
-files in the release and come in the form of a script that
-will extract and run the release automatically.</p></div>
-<div class="paragraph"><p>This allows you to package the release as a single file
-that can then be executed.</p></div>
-<div class="paragraph"><p>This feature is currently experimental. Feedback is much
-appreciated.</p></div>
-<div class="sect1">
-<h2 id="_generating_the_self_extracting_archive">Generating the self-extracting archive</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To generate a self-extracting release, all you need to do
-is pass the <code>SFX=1</code> variable to Make when you build the
-release:</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>$ make <span style="color: #009900">SFX</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>This will create a self-extracting archive in
-<code>$RELX_OUTPUT_DIR/<name>.run</code>. For example if the release
-is named <code>hello_world</code> and <code>$RELX_OUTPUT_DIR</code> is the default,
-the file will be located at <code>_rel/hello_world.run</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_the_release">Running the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Simply execute the script to get started:</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="color: #990000">./</span>_rel/hello_world<span style="color: #990000">.</span>run
-Exec<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta/erts-<span style="color: #993399">8.1</span>/bin/erlexec <span style="color: #990000">...</span>
-Root<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta
-/tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta
-Erlang/OTP <span style="color: #993399">19</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">8.1</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">...</span>
-
-Eshell V8<span style="color: #990000">.</span><span style="color: #993399">1</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span>
-<span style="color: #990000">(</span>hello_world@localhost<span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div>
-<div class="paragraph"><p>As you can see the archive is extracted to a temporary
-directory before the release can be started.</p></div>
-<div class="paragraph"><p>The self-extracting script currently only supports starting
-the release in <code>console</code> mode.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk allows you to package <a href="../relx">Relx releases</a> as +self-extracting archives. These archives contain all the +files in the release and come in the form of a script that +will extract and run the release automatically.</p></div> +<div class="paragraph"><p>This allows you to package the release as a single file +that can then be executed.</p></div> +<div class="paragraph"><p>This feature is currently experimental. Feedback is much +appreciated.</p></div> +<div class="sect1"> +<h2 id="_generating_the_self_extracting_archive">Generating the self-extracting archive</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To generate a self-extracting release, all you need to do +is pass the <code>SFX=1</code> variable to Make when you build the +release:</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>$ make <span style="color: #009900">SFX</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>This will create a self-extracting archive in +<code>$RELX_OUTPUT_DIR/<name>.run</code>. For example if the release +is named <code>hello_world</code> and <code>$RELX_OUTPUT_DIR</code> is the default, +the file will be located at <code>_rel/hello_world.run</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_the_release">Running the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Simply execute the script to get started:</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="color: #990000">./</span>_rel/hello_world<span style="color: #990000">.</span>run +Exec<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta/erts-<span style="color: #993399">8.1</span>/bin/erlexec <span style="color: #990000">...</span> +Root<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta +/tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta +Erlang/OTP <span style="color: #993399">19</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">8.1</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">...</span> + +Eshell V8<span style="color: #990000">.</span><span style="color: #993399">1</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span> +<span style="color: #990000">(</span>hello_world@localhost<span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div> +<div class="paragraph"><p>As you can see the archive is extracted to a temporary +directory before the release can be started.</p></div> +<div class="paragraph"><p>The self-extracting script currently only supports starting +the release in <code>console</code> mode.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/shell/index.html b/docs/en/erlang.mk/1/guide/shell/index.html index 28a13113..873e7b2f 100644 --- a/docs/en/erlang.mk/1/guide/shell/index.html +++ b/docs/en/erlang.mk/1/guide/shell/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang shell</title> @@ -67,53 +67,72 @@ <h1 class="lined-header"><span>Erlang shell</span></h1> -<div class="paragraph"><p>Erlang.mk provides a convenient target for starting a shell
-with all the paths set properly to experiment with your code.</p></div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>SHELL_DEPS</code> variable can be used to define dependencies
-that are only to be used when the <code>make shell</code> command is called.
-For example, if you want to use <em>kjell</em> as your shell:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Dependencies are downloaded and compiled the first time you
-run the <code>make shell</code> command.</p></div>
-<div class="paragraph"><p>You can customize the executable used to start the Erlang shell.
-To continue with our example, if you want to use <em>kjell</em> as your
-shell, you also need to change <code>SHELL_ERL</code> and point it to the
-<code>kjell</code> executable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can specify additional options to be used when starting the
-shell using the <code>SHELL_OPTS</code> variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Any of the usual <code>erl</code> options can be used, including <code>-eval</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To start the shell, all you need is the following command:</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>$ make shell</tt></pre></div></div>
-<div class="paragraph"><p>The shell can be stopped as usual with a double Ctrl+C or the
-command <code>q().</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides a convenient target for starting a shell +with all the paths set properly to experiment with your code.</p></div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>SHELL_DEPS</code> variable can be used to define dependencies +that are only to be used when the <code>make shell</code> command is called. +For example, if you want to use <em>kjell</em> as your shell:</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="color: #009900">SHELL_DEPS =</span> kjell</tt></pre></div></div> +<div class="paragraph"><p>Dependencies are downloaded and compiled the first time you +run the <code>make shell</code> command.</p></div> +<div class="paragraph"><p>You can customize the executable used to start the Erlang shell. +To continue with our example, if you want to use <em>kjell</em> as your +shell, you also need to change <code>SHELL_ERL</code> and point it to the +<code>kjell</code> executable:</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="color: #009900">SHELL_ERL =</span> <span style="color: #009900">$(DEPS_DIR)</span>/kjell/bin/kjell</tt></pre></div></div> +<div class="paragraph"><p>You can specify additional options to be used when starting the +shell using the <code>SHELL_OPTS</code> variable:</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="color: #009900">SHELL_OPTS =</span> -setcookie chocolate</tt></pre></div></div> +<div class="paragraph"><p>Any of the usual <code>erl</code> options can be used, including <code>-eval</code>:</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="color: #009900">SHELL_OPTS =</span> -eval <span style="color: #FF0000">'my_app:run()'</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To start the shell, all you need is the following command:</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>$ make shell</tt></pre></div></div> +<div class="paragraph"><p>The shell can be stopped as usual with a double Ctrl+C or the +command <code>q().</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/updating/index.html b/docs/en/erlang.mk/1/guide/updating/index.html index 96223e32..826e1b0d 100644 --- a/docs/en/erlang.mk/1/guide/updating/index.html +++ b/docs/en/erlang.mk/1/guide/updating/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Updating Erlang.mk</title> @@ -67,95 +67,98 @@ <h1 class="lined-header"><span>Updating Erlang.mk</span></h1> -<div class="paragraph"><p>This chapter describes how to update the <em>erlang.mk</em> file
-in your repository.</p></div>
-<div class="sect1">
-<h2 id="_initial_bootstrap">Initial bootstrap</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first time you use Erlang.mk, it will bootstrap itself.
-It always uses the most recent version for this, so you don’t
-have to update after creating your project.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_updating">Updating</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Later on though, updating becomes a necessity. Erlang.mk
-developers and contributors relentlessly improve the project
-and add new features; it would be a waste not to benefit
-from this.</p></div>
-<div class="paragraph"><p>That’s why updating Erlang.mk is so simple. All you need
-to do is to call <code>make erlang-mk</code>:</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>$ make erlang-mk
-git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build
-Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span>
-remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span>
-Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">1000.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
-cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span>
-awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span>
- <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span>
-cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk
-rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div>
-<div class="paragraph"><p>All that’s left to do is to commit the file!</p></div>
-<div class="paragraph"><p>Yep, it’s that easy.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customizing_the_build">Customizing the build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk allows you to customize which components are to be included
-in the <em>erlang.mk</em> file. The <code>WITHOUT</code> variable allows you to
-remove components from the default Erlang.mk build. The <em>build.config</em>
-file lets you define exactly what goes in (including your own code!),
-and in what order.</p></div>
-<div class="paragraph"><p>The <code>WITHOUT</code> file contains the list of components to exclude from
-the build. For example, to exclude the package index and the EDoc
-plugin when bootstrapping your application:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span><span style="color: #FF0000">"index plugins/edoc"</span></tt></pre></div></div>
-<div class="paragraph"><p>The generated Erlang.mk will never include those components when
-you update it, until you change your mind and use the <code>WITHOUT</code>
-variable again when you upgrade:</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>$ make erlang-mk <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span>index</tt></pre></div></div>
-<div class="paragraph"><p>The <em>build.config</em> file is automatically used when you bootstrap
-Erlang.mk or when you update it with <code>make erlang-mk</code>.</p></div>
-<div class="paragraph"><p>The <em>build.config</em> file contains the list of all files that will
-be built into the resulting <em>erlang.mk</em> file. You can start from
-the <a href="https://github.com/ninenines/erlang.mk/blob/master/build.config">most recent version</a>
-and customize to your needs.</p></div>
-<div class="paragraph"><p>You can also name the file differently or put it in a separate folder
-by modifying the value for <code>ERLANG_MK_BUILD_CONFIG</code>. You can also
-tell Erlang.mk to use a different temporary directory by changing
-the <code>ERLANG_MK_BUILD_DIR</code> variable.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to update the <em>erlang.mk</em> file +in your repository.</p></div> +<div class="sect1"> +<h2 id="_initial_bootstrap">Initial bootstrap</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first time you use Erlang.mk, it will bootstrap itself. +It always uses the most recent version for this, so you don’t +have to update after creating your project.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_updating">Updating</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Later on though, updating becomes a necessity. Erlang.mk +developers and contributors relentlessly improve the project +and add new features; it would be a waste not to benefit +from this.</p></div> +<div class="paragraph"><p>That’s why updating Erlang.mk is so simple. All you need +to do is to call <code>make erlang-mk</code>:</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>$ make erlang-mk +git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build +Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span> +remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span> +Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">1000.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span> +cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span> +awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span> + <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span> +cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk +rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div> +<div class="paragraph"><p>All that’s left to do is to commit the file!</p></div> +<div class="paragraph"><p>Yep, it’s that easy.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customizing_the_build">Customizing the build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk allows you to customize which components are to be included +in the <em>erlang.mk</em> file. The <code>WITHOUT</code> variable allows you to +remove components from the default Erlang.mk build. The <em>build.config</em> +file lets you define exactly what goes in (including your own code!), +and in what order.</p></div> +<div class="paragraph"><p>The <code>WITHOUT</code> file contains the list of components to exclude from +the build. For example, to exclude the package index and the EDoc +plugin when bootstrapping your application:</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span><span style="color: #FF0000">"index plugins/edoc"</span></tt></pre></div></div> +<div class="paragraph"><p>The generated Erlang.mk will never include those components when +you update it, until you change your mind and use the <code>WITHOUT</code> +variable again when you upgrade:</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>$ make erlang-mk <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span>index</tt></pre></div></div> +<div class="paragraph"><p>The <em>build.config</em> file is automatically used when you bootstrap +Erlang.mk or when you update it with <code>make erlang-mk</code>.</p></div> +<div class="paragraph"><p>The <em>build.config</em> file contains the list of all files that will +be built into the resulting <em>erlang.mk</em> file. You can start from +the <a href="https://github.com/ninenines/erlang.mk/blob/master/build.config">most recent version</a> +and customize to your needs.</p></div> +<div class="paragraph"><p>You can also name the file differently or put it in a separate folder +by modifying the value for <code>ERLANG_MK_BUILD_CONFIG</code>. You can also +tell Erlang.mk to use a different temporary directory by changing +the <code>ERLANG_MK_BUILD_DIR</code> variable.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/why/index.html b/docs/en/erlang.mk/1/guide/why/index.html index bc1881cf..0c73daaf 100644 --- a/docs/en/erlang.mk/1/guide/why/index.html +++ b/docs/en/erlang.mk/1/guide/why/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Why Erlang.mk</title> @@ -67,92 +67,95 @@ <h1 class="lined-header"><span>Why Erlang.mk</span></h1> -<div class="paragraph"><p>Why would you choose Erlang.mk, if not for its
-<a href="../overview">many features</a>? This chapter will
-attempt to answer that.</p></div>
-<div class="sect1">
-<h2 id="_erlang_mk_is_fast">Erlang.mk is fast</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is as fast as it gets.</p></div>
-<div class="paragraph"><p>Erlang.mk will group the compilation of files so as to avoid
-running the BEAM more than necessary. This saves many seconds
-compared to traditional Makefiles, even on small projects.</p></div>
-<div class="paragraph"><p>Erlang.mk will not try to be too smart. It provides a simple
-solution that works for most people, and gives additional
-options for projects that run into edge cases, often in the
-form of extra variables or rules to be defined.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_gives_you_the_full_power_of_unix">Erlang.mk gives you the full power of Unix</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div>
-<div class="paragraph"><p>You could use Erlang.mk directly without configuring anything
-and it would just work. But you can also extend it greatly
-either through configuration or hooks, and you can of course
-add your own rules to the Makefile.</p></div>
-<div class="paragraph"><p>In all cases: for configuration, hooks or custom rules, you
-have all the power of Unix at your disposal, and can call
-any utility <em>or even any language interpreter</em> you want,
-every time you need to. Erlang.mk also allows you to write
-scripts in this small language called Erlang directly inside
-your Makefile if you ever need to…</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_is_a_text_file">Erlang.mk is a text file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div>
-<div class="paragraph"><p>Which means Erlang.mk is a simple text file. You can edit a
-text file. Nothing stops you. If you run into any bug, or
-behavior that does not suit you, you can just open the
-<em>erlang.mk</em> file in your favorite editor, fix and/or comment
-a few lines, save, and try again. It’s as simple as it gets.</p></div>
-<div class="paragraph"><p>Currently using a binary build tool? Good luck with that.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_can_manage_erlang_itself">Erlang.mk can manage Erlang itself</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk isn’t written in Erlang.</p></div>
-<div class="paragraph"><p>That’s not a good thing, you say? Well, here’s one thing
-that Erlang.mk and Makefiles can do for you that Erlang
-build tool can’t easily: choose what version of Erlang is
-to be used for compiling the project.</p></div>
-<div class="paragraph"><p>This really is a one-liner in Erlang.mk (a few more lines
-if you also let it download and build Erlang directly)
-and allows for even greater things, like testing your
-project across all supported Erlang versions in one small
-command: <code>make -k ci</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_can_do_more_than_erlang">Erlang.mk can do more than Erlang</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk doesn’t care what your dependencies are written in.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily compile any dependency, as long as
-they come with a Makefile. The dependency can be written
-in C, C++ or even Javascript… Who cares, really? If you
-need Erlang.mk to fetch it, then Erlang.mk will fetch it
-and compile it as needed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_integrates_nicely_in_make_and_automake_projects">Erlang.mk integrates nicely in Make and Automake projects</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you are planning to put your project in the middle of
-a Make or Automake-based build environment, then the most
-logical thing to do is to use a Makefile.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily sit in such an environment and behave
-as you expect it to.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Why would you choose Erlang.mk, if not for its +<a href="../overview">many features</a>? This chapter will +attempt to answer that.</p></div> +<div class="sect1"> +<h2 id="_erlang_mk_is_fast">Erlang.mk is fast</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is as fast as it gets.</p></div> +<div class="paragraph"><p>Erlang.mk will group the compilation of files so as to avoid +running the BEAM more than necessary. This saves many seconds +compared to traditional Makefiles, even on small projects.</p></div> +<div class="paragraph"><p>Erlang.mk will not try to be too smart. It provides a simple +solution that works for most people, and gives additional +options for projects that run into edge cases, often in the +form of extra variables or rules to be defined.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_gives_you_the_full_power_of_unix">Erlang.mk gives you the full power of Unix</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div> +<div class="paragraph"><p>You could use Erlang.mk directly without configuring anything +and it would just work. But you can also extend it greatly +either through configuration or hooks, and you can of course +add your own rules to the Makefile.</p></div> +<div class="paragraph"><p>In all cases: for configuration, hooks or custom rules, you +have all the power of Unix at your disposal, and can call +any utility <em>or even any language interpreter</em> you want, +every time you need to. Erlang.mk also allows you to write +scripts in this small language called Erlang directly inside +your Makefile if you ever need to…</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_is_a_text_file">Erlang.mk is a text file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div> +<div class="paragraph"><p>Which means Erlang.mk is a simple text file. You can edit a +text file. Nothing stops you. If you run into any bug, or +behavior that does not suit you, you can just open the +<em>erlang.mk</em> file in your favorite editor, fix and/or comment +a few lines, save, and try again. It’s as simple as it gets.</p></div> +<div class="paragraph"><p>Currently using a binary build tool? Good luck with that.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_can_manage_erlang_itself">Erlang.mk can manage Erlang itself</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk isn’t written in Erlang.</p></div> +<div class="paragraph"><p>That’s not a good thing, you say? Well, here’s one thing +that Erlang.mk and Makefiles can do for you that Erlang +build tool can’t easily: choose what version of Erlang is +to be used for compiling the project.</p></div> +<div class="paragraph"><p>This really is a one-liner in Erlang.mk (a few more lines +if you also let it download and build Erlang directly) +and allows for even greater things, like testing your +project across all supported Erlang versions in one small +command: <code>make -k ci</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_can_do_more_than_erlang">Erlang.mk can do more than Erlang</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk doesn’t care what your dependencies are written in.</p></div> +<div class="paragraph"><p>Erlang.mk will happily compile any dependency, as long as +they come with a Makefile. The dependency can be written +in C, C++ or even Javascript… Who cares, really? If you +need Erlang.mk to fetch it, then Erlang.mk will fetch it +and compile it as needed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_integrates_nicely_in_make_and_automake_projects">Erlang.mk integrates nicely in Make and Automake projects</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you are planning to put your project in the middle of +a Make or Automake-based build environment, then the most +logical thing to do is to use a Makefile.</p></div> +<div class="paragraph"><p>Erlang.mk will happily sit in such an environment and behave +as you expect it to.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/xref/index.html b/docs/en/erlang.mk/1/guide/xref/index.html index 6cb0e2ec..7913e3d9 100644 --- a/docs/en/erlang.mk/1/guide/xref/index.html +++ b/docs/en/erlang.mk/1/guide/xref/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Xref</title> @@ -67,13 +67,16 @@ <h1 class="lined-header"><span>Xref</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Placeholder chapter.</p></div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/index.html b/docs/en/erlang.mk/1/index.html index d87c4243..0194031a 100644 --- a/docs/en/erlang.mk/1/index.html +++ b/docs/en/erlang.mk/1/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/erlang.mk/index.html b/docs/en/erlang.mk/index.html index d87c4243..0194031a 100644 --- a/docs/en/erlang.mk/index.html +++ b/docs/en/erlang.mk/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/gun/1.0/guide/connect/index.html b/docs/en/gun/1.0/guide/connect/index.html index 50035be4..62b1619d 100644 --- a/docs/en/gun/1.0/guide/connect/index.html +++ b/docs/en/gun/1.0/guide/connect/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Connection</title> @@ -67,174 +67,177 @@ <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 HTTP/2 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
-HTTP/2 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
-ALPN extension for TLS. By default Gun supports HTTP/2
-and HTTP/1.1 when connecting using SSL.</p></div>
-<div class="paragraph"><p>For any other port, Gun will attempt to connect using TCP
-and will use the HTTP/1.1 protocol.</p></div>
-<div class="paragraph"><p>The transport and protocol used can be overriden using
-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 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 HTTP/2 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 +HTTP/2 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 +ALPN extension for TLS. By default Gun supports HTTP/2 +and HTTP/1.1 when connecting using SSL.</p></div> +<div class="paragraph"><p>For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol.</p></div> +<div class="paragraph"><p>The transport and protocol used can be overriden using +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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/http/index.html b/docs/en/gun/1.0/guide/http/index.html index 668d3ff6..bbdb81ed 100644 --- a/docs/en/gun/1.0/guide/http/index.html +++ b/docs/en/gun/1.0/guide/http/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: HTTP</title> @@ -67,402 +67,405 @@ <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 HTTP/2 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,4}</code> to request a resource.</p></div>
-<div class="listingblock">
-<div class="title">GET "/organizations/ninenines"</div>
-<div class="content"><!-- Generator: GNU source-highlight 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,4}</code> if you don’t need the response body.</p></div>
-<div class="listingblock">
-<div class="title">HEAD "/organizations/ninenines"</div>
-<div class="content"><!-- Generator: GNU source-highlight 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,5}</code>, <code>gun:put/{4,5}</code> and <code>gun:patch/{4,5}</code> functions
-take a body as their fourth argument. These functions do
-not require any body-specific header to be set, although
-it is always recommended to set the content-type header.
-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 HTTP/2 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,4}</code> to delete a resource.</p></div>
-<div class="listingblock">
-<div class="title">DELETE "/organizations/ninenines"</div>
-<div class="content"><!-- Generator: GNU source-highlight 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,6}</code> function can be used to send requests
-with a configurable method name. It is mostly useful when you
-need a method that Gun does not understand natively.</p></div>
-<div class="listingblock">
-<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 HTTP/2 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 HTTP/2 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 class="sect1">
-<h2 id="_redirecting_responses_to_a_different_process">Redirecting responses to a different process</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun allows you to specify which process will handle responses
-to a request via the <code>reply_to</code> request option.</p></div>
-<div class="listingblock">
-<div class="title">GET "/organizations/ninenines" to a different 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: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [],
- #{<span style="color: #0000FF">reply_to</span> <span style="color: #990000">=></span> <span style="color: #009900">Pid</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to use the Gun client for +communicating with an HTTP/1.1 or HTTP/2 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,4}</code> to request a resource.</p></div> +<div class="listingblock"> +<div class="title">GET "/organizations/ninenines"</div> +<div class="content"><!-- Generator: GNU source-highlight 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,4}</code> if you don’t need the response body.</p></div> +<div class="listingblock"> +<div class="title">HEAD "/organizations/ninenines"</div> +<div class="content"><!-- Generator: GNU source-highlight 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,5}</code>, <code>gun:put/{4,5}</code> and <code>gun:patch/{4,5}</code> functions +take a body as their fourth argument. These functions do +not require any body-specific header to be set, although +it is always recommended to set the content-type header. +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 HTTP/2 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,4}</code> to delete a resource.</p></div> +<div class="listingblock"> +<div class="title">DELETE "/organizations/ninenines"</div> +<div class="content"><!-- Generator: GNU source-highlight 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,6}</code> function can be used to send requests +with a configurable method name. It is mostly useful when you +need a method that Gun does not understand natively.</p></div> +<div class="listingblock"> +<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 HTTP/2 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 HTTP/2 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 class="sect1"> +<h2 id="_redirecting_responses_to_a_different_process">Redirecting responses to a different process</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun allows you to specify which process will handle responses +to a request via the <code>reply_to</code> request option.</p></div> +<div class="listingblock"> +<div class="title">GET "/organizations/ninenines" to a different 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: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [], + #{<span style="color: #0000FF">reply_to</span> <span style="color: #990000">=></span> <span style="color: #009900">Pid</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/index.html b/docs/en/gun/1.0/guide/index.html index 8ad8284c..d243d71c 100644 --- a/docs/en/gun/1.0/guide/index.html +++ b/docs/en/gun/1.0/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Gun User Guide</title> @@ -67,38 +67,38 @@ <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 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> diff --git a/docs/en/gun/1.0/guide/introduction/index.html b/docs/en/gun/1.0/guide/introduction/index.html index 46d1fc33..271dfbc9 100644 --- a/docs/en/gun/1.0/guide/introduction/index.html +++ b/docs/en/gun/1.0/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,46 +67,49 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Knowledge of Erlang, but also of the HTTP/1.1, HTTP/2 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 class="sect1">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun uses [Semantic Versioning 2.0.0](<a href="http://semver.org/">http://semver.org/</a>).</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 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, HTTP/2 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 class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun uses [Semantic Versioning 2.0.0](<a href="http://semver.org/">http://semver.org/</a>).</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/protocols/index.html b/docs/en/gun/1.0/guide/protocols/index.html index 38b05bfd..36f9b62f 100644 --- a/docs/en/gun/1.0/guide/protocols/index.html +++ b/docs/en/gun/1.0/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Supported protocols</title> @@ -67,265 +67,268 @@ <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,6}</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="_http_2">HTTP/2</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP/2 is a binary protocol based on HTTP, compatible with
-the HTTP semantics, that reduces the complexity of parsing
-requests and responses, compresses the HTTP headers and
-allows the server to push multiple responses to a single
-request.</p></div>
-<div class="paragraph"><p>The HTTP/2 interface is very similar to HTTP/1.1, so this
-section instead focuses on the differences in the interface
-for the two protocols.</p></div>
-<div class="paragraph"><p>Because a HTTP/2 server can push multiple responses to a
-single request, Gun might send <code>gun_push</code> messages for
-every push received. They can be ignored safely if they
-are not needed.</p></div>
-<div class="paragraph"><p>The <code>gun:cancel/2</code> function will use the HTTP/2 stream
-cancellation mechanism which allows Gun to inform the
-server to stop sending a response for this particular
-request, saving resources.</p></div>
-<div class="paragraph"><p>It is not possible to upgrade an HTTP/2 connection to Websocket
-due to protocol limitations.</p></div>
-</div>
-</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">
-<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"> HTTP/2 </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">
-<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"> HTTP/2 </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 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,6}</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="_http_2">HTTP/2</h2> +<div class="sectionbody"> +<div class="paragraph"><p>HTTP/2 is a binary protocol based on HTTP, compatible with +the HTTP semantics, that reduces the complexity of parsing +requests and responses, compresses the HTTP headers and +allows the server to push multiple responses to a single +request.</p></div> +<div class="paragraph"><p>The HTTP/2 interface is very similar to HTTP/1.1, so this +section instead focuses on the differences in the interface +for the two protocols.</p></div> +<div class="paragraph"><p>Because a HTTP/2 server can push multiple responses to a +single request, Gun might send <code>gun_push</code> messages for +every push received. They can be ignored safely if they +are not needed.</p></div> +<div class="paragraph"><p>The <code>gun:cancel/2</code> function will use the HTTP/2 stream +cancellation mechanism which allows Gun to inform the +server to stop sending a response for this particular +request, saving resources.</p></div> +<div class="paragraph"><p>It is not possible to upgrade an HTTP/2 connection to Websocket +due to protocol limitations.</p></div> +</div> +</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"> +<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"> HTTP/2 </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"> +<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"> HTTP/2 </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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/start/index.html b/docs/en/gun/1.0/guide/start/index.html index b0345edf..e7df8d53 100644 --- a/docs/en/gun/1.0/guide/start/index.html +++ b/docs/en/gun/1.0/guide/start/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Starting and stopping</title> @@ -67,84 +67,91 @@ <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"></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 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html index 4f162488..b10064cf 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Websocket</title> @@ -67,134 +67,137 @@ <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 class="paragraph"><p>Note that you shouldn’t use the <code>reply_to</code> request option
-for connections you plan to upgrade, because only the
-owner of the connection will receive messages about it.</p></div>
-</div>
-</div>
-<div class="sect1">
-<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 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 class="paragraph"><p>Note that you shouldn’t use the <code>reply_to</code> request option +for connections you plan to upgrade, because only the +owner of the connection will receive messages about it.</p></div> +</div> +</div> +<div class="sect1"> +<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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/index.html b/docs/en/gun/1.0/index.html index d87c4243..0194031a 100644 --- a/docs/en/gun/1.0/index.html +++ b/docs/en/gun/1.0/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/gun/1.0/manual/gun/index.html b/docs/en/gun/1.0/manual/gun/index.html index 9fedee7e..aad74371 100644 --- a/docs/en/gun/1.0/manual/gun/index.html +++ b/docs/en/gun/1.0/manual/gun/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: gun(3)</title> @@ -67,1731 +67,1731 @@ <h1 class="lined-header"><span>gun(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>gun - asynchronous HTTP client</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>gun</code> module provides an asynchronous interface for
-connecting and communicating with Web servers over HTTP,
-HTTP/2 or Websocket.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opts_map">opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the connection.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-connect_timeout ⇒ timeout()
-</dt>
-<dd>
-<p>
- Connection timeout. Defaults to <code>infinity</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-http_opts ⇒ http_opts()
-</dt>
-<dd>
-<p>
- Options specific to the HTTP protocol. See below.
-</p>
-</dd>
-<dt class="hdlist1">
-http2_opts ⇒ http2_opts()
-</dt>
-<dd>
-<p>
- Options specific to the HTTP/2 protocol. See below.
-</p>
-</dd>
-<dt class="hdlist1">
-protocols ⇒ [http | http2]
-</dt>
-<dd>
-<p>
- Ordered list of preferred protocols. When the transport is tcp,
- this list must contain exactly one protocol. When the transport
- is ssl, this list must contain at least one protocol and will be
- used using the ALPN protocol negotiation method. When the server
- does not support ALPN then http will always be used. Defaults to
- [http] when the transport is tcp, and [http2, http] when the
- transport is ssl.
-</p>
-</dd>
-<dt class="hdlist1">
-retry ⇒ non_neg_integer()
-</dt>
-<dd>
-<p>
- Number of times Gun will try to reconnect on failure before giving up.
- Defaults to 5.
-</p>
-</dd>
-<dt class="hdlist1">
-retry_timeout ⇒ pos_integer()
-</dt>
-<dd>
-<p>
- Time between retries in milliseconds. Defaults to 5000.
-</p>
-</dd>
-<dt class="hdlist1">
-trace ⇒ boolean()
-</dt>
-<dd>
-<p>
- Whether to enable <code>dbg</code> tracing of the connection process. Should
- only be used during debugging. Defaults to false.
-</p>
-</dd>
-<dt class="hdlist1">
-transport ⇒ tcp | ssl
-</dt>
-<dd>
-<p>
- Whether to use SSL or plain TCP. The default varies depending on the
- port used. Port 443 defaults to ssl. All other ports default to tcp.
-</p>
-</dd>
-<dt class="hdlist1">
-transport_opts ⇒ proplists:proplist()
-</dt>
-<dd>
-<p>
- Transport options. They are TCP options or SSL options depending on
- the selected transport.
-</p>
-</dd>
-<dt class="hdlist1">
-ws_opts ⇒ ws_opts()
-</dt>
-<dd>
-<p>
- Options specific to the Websocket protocol. See below.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_http_opts_map">http_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the HTTP protocol.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-keepalive ⇒ timeout()
-</dt>
-<dd>
-<p>
- Time between pings in milliseconds. Since the HTTP protocol has
- no standardized way to ping the server, Gun will simply send an
- empty line when the connection is idle. Gun only makes a best
- effort here as servers usually have configurable limits to drop
- idle connections. Use <code>infinity</code> to disable. Defaults to 5000.
-</p>
-</dd>
-<dt class="hdlist1">
-transform_header_name ⇒ funLowercaseName :: binary( → TransformedName :: binary()) | undefined
-</dt>
-<dd>
-<p>
- A function that will be applied to all header names before they
- are sent to the server. Gun assumes that all header names are in
- lower case. This function is useful if you, for example, need to
- re-case header names in the event that the server incorrectly
- considers header name case to be significant.
-</p>
-</dd>
-<dt class="hdlist1">
-version ⇒ <em>HTTP/1.1</em> | <em>HTTP/1.0</em>
-</dt>
-<dd>
-<p>
- HTTP version to use. Defaults to <em>HTTP/1.1</em>.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_http2_opts_map">http2_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-keepalive ⇒ pos_integer()
-</dt>
-<dd>
-<p>
- Time between pings in milliseconds. Defaults to 5000.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_req_opts_map">req_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for a particular request.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-reply_to ⇒ pid()
-</dt>
-<dd>
-<p>
- The pid of a process that is responsible for the response handling.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_opts_map">ws_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the Websocket protocol.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-compress ⇒ boolean()
-</dt>
-<dd>
-<p>
- Whether to enable permessage-deflate compression. This does
- not guarantee that compression will be used as it is the
- server that ultimately decides. Defaults to false.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_messages">Messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Calling functions from this module may result in the following
-messages being sent.</p></div>
-<div class="sect2">
-<h3 id="_gun_up_connpid_protocol">{gun_up, ConnPid, Protocol}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = http | http2
-</dt>
-<dd>
-<p>
-The protocol selected for this connection.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The connection is up.</p></div>
-<div class="paragraph"><p>This message informs the owner process that the connection or
-reconnection completed.</p></div>
-<div class="paragraph"><p>The protocol selected during the connection is sent in this
-message. It can be used to determine the capabilities of the
-server.</p></div>
-<div class="paragraph"><p>Gun will now start processing the messages it received while
-waiting for the connection to be up. If this is a reconnection,
-then this may not be desirable for all requests. Those requests
-should be cancelled when the connection goes down, and any
-subsequent messages ignored.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_down_connpid_protocol_reason_killedstreams_unprocessedstreams">{gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = http | http2 | ws
-</dt>
-<dd>
-<p>
-The protocol in use when the connection was lost.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = normal | closed | {error, atom()}
-</dt>
-<dd>
-<p>
-The reason for the loss of the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-KilledStreams = [reference()]
-</dt>
-<dd>
-<p>
-List of streams that have been brutally terminated.
-</p>
-</dd>
-<dt class="hdlist1">
-UnprocessedStreams = [reference()]
-</dt>
-<dd>
-<p>
-List of streams that have not been processed by the server.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The connection is down.</p></div>
-<div class="paragraph"><p>This message informs the owner process that the connection is
-currently down. Gun will automatically attempt to reconnect
-depending on the <code>retry</code> and <code>retry_timeout</code> options.</p></div>
-<div class="paragraph"><p>The reason of the termination is there for debugging purposes
-only. You should not rely on this value to know what streams
-were processed or completed.</p></div>
-<div class="paragraph"><p>The <em>killed streams</em> are the active streams that did not complete
-before the closing of the connection. Whether they can be retried
-safely depends on the protocol used and the idempotence property
-of the requests.</p></div>
-<div class="paragraph"><p>The <em>unprocessed streams</em> are streams that the server did not
-start processing yet. They may be retried safely depending on
-what streams were killed before.</p></div>
-<div class="paragraph"><p>When the connection goes back up, Gun will not attempt to retry
-requests. It will also not upgrade to Websocket automatically
-if that was the protocol in use when the connection was lost.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_push_connpid_streamref_newstreamref_uri_headers">{gun_push, ConnPid, StreamRef, NewStreamRef, URI, Headers}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream initiated by the owner process.
-</p>
-</dd>
-<dt class="hdlist1">
-NewStreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream being pushed.
-</p>
-</dd>
-<dt class="hdlist1">
-URI = binary()
-</dt>
-<dd>
-<p>
-URI of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers @todo
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>A resource pushed alongside an HTTP response.</p></div>
-<div class="paragraph"><p>This message can only be sent when the protocol is HTTP/2.</p></div>
-<div class="paragraph"><p>@todo I fear we also need the scheme; resource is identified by URI
-@todo Perhaps we really should send the URI entirely, because cache
-@todo relies on URI to work and this feature is for caching…
-@todo Not sure why Method is there, spec says it is only for GET</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_response_connpid_streamref_isfin_status_headers">{gun_response, ConnPid, StreamRef, IsFin, Status, Headers}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream initiated by the owner process.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Status = binary()
-</dt>
-<dd>
-<p>
-Status line for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers sent with the response.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>A response to an HTTP request.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_data_connpid_streamref_isfin_data">{gun_data, ConnPid, StreamRef, IsFin, Data}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream this data belongs to.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Data = binary()
-</dt>
-<dd>
-<p>
-Data from the stream.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Data associated with a stream.</p></div>
-<div class="paragraph"><p>The stream in question can be either one initiated by the owner
-process or a stream initiated by the server through the push
-mechanism. In any case a <code>gun_response</code> or a <code>gun_push</code> message
-will be sent before any <code>gun_data</code> message.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_error_connpid_streamref_reason">{gun_error, ConnPid, StreamRef, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream this error relates to.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stream-specific error.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_error_connpid_reason">{gun_error, ConnPid, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>General error.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_ws_upgrade_connpid_ok_headers">{gun_ws_upgrade, ConnPid, ok, Headers}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers sent with the response.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Successful upgrade to the Websocket protocol.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_ws_connpid_frame">{gun_ws, ConnPid, Frame}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Frame = @todo
-</dt>
-<dd>
-<p>
-Frame.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Websocket frame.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_open_host_port_8594_open_host_port">open(Host, Port) → open(Host, Port, [])</h3>
-<div class="paragraph"><p>Alias of <code>gun:open/3</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_open_host_port_opts_8594_ok_connpid_error_reason">open(Host, Port, Opts) → {ok, ConnPid} | {error, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Host = inet:hostname()
-</dt>
-<dd>
-<p>
-Host to connect to.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port to connect to.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts = opts()
-</dt>
-<dd>
-<p>
-Options for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason. @todo really any?
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Open a connection to the given host and port.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_close_connpid_8594_ok">close(ConnPid) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Brutally close the connection.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_shutdown_connpid_8594_ok">shutdown(ConnPid) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Gracefully close the connection.</p></div>
-<div class="paragraph"><p>A monitor can be used to be notified when the connection is
-effectively closed.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_connpid_path_8594_delete_connpid_path">delete(ConnPid, Path) → delete(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_connpid_path_headers_8594_delete_connpid_path_headers">delete(ConnPid, Path, Headers) → delete(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_connpid_path_headers_reqopts_8594_streamref">delete(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Delete a resource.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_connpid_path_8594_get_connpid_path">get(ConnPid, Path) → get(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_connpid_path_headers_8594_get_connpid_path_headers">get(ConnPid, Path, Headers) → get(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_connpid_path_headers_reqopts_8594_streamref">get(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Get a resource.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_head_connpid_path_8594_head_connpid_path">head(ConnPid, Path) → head(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_head_connpid_path_headers_8594_head_connpid_path_headers">head(ConnPid, Path, Headers) → head(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_head_connpid_path_headers_reqopts_8594_streamref">head(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Get headers of a resource.</p></div>
-<div class="paragraph"><p>This function performs the same operation as <code>get/{2,3}</code> except
-the server will not send the resource representation, only the
-response’s status line and headers.</p></div>
-<div class="paragraph"><p>While servers should send the same headers they would if the
-request was a GET, like <code>content-length</code>, it is not always
-the case and differences may exist.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options_connpid_path_8594_options_connpid_path">options(ConnPid, Path) → options(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options_connpid_path_headers_8594_options_connpid_path_headers">options(ConnPid, Path, Headers) → options(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options_connpid_path_headers_reqopts_8594_streamref">options(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Obtain information about the capabilities of the server or of a resource.</p></div>
-<div class="paragraph"><p>The special path <code>"*"</code> can be used to obtain information about
-the server as a whole. Any other path will return information
-about the resource only.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_patch_connpid_path_headers_8594_streamref">patch(ConnPid, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>The body sent in this request should be a patch document
-with instructions on how to update the resource.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_patch_connpid_path_headers_body_8594_patch_connpid_path_headers_body">patch(ConnPid, Path, Headers, Body) → patch(ConnPid, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:patch/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_patch_connpid_path_headers_body_reqopts_8594_streamref">patch(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The body sent in this request should be a patch document
-with instructions on how to update the resource.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_post_connpid_path_headers_8594_streamref">post(ConnPid, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>The body sent in this request will be processed
-according to the resource’s own semantics. A new
-resource may be created as a result, and may be
-located at a different URI.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_post_connpid_path_headers_body_8594_post_connpid_path_headers_body">post(ConnPid, Path, Headers, Body) → post(ConnPid, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:post/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_post_connpid_path_headers_body_reqopts_8594_streamref">post(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The body sent in this request will be processed
-according to the resource’s own semantics. A new
-resource may be created as a result, and may be
-located at a different URI.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_put_connpid_path_headers_8594_streamref">put(ConnPid, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Create or replace a resource.</p></div>
-<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_put_connpid_path_headers_body_8594_put_connpid_path_headers_body">put(ConnPid, Path, Headers, Body) → put(ConnPid, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:put/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_put_connpid_path_headers_body_reqopts_8594_streamref">put(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Create or replace a resource.</p></div>
-<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_request_connpid_method_path_headers_8594_streamref">request(ConnPid, Method, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Method = iodata()
-</dt>
-<dd>
-<p>
-Request method.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform the given request.</p></div>
-<div class="paragraph"><p>This is a general purpose function that should only be used
-when existing method-specific functions don’t apply.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_request_connpid_method_path_headers_body_8594_request_connpid_method_path_headers_body">request(ConnPid, Method, Path, Headers, Body) → request(ConnPid, Method, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:request/6</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_request_connpid_method_path_headers_body_reqopts_8594_streamref">request(ConnPid, Method, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Method = iodata()
-</dt>
-<dd>
-<p>
-Request method.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform the given request.</p></div>
-<div class="paragraph"><p>This is a general purpose function that should only be used
-when existing method-specific functions don’t apply.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_data_connpid_streamref_isfin_data_8594_ok">data(ConnPid, StreamRef, IsFin, Data) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream this data belongs to.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the request.
-</p>
-</dd>
-<dt class="hdlist1">
-Data = iodata()
-</dt>
-<dd>
-<p>
-Data to be sent with the request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stream the body of a request.</p></div>
-<div class="paragraph"><p>@todo empty chunks</p></div>
-<div class="paragraph"><p>This function can only be used if the request identified by
-<code>StreamRef</code> came with headers indicating the presence of a
-body and that body not being given when creating the request.</p></div>
-<div class="paragraph"><p>All calls to this function must use <code>nofin</code> except for the
-last which must use <code>fin</code> to indicate the end of the request
-body.</p></div>
-<div class="paragraph"><p>Empty data is allowed regardless of the value of <code>IsFin</code>.
-Gun will not send empty data chunks unless required to
-indicate the request body is finished, however.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_monitorref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef, MonitorRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_timeout_8594_await_connpid_streamref_timeout_monitorref">await(ConnPid, StreamRef, Timeout) → await(ConnPid, StreamRef, Timeout, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_timeout_monitorref_8594_tuple_8201_8212_8201_see_below">await(ConnPid, StreamRef, Timeout, MonitorRef) → tuple() — see below</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream to await messages from.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-How long this function will wait for messages.
-</p>
-</dd>
-<dt class="hdlist1">
-MonitorRef = reference()
-</dt>
-<dd>
-<p>
-Monitor reference for the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Wait for a response message.</p></div>
-<div class="paragraph"><p>This function can be used when a synchronous handling of
-responses is desired. It will only return when a message
-for the given stream is received, on error or on timeout.</p></div>
-<div class="paragraph"><p>The return values are described in the next few subsections.</p></div>
-<div class="sect3">
-<h4 id="_response_isfin_status_headers">{response, IsFin, Status, Headers}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Status = binary()
-</dt>
-<dd>
-<p>
-Status line for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers sent with the response.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_response</code> message.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_data_isfin_data">{data, IsFin, Data}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Data = binary()
-</dt>
-<dd>
-<p>
-Data from the stream.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_data</code> message.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_push_newstreamref_uri_headers">{push, NewStreamRef, URI, Headers}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-NewStreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream being pushed.
-</p>
-</dd>
-<dt class="hdlist1">
-URI = binary()
-</dt>
-<dd>
-<p>
-URI of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers @todo
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_push</code> message.</p></div>
-<div class="paragraph"><p>@todo Same changes as gun_push</p></div>
-</div>
-<div class="sect3">
-<h4 id="_error_reason">{error, Reason}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason. @todo any?
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_error</code> message.</p></div>
-<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error,
-@todo a DOWN and a timeout error</p></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_monitorref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef, MonitorRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_timeout_8594_await_body_connpid_streamref_timeout_monitorref">await_body(ConnPid, StreamRef, Timeout) → await_body(ConnPid, StreamRef, Timeout, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_timeout_monitorref_8594_ok_body_error_reason">await_body(ConnPid, StreamRef, Timeout, MonitorRef) → {ok, Body} | {error, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream to await messages from.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-How long this function will wait for each message.
-</p>
-</dd>
-<dt class="hdlist1">
-MonitorRef = reference()
-</dt>
-<dd>
-<p>
-Monitor reference for the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = binary()
-</dt>
-<dd>
-<p>
-Body for the given stream.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason. @todo any?
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Wait for a response body.</p></div>
-<div class="paragraph"><p>This function can be used when a synchronous handling of
-responses is desired. It will only return when it has
-finished fetching the entire response body.</p></div>
-<div class="paragraph"><p>The timeout value is <strong>per message</strong>. The actual function call
-can last much longer for large bodies.</p></div>
-<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error,
-@todo a DOWN and a timeout error</p></div>
-<div class="paragraph"><p>@todo guide might be a little incorrect about await/await_body</p></div>
-</div>
-<div class="sect2">
-<h3 id="_flush_connpid_8594_ok">flush(ConnPid) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Flush all messages from the Gun connection process from the mailbox.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_flush_streamref_8594_ok">flush(StreamRef) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Stream identifier.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Flush all messages related to the given stream.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_cancel_connpid_streamref_8594_ok">cancel(ConnPid, StreamRef) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream to cancel.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Cancel the given stream.</p></div>
-<div class="paragraph"><p>HTTP/1.1 streams can’t be cancelled. Gun will simply silence
-the stream and stop relaying messages.</p></div>
-<div class="paragraph"><p>@todo Depending on the length
-@todo of a response Gun may also attempt to reconnect rather than
-@todo receive the entire response body.</p></div>
-<div class="paragraph"><p>HTTP/2 streams can however be cancelled at any time.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_upgrade_connpid_path_8594_ws_upgrade_connpid_path">ws_upgrade(ConnPid, Path) → ws_upgrade(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:ws_upgrade/3</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_upgrade_connpid_path_headers_8594_ok">ws_upgrade(ConnPid, Path, Headers) → ok</h3>
-<div class="paragraph"><p>Similar to <code>gun:ws_upgrade/4</code>, except <code>WsOpts</code> is taken from
-the options given in the <code>gun:open/{2,3}</code> call when opening
-the connection.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_upgrade_connpid_path_headers_wsopts_8594_ok">ws_upgrade(ConnPid, Path, Headers, WsOpts) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-WsOpts = map()
-</dt>
-<dd>
-<p>
-Options for the Websocket connection.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Request the connection to be upgraded to the Websocket protocol.</p></div>
-<div class="paragraph"><p>This function can only be used when the current protocol is <code>http</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_send_connpid_frames_8594_ok">ws_send(ConnPid, Frames) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Frames = @todo
-</dt>
-<dd>
-<p>
-@todo
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send one or more Websocket frames.</p></div>
-<div class="paragraph"><p>This function can only be used following a successful <code>ws_upgrade</code> call.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>gun - asynchronous HTTP client</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun</code> module provides an asynchronous interface for +connecting and communicating with Web servers over HTTP, +HTTP/2 or Websocket.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_opts_map">opts() = map()</h3> +<div class="paragraph"><p>Configuration for the connection.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +connect_timeout ⇒ timeout() +</dt> +<dd> +<p> + Connection timeout. Defaults to <code>infinity</code>. +</p> +</dd> +<dt class="hdlist1"> +http_opts ⇒ http_opts() +</dt> +<dd> +<p> + Options specific to the HTTP protocol. See below. +</p> +</dd> +<dt class="hdlist1"> +http2_opts ⇒ http2_opts() +</dt> +<dd> +<p> + Options specific to the HTTP/2 protocol. See below. +</p> +</dd> +<dt class="hdlist1"> +protocols ⇒ [http | http2] +</dt> +<dd> +<p> + Ordered list of preferred protocols. When the transport is tcp, + this list must contain exactly one protocol. When the transport + is ssl, this list must contain at least one protocol and will be + used using the ALPN protocol negotiation method. When the server + does not support ALPN then http will always be used. Defaults to + [http] when the transport is tcp, and [http2, http] when the + transport is ssl. +</p> +</dd> +<dt class="hdlist1"> +retry ⇒ non_neg_integer() +</dt> +<dd> +<p> + Number of times Gun will try to reconnect on failure before giving up. + Defaults to 5. +</p> +</dd> +<dt class="hdlist1"> +retry_timeout ⇒ pos_integer() +</dt> +<dd> +<p> + Time between retries in milliseconds. Defaults to 5000. +</p> +</dd> +<dt class="hdlist1"> +trace ⇒ boolean() +</dt> +<dd> +<p> + Whether to enable <code>dbg</code> tracing of the connection process. Should + only be used during debugging. Defaults to false. +</p> +</dd> +<dt class="hdlist1"> +transport ⇒ tcp | ssl +</dt> +<dd> +<p> + Whether to use SSL or plain TCP. The default varies depending on the + port used. Port 443 defaults to ssl. All other ports default to tcp. +</p> +</dd> +<dt class="hdlist1"> +transport_opts ⇒ proplists:proplist() +</dt> +<dd> +<p> + Transport options. They are TCP options or SSL options depending on + the selected transport. +</p> +</dd> +<dt class="hdlist1"> +ws_opts ⇒ ws_opts() +</dt> +<dd> +<p> + Options specific to the Websocket protocol. See below. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_http_opts_map">http_opts() = map()</h3> +<div class="paragraph"><p>Configuration for the HTTP protocol.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +keepalive ⇒ timeout() +</dt> +<dd> +<p> + Time between pings in milliseconds. Since the HTTP protocol has + no standardized way to ping the server, Gun will simply send an + empty line when the connection is idle. Gun only makes a best + effort here as servers usually have configurable limits to drop + idle connections. Use <code>infinity</code> to disable. Defaults to 5000. +</p> +</dd> +<dt class="hdlist1"> +transform_header_name ⇒ funLowercaseName :: binary( → TransformedName :: binary()) | undefined +</dt> +<dd> +<p> + A function that will be applied to all header names before they + are sent to the server. Gun assumes that all header names are in + lower case. This function is useful if you, for example, need to + re-case header names in the event that the server incorrectly + considers header name case to be significant. +</p> +</dd> +<dt class="hdlist1"> +version ⇒ <em>HTTP/1.1</em> | <em>HTTP/1.0</em> +</dt> +<dd> +<p> + HTTP version to use. Defaults to <em>HTTP/1.1</em>. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_http2_opts_map">http2_opts() = map()</h3> +<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +keepalive ⇒ pos_integer() +</dt> +<dd> +<p> + Time between pings in milliseconds. Defaults to 5000. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_req_opts_map">req_opts() = map()</h3> +<div class="paragraph"><p>Configuration for a particular request.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +reply_to ⇒ pid() +</dt> +<dd> +<p> + The pid of a process that is responsible for the response handling. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_ws_opts_map">ws_opts() = map()</h3> +<div class="paragraph"><p>Configuration for the Websocket protocol.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +compress ⇒ boolean() +</dt> +<dd> +<p> + Whether to enable permessage-deflate compression. This does + not guarantee that compression will be used as it is the + server that ultimately decides. Defaults to false. +</p> +</dd> +</dl></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_messages">Messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Calling functions from this module may result in the following +messages being sent.</p></div> +<div class="sect2"> +<h3 id="_gun_up_connpid_protocol">{gun_up, ConnPid, Protocol}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Protocol = http | http2 +</dt> +<dd> +<p> +The protocol selected for this connection. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>The connection is up.</p></div> +<div class="paragraph"><p>This message informs the owner process that the connection or +reconnection completed.</p></div> +<div class="paragraph"><p>The protocol selected during the connection is sent in this +message. It can be used to determine the capabilities of the +server.</p></div> +<div class="paragraph"><p>Gun will now start processing the messages it received while +waiting for the connection to be up. If this is a reconnection, +then this may not be desirable for all requests. Those requests +should be cancelled when the connection goes down, and any +subsequent messages ignored.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_down_connpid_protocol_reason_killedstreams_unprocessedstreams">{gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Protocol = http | http2 | ws +</dt> +<dd> +<p> +The protocol in use when the connection was lost. +</p> +</dd> +<dt class="hdlist1"> +Reason = normal | closed | {error, atom()} +</dt> +<dd> +<p> +The reason for the loss of the connection. +</p> +</dd> +<dt class="hdlist1"> +KilledStreams = [reference()] +</dt> +<dd> +<p> +List of streams that have been brutally terminated. +</p> +</dd> +<dt class="hdlist1"> +UnprocessedStreams = [reference()] +</dt> +<dd> +<p> +List of streams that have not been processed by the server. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>The connection is down.</p></div> +<div class="paragraph"><p>This message informs the owner process that the connection is +currently down. Gun will automatically attempt to reconnect +depending on the <code>retry</code> and <code>retry_timeout</code> options.</p></div> +<div class="paragraph"><p>The reason of the termination is there for debugging purposes +only. You should not rely on this value to know what streams +were processed or completed.</p></div> +<div class="paragraph"><p>The <em>killed streams</em> are the active streams that did not complete +before the closing of the connection. Whether they can be retried +safely depends on the protocol used and the idempotence property +of the requests.</p></div> +<div class="paragraph"><p>The <em>unprocessed streams</em> are streams that the server did not +start processing yet. They may be retried safely depending on +what streams were killed before.</p></div> +<div class="paragraph"><p>When the connection goes back up, Gun will not attempt to retry +requests. It will also not upgrade to Websocket automatically +if that was the protocol in use when the connection was lost.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_push_connpid_streamref_newstreamref_uri_headers">{gun_push, ConnPid, StreamRef, NewStreamRef, URI, Headers}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream initiated by the owner process. +</p> +</dd> +<dt class="hdlist1"> +NewStreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream being pushed. +</p> +</dd> +<dt class="hdlist1"> +URI = binary() +</dt> +<dd> +<p> +URI of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers @todo +</p> +</dd> +</dl></div> +<div class="paragraph"><p>A resource pushed alongside an HTTP response.</p></div> +<div class="paragraph"><p>This message can only be sent when the protocol is HTTP/2.</p></div> +<div class="paragraph"><p>@todo I fear we also need the scheme; resource is identified by URI +@todo Perhaps we really should send the URI entirely, because cache +@todo relies on URI to work and this feature is for caching… +@todo Not sure why Method is there, spec says it is only for GET</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_response_connpid_streamref_isfin_status_headers">{gun_response, ConnPid, StreamRef, IsFin, Status, Headers}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream initiated by the owner process. +</p> +</dd> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Status = binary() +</dt> +<dd> +<p> +Status line for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers sent with the response. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>A response to an HTTP request.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_data_connpid_streamref_isfin_data">{gun_data, ConnPid, StreamRef, IsFin, Data}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream this data belongs to. +</p> +</dd> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Data = binary() +</dt> +<dd> +<p> +Data from the stream. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Data associated with a stream.</p></div> +<div class="paragraph"><p>The stream in question can be either one initiated by the owner +process or a stream initiated by the server through the push +mechanism. In any case a <code>gun_response</code> or a <code>gun_push</code> message +will be sent before any <code>gun_data</code> message.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_error_connpid_streamref_reason">{gun_error, ConnPid, StreamRef, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream this error relates to. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stream-specific error.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_error_connpid_reason">{gun_error, ConnPid, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>General error.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_ws_upgrade_connpid_ok_headers">{gun_ws_upgrade, ConnPid, ok, Headers}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers sent with the response. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Successful upgrade to the Websocket protocol.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_ws_connpid_frame">{gun_ws, ConnPid, Frame}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Frame = @todo +</dt> +<dd> +<p> +Frame. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Websocket frame.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_open_host_port_8594_open_host_port">open(Host, Port) → open(Host, Port, [])</h3> +<div class="paragraph"><p>Alias of <code>gun:open/3</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_open_host_port_opts_8594_ok_connpid_error_reason">open(Host, Port, Opts) → {ok, ConnPid} | {error, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Host = inet:hostname() +</dt> +<dd> +<p> +Host to connect to. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port to connect to. +</p> +</dd> +<dt class="hdlist1"> +Opts = opts() +</dt> +<dd> +<p> +Options for this connection. +</p> +</dd> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. @todo really any? +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Open a connection to the given host and port.</p></div> +</div> +<div class="sect2"> +<h3 id="_close_connpid_8594_ok">close(ConnPid) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Brutally close the connection.</p></div> +</div> +<div class="sect2"> +<h3 id="_shutdown_connpid_8594_ok">shutdown(ConnPid) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Gracefully close the connection.</p></div> +<div class="paragraph"><p>A monitor can be used to be notified when the connection is +effectively closed.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_connpid_path_8594_delete_connpid_path">delete(ConnPid, Path) → delete(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_connpid_path_headers_8594_delete_connpid_path_headers">delete(ConnPid, Path, Headers) → delete(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_connpid_path_headers_reqopts_8594_streamref">delete(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Delete a resource.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_connpid_path_8594_get_connpid_path">get(ConnPid, Path) → get(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_connpid_path_headers_8594_get_connpid_path_headers">get(ConnPid, Path, Headers) → get(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_connpid_path_headers_reqopts_8594_streamref">get(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Get a resource.</p></div> +</div> +<div class="sect2"> +<h3 id="_head_connpid_path_8594_head_connpid_path">head(ConnPid, Path) → head(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_head_connpid_path_headers_8594_head_connpid_path_headers">head(ConnPid, Path, Headers) → head(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_head_connpid_path_headers_reqopts_8594_streamref">head(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Get headers of a resource.</p></div> +<div class="paragraph"><p>This function performs the same operation as <code>get/{2,3}</code> except +the server will not send the resource representation, only the +response’s status line and headers.</p></div> +<div class="paragraph"><p>While servers should send the same headers they would if the +request was a GET, like <code>content-length</code>, it is not always +the case and differences may exist.</p></div> +</div> +<div class="sect2"> +<h3 id="_options_connpid_path_8594_options_connpid_path">options(ConnPid, Path) → options(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_options_connpid_path_headers_8594_options_connpid_path_headers">options(ConnPid, Path, Headers) → options(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_options_connpid_path_headers_reqopts_8594_streamref">options(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Obtain information about the capabilities of the server or of a resource.</p></div> +<div class="paragraph"><p>The special path <code>"*"</code> can be used to obtain information about +the server as a whole. Any other path will return information +about the resource only.</p></div> +</div> +<div class="sect2"> +<h3 id="_patch_connpid_path_headers_8594_streamref">patch(ConnPid, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>The body sent in this request should be a patch document +with instructions on how to update the resource.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_patch_connpid_path_headers_body_8594_patch_connpid_path_headers_body">patch(ConnPid, Path, Headers, Body) → patch(ConnPid, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:patch/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_patch_connpid_path_headers_body_reqopts_8594_streamref">patch(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The body sent in this request should be a patch document +with instructions on how to update the resource.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_post_connpid_path_headers_8594_streamref">post(ConnPid, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>The body sent in this request will be processed +according to the resource’s own semantics. A new +resource may be created as a result, and may be +located at a different URI.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_post_connpid_path_headers_body_8594_post_connpid_path_headers_body">post(ConnPid, Path, Headers, Body) → post(ConnPid, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:post/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_post_connpid_path_headers_body_reqopts_8594_streamref">post(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The body sent in this request will be processed +according to the resource’s own semantics. A new +resource may be created as a result, and may be +located at a different URI.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_put_connpid_path_headers_8594_streamref">put(ConnPid, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Create or replace a resource.</p></div> +<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_put_connpid_path_headers_body_8594_put_connpid_path_headers_body">put(ConnPid, Path, Headers, Body) → put(ConnPid, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:put/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_put_connpid_path_headers_body_reqopts_8594_streamref">put(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Create or replace a resource.</p></div> +<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_request_connpid_method_path_headers_8594_streamref">request(ConnPid, Method, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Method = iodata() +</dt> +<dd> +<p> +Request method. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform the given request.</p></div> +<div class="paragraph"><p>This is a general purpose function that should only be used +when existing method-specific functions don’t apply.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_request_connpid_method_path_headers_body_8594_request_connpid_method_path_headers_body">request(ConnPid, Method, Path, Headers, Body) → request(ConnPid, Method, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:request/6</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_request_connpid_method_path_headers_body_reqopts_8594_streamref">request(ConnPid, Method, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Method = iodata() +</dt> +<dd> +<p> +Request method. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform the given request.</p></div> +<div class="paragraph"><p>This is a general purpose function that should only be used +when existing method-specific functions don’t apply.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_data_connpid_streamref_isfin_data_8594_ok">data(ConnPid, StreamRef, IsFin, Data) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream this data belongs to. +</p> +</dd> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the request. +</p> +</dd> +<dt class="hdlist1"> +Data = iodata() +</dt> +<dd> +<p> +Data to be sent with the request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stream the body of a request.</p></div> +<div class="paragraph"><p>@todo empty chunks</p></div> +<div class="paragraph"><p>This function can only be used if the request identified by +<code>StreamRef</code> came with headers indicating the presence of a +body and that body not being given when creating the request.</p></div> +<div class="paragraph"><p>All calls to this function must use <code>nofin</code> except for the +last which must use <code>fin</code> to indicate the end of the request +body.</p></div> +<div class="paragraph"><p>Empty data is allowed regardless of the value of <code>IsFin</code>. +Gun will not send empty data chunks unless required to +indicate the request body is finished, however.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_monitorref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef, MonitorRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_timeout_8594_await_connpid_streamref_timeout_monitorref">await(ConnPid, StreamRef, Timeout) → await(ConnPid, StreamRef, Timeout, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_timeout_monitorref_8594_tuple_8201_8212_8201_see_below">await(ConnPid, StreamRef, Timeout, MonitorRef) → tuple() — see below</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream to await messages from. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +How long this function will wait for messages. +</p> +</dd> +<dt class="hdlist1"> +MonitorRef = reference() +</dt> +<dd> +<p> +Monitor reference for the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Wait for a response message.</p></div> +<div class="paragraph"><p>This function can be used when a synchronous handling of +responses is desired. It will only return when a message +for the given stream is received, on error or on timeout.</p></div> +<div class="paragraph"><p>The return values are described in the next few subsections.</p></div> +<div class="sect3"> +<h4 id="_response_isfin_status_headers">{response, IsFin, Status, Headers}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Status = binary() +</dt> +<dd> +<p> +Status line for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers sent with the response. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_response</code> message.</p></div> +</div> +<div class="sect3"> +<h4 id="_data_isfin_data">{data, IsFin, Data}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Data = binary() +</dt> +<dd> +<p> +Data from the stream. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_data</code> message.</p></div> +</div> +<div class="sect3"> +<h4 id="_push_newstreamref_uri_headers">{push, NewStreamRef, URI, Headers}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +NewStreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream being pushed. +</p> +</dd> +<dt class="hdlist1"> +URI = binary() +</dt> +<dd> +<p> +URI of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers @todo +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_push</code> message.</p></div> +<div class="paragraph"><p>@todo Same changes as gun_push</p></div> +</div> +<div class="sect3"> +<h4 id="_error_reason">{error, Reason}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. @todo any? +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_error</code> message.</p></div> +<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error</p></div> +</div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_monitorref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef, MonitorRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_timeout_8594_await_body_connpid_streamref_timeout_monitorref">await_body(ConnPid, StreamRef, Timeout) → await_body(ConnPid, StreamRef, Timeout, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_timeout_monitorref_8594_ok_body_error_reason">await_body(ConnPid, StreamRef, Timeout, MonitorRef) → {ok, Body} | {error, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream to await messages from. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +How long this function will wait for each message. +</p> +</dd> +<dt class="hdlist1"> +MonitorRef = reference() +</dt> +<dd> +<p> +Monitor reference for the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Body = binary() +</dt> +<dd> +<p> +Body for the given stream. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. @todo any? +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Wait for a response body.</p></div> +<div class="paragraph"><p>This function can be used when a synchronous handling of +responses is desired. It will only return when it has +finished fetching the entire response body.</p></div> +<div class="paragraph"><p>The timeout value is <strong>per message</strong>. The actual function call +can last much longer for large bodies.</p></div> +<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error</p></div> +<div class="paragraph"><p>@todo guide might be a little incorrect about await/await_body</p></div> +</div> +<div class="sect2"> +<h3 id="_flush_connpid_8594_ok">flush(ConnPid) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Flush all messages from the Gun connection process from the mailbox.</p></div> +</div> +<div class="sect2"> +<h3 id="_flush_streamref_8594_ok">flush(StreamRef) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Stream identifier. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Flush all messages related to the given stream.</p></div> +</div> +<div class="sect2"> +<h3 id="_cancel_connpid_streamref_8594_ok">cancel(ConnPid, StreamRef) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream to cancel. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Cancel the given stream.</p></div> +<div class="paragraph"><p>HTTP/1.1 streams can’t be cancelled. Gun will simply silence +the stream and stop relaying messages.</p></div> +<div class="paragraph"><p>@todo Depending on the length +@todo of a response Gun may also attempt to reconnect rather than +@todo receive the entire response body.</p></div> +<div class="paragraph"><p>HTTP/2 streams can however be cancelled at any time.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_upgrade_connpid_path_8594_ws_upgrade_connpid_path">ws_upgrade(ConnPid, Path) → ws_upgrade(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:ws_upgrade/3</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_upgrade_connpid_path_headers_8594_ok">ws_upgrade(ConnPid, Path, Headers) → ok</h3> +<div class="paragraph"><p>Similar to <code>gun:ws_upgrade/4</code>, except <code>WsOpts</code> is taken from +the options given in the <code>gun:open/{2,3}</code> call when opening +the connection.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_upgrade_connpid_path_headers_wsopts_8594_ok">ws_upgrade(ConnPid, Path, Headers, WsOpts) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +WsOpts = map() +</dt> +<dd> +<p> +Options for the Websocket connection. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Request the connection to be upgraded to the Websocket protocol.</p></div> +<div class="paragraph"><p>This function can only be used when the current protocol is <code>http</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_send_connpid_frames_8594_ok">ws_send(ConnPid, Frames) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Frames = @todo +</dt> +<dd> +<p> +@todo +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send one or more Websocket frames.</p></div> +<div class="paragraph"><p>This function can only be used following a successful <code>ws_upgrade</code> call.</p></div> +</div> +</div> +</div> diff --git a/docs/en/gun/1.0/manual/gun_app/index.html b/docs/en/gun/1.0/manual/gun_app/index.html index be525d51..5690ca2b 100644 --- a/docs/en/gun/1.0/manual/gun_app/index.html +++ b/docs/en/gun/1.0/manual/gun_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: gun(7)</title> @@ -67,34 +67,34 @@ <h1 class="lined-header"><span>gun(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>gun - Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>gun</code> application uses the Erlang applications <code>ranch</code>
-for abstracting TCP and TLS over a common interface, and
-the <code>ssl</code> application for TLS support, required for HTTPS
-and secure HTTP/2 support. In addition, Gun requires the <code>crypto</code>
-application (a dependency of <code>ssl</code>) for Websocket.</p></div>
-<div class="paragraph"><p>These dependencies must be started for the <code>gun</code>
-application to work. In an embedded environment
-this means that they need to be started with the
-<code>application:start/{1,2}</code> function before the <code>gun</code>
-application is started.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>gun</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>gun - Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun</code> application uses the Erlang applications <code>ranch</code> +for abstracting TCP and TLS over a common interface, and +the <code>ssl</code> application for TLS support, required for HTTPS +and secure HTTP/2 support. In addition, Gun requires the <code>crypto</code> +application (a dependency of <code>ssl</code>) for Websocket.</p></div> +<div class="paragraph"><p>These dependencies must be started for the <code>gun</code> +application to work. In an embedded environment +this means that they need to be started with the +<code>application:start/{1,2}</code> function before the <code>gun</code> +application is started.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun</code> application does not define any application +environment configuration parameters.</p></div> +</div> +</div> diff --git a/docs/en/gun/1.0/manual/index.html b/docs/en/gun/1.0/manual/index.html index 411e92f0..c3851885 100644 --- a/docs/en/gun/1.0/manual/index.html +++ b/docs/en/gun/1.0/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Gun Function Reference</title> @@ -67,18 +67,18 @@ <h1 class="lined-header"><span>Gun Function Reference</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="gun_app">gun(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="gun">gun(3)</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="gun_app">gun(7)</a> +</p> +</li> +<li> +<p> +<a href="gun">gun(3)</a> +</p> +</li> +</ul></div> diff --git a/docs/en/gun/index.html b/docs/en/gun/index.html index d87c4243..0194031a 100644 --- a/docs/en/gun/index.html +++ b/docs/en/gun/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/index.html b/docs/en/index.html index d87c4243..0194031a 100644 --- a/docs/en/index.html +++ b/docs/en/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/ranch/1.2/guide/embedded/index.html b/docs/en/ranch/1.2/guide/embedded/index.html index ac94bf2a..ff2cf499 100644 --- a/docs/en/ranch/1.2/guide/embedded/index.html +++ b/docs/en/ranch/1.2/guide/embedded/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Embedded mode</title> @@ -67,54 +67,57 @@ <h1 class="lined-header"><span>Embedded mode</span></h1> -<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly
-in your supervision tree. This allows for greater fault tolerance
-control by permitting the shutdown of a listener due to the
-failure of another part of the application and vice versa.</p></div>
-<div class="sect1">
-<h2 id="_embedding">Embedding</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs
-to your supervision tree. This can all be done in the <code>init/1</code> function
-of one of your application supervisors.</p></div>
-<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding.
-First, you need to add <code>ranch_sup</code> to your supervision tree, only once,
-regardless of the number of listeners you will use. Then you need to
-add the child specs for each listener.</p></div>
-<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs
-called <code>ranch:child_spec/6</code>, that works like <code>ranch:start_listener/6</code>,
-except that it doesn’t start anything, it only returns child specs.</p></div>
-<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a
-convenience function.</p></div>
-<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another
-application’s supervision tree.</p></div>
-<div class="listingblock">
-<div class="title">Embed Ranch directly in your supervision tree</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">init</span></span>([]) <span style="color: #990000">-></span>
- <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []},
- <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]},
- <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
- ),
- {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only
-one <code>ranch_sup</code> spec!</p></div>
-<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners
-are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for
-more details on how Ranch does it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa.</p></div> +<div class="sect1"> +<h2 id="_embedding">Embedding</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the <code>init/1</code> function +of one of your application supervisors.</p></div> +<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add <code>ranch_sup</code> to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener.</p></div> +<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs +called <code>ranch:child_spec/6</code>, that works like <code>ranch:start_listener/6</code>, +except that it doesn’t start anything, it only returns child specs.</p></div> +<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a +convenience function.</p></div> +<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another +application’s supervision tree.</p></div> +<div class="listingblock"> +<div class="title">Embed Ranch directly in your supervision tree</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">init</span></span>([]) <span style="color: #990000">-></span> + <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []}, + <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]}, + <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] + ), + {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only +one <code>ranch_sup</code> spec!</p></div> +<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners +are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for +more details on how Ranch does it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/index.html b/docs/en/ranch/1.2/guide/index.html index 2b1b7e05..cd37ce05 100644 --- a/docs/en/ranch/1.2/guide/index.html +++ b/docs/en/ranch/1.2/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch User Guide</title> @@ -67,48 +67,48 @@ <h1 class="lined-header"><span>Ranch User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<a href="transports/">Transports</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="embedded/">Embedded mode</a>
-</p>
-</li>
-<li>
-<p>
-<a href="parsers/">Writing parsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ssl_auth/">SSL client authentication</a>
-</p>
-</li>
-<li>
-<p>
-<a href="internals/">Internals</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="listeners/">Listeners</a> +</p> +</li> +<li> +<p> +<a href="transports/">Transports</a> +</p> +</li> +<li> +<p> +<a href="protocols/">Protocols</a> +</p> +</li> +<li> +<p> +<a href="embedded/">Embedded mode</a> +</p> +</li> +<li> +<p> +<a href="parsers/">Writing parsers</a> +</p> +</li> +<li> +<p> +<a href="ssl_auth/">SSL client authentication</a> +</p> +</li> +<li> +<p> +<a href="internals/">Internals</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.2/guide/internals/index.html b/docs/en/ranch/1.2/guide/internals/index.html index 88466f8e..0f731816 100644 --- a/docs/en/ranch/1.2/guide/internals/index.html +++ b/docs/en/ranch/1.2/guide/internals/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Internals</title> @@ -67,99 +67,102 @@ <h1 class="lined-header"><span>Internals</span></h1> -<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you
-to use an architecture specific to your application, which may or may
-not be compatible with the description of the Ranch application.</p></div>
-<div class="paragraph"><p>Note that for everything related to efficiency and performance,
-you should perform the benchmarks yourself to get the numbers that
-matter to you. Generic benchmarks found on the web may or may not
-be of use to you, you can never know until you benchmark your own
-system.</p></div>
-<div class="sect1">
-<h2 id="_architecture">Architecture</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is an OTP application.</p></div>
-<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible
-for supervising the <code>ranch_server</code> process and all the listeners that
-will be started.</p></div>
-<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the
-listeners and their acceptors. It does so through the use of a public ets
-table called <code>ranch_server</code>. The table is owned by the top supervisor
-to improve fault tolerance. This way if the <code>ranch_server</code> gen_server
-fails, it doesn’t lose any information and the restarted process can
-continue as if nothing happened.</p></div>
-<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor
-keeps track of the number of connections and handles connection limits
-directly. While it is heavily optimized to perform the task of creating
-connection processes for accepted connections, it is still following the
-OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on
-it as expected.</p></div>
-<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and
-consist of three kinds of processes: the listener gen_server, the
-acceptor processes and the connection processes, both grouped under
-their own supervisor. All of these processes are registered to the
-<code>ranch_server</code> gen_server with varying amount of information.</p></div>
-<div class="paragraph"><p>All socket operations, including listening for connections, go through
-transport handlers. Accepted connections are given to the protocol handler.
-Transport handlers are simple callback modules for performing operations on
-sockets. Protocol handlers start a new process, which receives socket
-ownership, with no requirements on how the code should be written inside
-that new process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_number_of_acceptors">Number of acceptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The second argument to <code>ranch:start_listener/6</code> is the number of
-processes that will be accepting connections. Care should be taken
-when choosing this number.</p></div>
-<div class="paragraph"><p>First of all, it should not be confused with the maximum number
-of connections. Acceptor processes are only used for accepting and
-have nothing else in common with connection processes. Therefore
-there is nothing to be gained from setting this number too high,
-in fact it can slow everything else down.</p></div>
-<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept
-connections concurrently. But the number of cores available doesn’t
-seem to be the only factor for choosing this number, as we can
-observe faster accepts if we have more acceptors than cores. It
-might be entirely dependent on the protocol, however.</p></div>
-<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware
-is a good solution, as it’s big enough to always have acceptors ready
-and it’s low enough that it doesn’t have a negative impact on the
-system’s performances.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>.
-They can be of interest because they generally are related to
-optimizations provided by the underlying OS. They can still be enabled
-thanks to the <code>raw</code> option, for which we will see an example.</p></div>
-<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified
-accept mechanism which will wait for application data to come in before
-handing out the connection to the Erlang process.</p></div>
-<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly
-idle, perhaps part of a connection pool. They can be handled by the
-kernel directly until they send any real data, instead of allocating
-resources to idle connections.</p></div>
-<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div>
-<div class="listingblock">
-<div class="title">Using raw transport 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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div>
-<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application.</p></div> +<div class="paragraph"><p>Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system.</p></div> +<div class="sect1"> +<h2 id="_architecture">Architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is an OTP application.</p></div> +<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the <code>ranch_server</code> process and all the listeners that +will be started.</p></div> +<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called <code>ranch_server</code>. The table is owned by the top supervisor +to improve fault tolerance. This way if the <code>ranch_server</code> gen_server +fails, it doesn’t lose any information and the restarted process can +continue as if nothing happened.</p></div> +<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on +it as expected.</p></div> +<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +<code>ranch_server</code> gen_server with varying amount of information.</p></div> +<div class="paragraph"><p>All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_number_of_acceptors">Number of acceptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The second argument to <code>ranch:start_listener/6</code> is the number of +processes that will be accepting connections. Care should be taken +when choosing this number.</p></div> +<div class="paragraph"><p>First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down.</p></div> +<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn’t +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however.</p></div> +<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it’s big enough to always have acceptors ready +and it’s low enough that it doesn’t have a negative impact on the +system’s performances.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the <code>raw</code> option, for which we will see an example.</p></div> +<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process.</p></div> +<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections.</p></div> +<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div> +<div class="listingblock"> +<div class="title">Using raw transport 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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div> +<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/introduction/index.html b/docs/en/ranch/1.2/guide/introduction/index.html index 8d2e565c..130721a0 100644 --- a/docs/en/ranch/1.2/guide/introduction/index.html +++ b/docs/en/ranch/1.2/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,38 +67,41 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div>
-<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections
-with a small code base and low latency while being easy to use directly
-as an application or to embed into your own.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience
-with socket programming and TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_supported_platforms">Supported platforms</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is tested and supported on Linux.</p></div>
-<div class="paragraph"><p>Ranch is developed for Erlang R15B01+.</p></div>
-<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code
-modifications but there is no guarantee that it will work as expected.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div>
-</div>
-</div>
+<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div> +<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supported_platforms">Supported platforms</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is tested and supported on Linux.</p></div> +<div class="paragraph"><p>Ranch is developed for Erlang R15B01+.</p></div> +<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/listeners/index.html b/docs/en/ranch/1.2/guide/listeners/index.html index eff0e0ed..83c092a0 100644 --- a/docs/en/ranch/1.2/guide/listeners/index.html +++ b/docs/en/ranch/1.2/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,293 +67,296 @@ <h1 class="lined-header"><span>Listeners</span></h1> -<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port
-for new connections. It manages a pool of acceptor processes, each
-of them indefinitely accepting connections. When it does, it starts
-a new process executing the protocol handler code. All the socket
-programming is abstracted through the user of transport handlers.</p></div>
-<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection
-processes, allowing developers to focus on building their application.</p></div>
-<div class="sect1">
-<h2 id="_starting_a_listener">Starting a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer
-to request that Ranch listens for connections.</p></div>
-<div class="paragraph"><p>A listener can be started and stopped at will.</p></div>
-<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A name to identify it locally and be able to interact with it.
-</p>
-</li>
-<li>
-<p>
-The number of acceptors in the pool.
-</p>
-</li>
-<li>
-<p>
-A transport handler and its associated options.
-</p>
-</li>
-<li>
-<p>
-A protocol handler and its associated options.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively
-<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div>
-<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/6</code>
-function. Before doing so however, you must ensure that the <code>ranch</code>
-application is started.</p></div>
-<div class="listingblock">
-<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will
-have a pool of 100 acceptors, use a TCP transport and forward connections
-to the <code>echo_protocol</code> handler.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on port 5555</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the
-examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em>
-directory and run the following command:</p></div>
-<div class="listingblock">
-<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div>
-<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply
-everything you send to it. Then when you’re done testing, you can use
-the <code>Ctrl+]</code> key to escape to the telnet command line and type
-<code>quit</code> to exit.</p></div>
-<div class="listingblock">
-<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span>
-Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span>
-Connected to localhost<span style="color: #990000">.</span>
-Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span>
-Hello<span style="color: #990000">!</span>
-Hello<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-<span style="color: #990000">^]</span>
-
-telnet<span style="color: #990000">></span> quit
-Connection closed<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stopping_a_listener">Stopping a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All you need to stop a Ranch listener is to call the
-<code>ranch:stop_listener/1</code> function with the listener’s name
-as argument. In the previous section we started the listener
-named <code>tcp_echo</code>. We can now stop it.</p></div>
-<div class="listingblock">
-<div class="title">Stopping a listener</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">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_default_transport_options">Default transport options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the
-options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set.
-These values can’t be overriden when starting the listener, but
-they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div>
-<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which
-can be overriden at listener startup.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_a_random_port">Listening on a random port</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give
-the port number 0, or if you omit the port number entirely, Ranch will
-start listening on a random port.</p></div>
-<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The
-argument is the name of the listener you gave in <code>ranch:start_listener/6</code>.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on a random port</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span>
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons.
-This can easily be identified by an <code>{error, eacces}</code> error when trying
-to open a listening socket on such a port.</p></div>
-<div class="paragraph"><p>The methods for listening on privileged ports vary between systems,
-please refer to your system’s documentation for more information.</p></div>
-<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server,
-and load balancing for systems with multiple servers. Documenting these
-solutions is however out of the scope of this guide.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the
-<code>socket</code> transport option, which should just be the relevant data returned
-from the connect function for the transport or the underlying socket library
-(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be
-called on the passed in socket. You should connect the socket in
-<code>{active, false}</code> mode, as well.</p></div>
-<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an
-SSL listen socket prior to R16. Ranch will catch the error thrown, but the
-owner of the SSL socket will remain as whatever process created the socket.
-However, this will not affect accept behaviour unless the owner process dies,
-in which case the socket is closed. Therefore, to use this feature with SSL
-with an erlang release prior to R16, ensure that the SSL socket is opened in a
-persistant process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number
-of concurrent connections. It defaults to 1024. Its purpose is to
-prevent your system from being overloaded and ensuring all the
-connections are handled optimally.</p></div>
-<div class="listingblock">
-<div class="title">Customizing the maximum number of concurrent connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div>
-<div class="listingblock">
-<div class="title">Disabling the limit for the number of connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You may not always want connections to be counted when checking for
-<code>max_connections</code>. For example you might have a protocol where both
-short-lived and long-lived connections are possible. If the long-lived
-connections are mostly waiting for messages, then they don’t consume
-much resources and can safely be removed from the count.</p></div>
-<div class="paragraph"><p>To remove the connection from the count, you must call the
-<code>ranch:remove_connection/1</code> from within the connection process,
-with the name of the listener as the only argument.</p></div>
-<div class="listingblock">
-<div class="title">Removing a connection from the count of connections</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">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the
-first argument of the protocol’s <code>start_link/4</code> callback.</p></div>
-<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by
-using the <code>ranch:set_max_connections/2</code> function, with the name of the
-listener as first argument and the new value as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the maximum number of connections</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">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The change will occur immediately.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to define the type of process that will be used
-for the connection processes. By default it expects a <code>worker</code>.
-When the <code>connection_type</code> configuration value is set to <code>supervisor</code>,
-Ranch will consider that the connection process it manages is a
-supervisor and will reflect that in its supervision tree.</p></div>
-<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the
-socket directly or through one of their children. In the latter
-case the start function for the connection process must return
-two pids: the pid of the supervisor you created (that will be
-supervised) and the pid of the protocol handling process (that
-will receive the socket).</p></div>
-<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return
-<code>{ok, SupPid, ConnPid}</code>.</p></div>
-<div class="paragraph"><p>It is very important that the connection process be created
-under the supervisor process so that everything works as intended.
-If not, you will most likely experience issues when the supervised
-process is stopped.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading">Upgrading</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect
-immediately and for all subsequent connections.</p></div>
-<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code>
-with the name of the listener as first argument and the new options
-as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the protocol 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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All future connections will use the new options.</p></div>
-<div class="paragraph"><p>You can also retrieve the current options similarly by
-calling <code>ranch:get_protocol_options/1</code>.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the current protocol 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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the user of transport handlers.</p></div> +<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application.</p></div> +<div class="sect1"> +<h2 id="_starting_a_listener">Starting a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections.</p></div> +<div class="paragraph"><p>A listener can be started and stopped at will.</p></div> +<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div> +<div class="ulist"><ul> +<li> +<p> +A name to identify it locally and be able to interact with it. +</p> +</li> +<li> +<p> +The number of acceptors in the pool. +</p> +</li> +<li> +<p> +A transport handler and its associated options. +</p> +</li> +<li> +<p> +A protocol handler and its associated options. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively +<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div> +<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/6</code> +function. Before doing so however, you must ensure that the <code>ranch</code> +application is started.</p></div> +<div class="listingblock"> +<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the <code>echo_protocol</code> handler.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on port 5555</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the +examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em> +directory and run the following command:</p></div> +<div class="listingblock"> +<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div> +<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you’re done testing, you can use +the <code>Ctrl+]</code> key to escape to the telnet command line and type +<code>quit</code> to exit.</p></div> +<div class="listingblock"> +<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span> +Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span> +Connected to localhost<span style="color: #990000">.</span> +Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span> +Hello<span style="color: #990000">!</span> +Hello<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +<span style="color: #990000">^]</span> + +telnet<span style="color: #990000">></span> quit +Connection closed<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stopping_a_listener">Stopping a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All you need to stop a Ranch listener is to call the +<code>ranch:stop_listener/1</code> function with the listener’s name +as argument. In the previous section we started the listener +named <code>tcp_echo</code>. We can now stop it.</p></div> +<div class="listingblock"> +<div class="title">Stopping a listener</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">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_default_transport_options">Default transport options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the +options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set. +These values can’t be overriden when starting the listener, but +they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div> +<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which +can be overriden at listener startup.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_a_random_port">Listening on a random port</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port.</p></div> +<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The +argument is the name of the listener you gave in <code>ranch:start_listener/6</code>.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on a random port</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span> +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an <code>{error, eacces}</code> error when trying +to open a listening socket on such a port.</p></div> +<div class="paragraph"><p>The methods for listening on privileged ports vary between systems, +please refer to your system’s documentation for more information.</p></div> +<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the +<code>socket</code> transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be +called on the passed in socket. You should connect the socket in +<code>{active, false}</code> mode, as well.</p></div> +<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally.</p></div> +<div class="listingblock"> +<div class="title">Customizing the maximum number of concurrent connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div> +<div class="listingblock"> +<div class="title">Disabling the limit for the number of connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You may not always want connections to be counted when checking for +<code>max_connections</code>. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don’t consume +much resources and can safely be removed from the count.</p></div> +<div class="paragraph"><p>To remove the connection from the count, you must call the +<code>ranch:remove_connection/1</code> from within the connection process, +with the name of the listener as the only argument.</p></div> +<div class="listingblock"> +<div class="title">Removing a connection from the count of connections</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">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol’s <code>start_link/4</code> callback.</p></div> +<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by +using the <code>ranch:set_max_connections/2</code> function, with the name of the +listener as first argument and the new value as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the maximum number of connections</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">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The change will occur immediately.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a <code>worker</code>. +When the <code>connection_type</code> configuration value is set to <code>supervisor</code>, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree.</p></div> +<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket).</p></div> +<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return +<code>{ok, SupPid, ConnPid}</code>.</p></div> +<div class="paragraph"><p>It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading">Upgrading</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections.</p></div> +<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code> +with the name of the listener as first argument and the new options +as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the protocol 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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All future connections will use the new options.</p></div> +<div class="paragraph"><p>You can also retrieve the current options similarly by +calling <code>ranch:get_protocol_options/1</code>.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the current protocol 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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/parsers/index.html b/docs/en/ranch/1.2/guide/parsers/index.html index a0b4e5d1..a5d18388 100644 --- a/docs/en/ranch/1.2/guide/parsers/index.html +++ b/docs/en/ranch/1.2/guide/parsers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Writing parsers</title> @@ -67,115 +67,118 @@ <h1 class="lined-header"><span>Writing parsers</span></h1> -<div class="paragraph"><p>There are three kinds of protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Text protocols
-</p>
-</li>
-<li>
-<p>
-Schema-less binary protocols
-</p>
-</li>
-<li>
-<p>
-Schema-based binary protocols
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover
-more advanced topics such as continuations or parser generators.</p></div>
-<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that
-you know how to read data from the socket. The data you read and
-the data that hasn’t been parsed is saved in a buffer. Every
-time you read from the socket, the data read is appended to the
-buffer. What happens next depends on the kind of protocol. We
-will only cover the first two.</p></div>
-<div class="sect1">
-<h2 id="_parsing_text">Parsing text</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t
-do anything with them until we receive the full line.</p></div>
-<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/2 to get a line of input</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000">_</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>);
- [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was
-a line break in the buffer and we get it split into two parts,
-the line and the rest of the buffer; or there was no line break
-in the buffer and we need to get more data from the socket.</p></div>
-<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again
-split, here on space. The difference is that we want to split
-on all spaces character, as we want to tokenize the whole string.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/3 to split text</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>();
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>);
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>)
- <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest
-of the tokens in variables and call the respective functions.</p></div>
-<div class="paragraph"><p>After doing this, you will want to check if there is another
-line in the buffer, and handle it immediately if any.
-Otherwise wait for more data.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_parsing_binary">Parsing binary</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Binary protocols can be more varied, although most of them are
-pretty similar. The first four bytes of a frame tend to be
-the size of the frame, which is followed by a certain number
-of bytes for the type of frame and then various parameters.</p></div>
-<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes,
-sometimes not. Other times this size is encoded over two bytes.
-And even other times little-endian is used instead of big-endian.</p></div>
-<div class="paragraph"><p>The general idea stays the same though.</p></div>
-<div class="listingblock">
-<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>,
-<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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>You will then need to parse this frame using binary pattern
-matching, and handle it. Then you will want to check if there
-is another frame fully received in the buffer, and handle it
-immediately if any. Otherwise wait for more data.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>There are three kinds of protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +Text protocols +</p> +</li> +<li> +<p> +Schema-less binary protocols +</p> +</li> +<li> +<p> +Schema-based binary protocols +</p> +</li> +</ul></div> +<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators.</p></div> +<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn’t been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two.</p></div> +<div class="sect1"> +<h2 id="_parsing_text">Parsing text</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t +do anything with them until we receive the full line.</p></div> +<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/2 to get a line of input</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000">_</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>); + [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket.</p></div> +<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/3 to split text</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>(); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions.</p></div> +<div class="paragraph"><p>After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_parsing_binary">Parsing binary</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters.</p></div> +<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian.</p></div> +<div class="paragraph"><p>The general idea stays the same though.</p></div> +<div class="listingblock"> +<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>, +<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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>You will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/protocols/index.html b/docs/en/ranch/1.2/guide/protocols/index.html index b7918b8c..dffca064 100644 --- a/docs/en/ranch/1.2/guide/protocols/index.html +++ b/docs/en/ranch/1.2/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Protocols</title> @@ -67,135 +67,138 @@ <h1 class="lined-header"><span>Protocols</span></h1> -<div class="paragraph"><p>A protocol handler starts a connection process and defines the
-protocol logic executed in this process.</p></div>
-<div class="sect1">
-<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior
-which defines a single callback, <code>start_link/4</code>. This callback is
-responsible for spawning a new process for handling the connection.
-It receives four arguments: the name of the listener, the socket, the
-transport handler being used and the protocol options defined in
-the call to <code>ranch:start_listener/6</code>. This callback must
-return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div>
-<div class="paragraph"><p>The newly started process can then freely initialize itself. However,
-it must call <code>ranch:accept_ack/1</code> before doing any socket operation.
-This will ensure the connection process is the owner of the socket.
-It expects the listener’s name as argument.</p></div>
-<div class="listingblock">
-<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If your protocol code requires specific socket options, you should
-set them while initializing your connection process, after
-calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code>
-for that purpose.</p></div>
-<div class="paragraph"><p>Following is the complete protocol code for the example found
-in <code>examples/tcp_echo/</code>.</p></div>
-<div class="listingblock">
-<div class="title">Protocol module that echoes everything it receives</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: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</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="_using_gen_server">Using gen_server</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code>
-behaviours have the particularity of having their <code>start_link</code> call not
-return until the <code>init</code> function returns. This is problematic, because
-you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback
-as this would cause a deadlock to happen.</p></div>
-<div class="paragraph"><p>There are two ways of solving this problem.</p></div>
-<div class="paragraph"><p>The first, and probably the most elegant one, is to make use of the
-<code>gen_server:enter_loop/3</code> function. It allows you to start your process
-normally (although it must be started with <code>proc_lib</code> like all special
-processes), then perform any needed operations before falling back into
-the normal <code>gen_server</code> execution loop.</p></div>
-<div class="listingblock">
-<div class="title">Use a gen_server for protocol handling</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: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">proc_lib:start_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">proc_lib:init_ack</span></span>({<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>()}),
- <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
- <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div>
-<div class="paragraph"><p>The second method involves triggering a timeout just after <code>gen_server:init</code>
-ends. If you return a timeout value of <code>0</code> then the <code>gen_server</code> will call
-<code>handle_info(timeout, _, _)</code> right away.</p></div>
-<div class="listingblock">
-<div class="title">Use a gen_server for protocol handling, method 2</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: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Exports go here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>([<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>]) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, {<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}, <span style="color: #993399">0</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">handle_info</span></span>(<span style="color: #FF6600">timeout</span>, <span style="color: #009900">State</span><span style="color: #990000">=</span>{<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
- {<span style="color: #FF6600">noreply</span>, <span style="color: #009900">State</span>};
-<span style="font-style: italic"><span style="color: #9A1900">%% ...</span></span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>A protocol handler starts a connection process and defines the +protocol logic executed in this process.</p></div> +<div class="sect1"> +<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior +which defines a single callback, <code>start_link/4</code>. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to <code>ranch:start_listener/6</code>. This callback must +return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div> +<div class="paragraph"><p>The newly started process can then freely initialize itself. However, +it must call <code>ranch:accept_ack/1</code> before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener’s name as argument.</p></div> +<div class="listingblock"> +<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code> +for that purpose.</p></div> +<div class="paragraph"><p>Following is the complete protocol code for the example found +in <code>examples/tcp_echo/</code>.</p></div> +<div class="listingblock"> +<div class="title">Protocol module that echoes everything it receives</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: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</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="_using_gen_server">Using gen_server</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code> +behaviours have the particularity of having their <code>start_link</code> call not +return until the <code>init</code> function returns. This is problematic, because +you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback +as this would cause a deadlock to happen.</p></div> +<div class="paragraph"><p>There are two ways of solving this problem.</p></div> +<div class="paragraph"><p>The first, and probably the most elegant one, is to make use of the +<code>gen_server:enter_loop/3</code> function. It allows you to start your process +normally (although it must be started with <code>proc_lib</code> like all special +processes), then perform any needed operations before falling back into +the normal <code>gen_server</code> execution loop.</p></div> +<div class="listingblock"> +<div class="title">Use a gen_server for protocol handling</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: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">proc_lib:start_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">proc_lib:init_ack</span></span>({<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>()}), + <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), + <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div> +<div class="paragraph"><p>The second method involves triggering a timeout just after <code>gen_server:init</code> +ends. If you return a timeout value of <code>0</code> then the <code>gen_server</code> will call +<code>handle_info(timeout, _, _)</code> right away.</p></div> +<div class="listingblock"> +<div class="title">Use a gen_server for protocol handling, method 2</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: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Exports go here.</span></span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>([<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>]) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, {<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}, <span style="color: #993399">0</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">handle_info</span></span>(<span style="color: #FF6600">timeout</span>, <span style="color: #009900">State</span><span style="color: #990000">=</span>{<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), + {<span style="color: #FF6600">noreply</span>, <span style="color: #009900">State</span>}; +<span style="font-style: italic"><span style="color: #9A1900">%% ...</span></span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/ssl_auth/index.html b/docs/en/ranch/1.2/guide/ssl_auth/index.html index 18e94d36..3261ddc4 100644 --- a/docs/en/ranch/1.2/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: SSL client authentication</title> @@ -67,164 +67,167 @@ <h1 class="lined-header"><span>SSL client authentication</span></h1> -<div class="sect1">
-<h2 id="_purpose">Purpose</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to
-identify certificates. This allows your application to make sure that
-the client is an authorized certificate, but makes no claim about
-whether the user can be trusted. This can be combined with a password
-based authentication to attain greater security.</p></div>
-<div class="paragraph"><p>The server only needs to retain the certificate serial number and
-the certificate issuer to authenticate the certificate. Together,
-they can be used to uniquely identify a certicate.</p></div>
-<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and
-non-SSL transports, you need to make sure you are in an SSL context
-before attempting to perform an SSL client authentication. This
-can be done by checking the return value of <code>Transport:name/0</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can obtain client certificates from various sources. You can
-generate them yourself, or you can use a service like CAcert.org
-which allows you to generate client and server certificates for
-free.</p></div>
-<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org
-account, generate a certificate and install it in your favorite
-browser.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Open [CAcert.org](<a href="http://cacert.org">http://cacert.org</a>) in your favorite browser
-</p>
-</li>
-<li>
-<p>
-Root Certificate link: install both certificates
-</p>
-</li>
-<li>
-<p>
-Join (Register an account)
-</p>
-</li>
-<li>
-<p>
-Verify your account (check your email inbox!)
-</p>
-</li>
-<li>
-<p>
-Log in
-</p>
-</li>
-<li>
-<p>
-Client Certificates: New
-</p>
-</li>
-<li>
-<p>
-Follow instructions to create the certificate
-</p>
-</li>
-<li>
-<p>
-Install the certificate in your browser
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>You can optionally save the certificate for later use, for example
-to extract the <code>IssuerID</code> information as will be detailed later on.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_transport_configuration">Transport configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport does not request a client certificate by default.
-You need to specify the <code>{verify, verify_peer}</code> option when starting
-the listener to enable this behavior.</p></div>
-<div class="listingblock">
-<div class="title">Configure a listener for SSL authentication</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_ssl</span>, [
- {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>},
- {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>},
- {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>},
- {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>}
- ],
- <span style="color: #FF6600">my_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also
-the <code>cacertfile</code> containing the CACert.org root certificate, and
-the option to request the client certificate.</p></div>
-<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does
-not have a client certificate configured for your domain, then no
-certificate will be sent. This allows you to use SSL for more than
-just authenticated clients.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_authentication">Authentication</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To authenticate users, you must first save the certificate information
-required. If you have your users' certificate files, you can simply
-load the certificate and retrieve the information directly.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from a certificate</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">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>),
- [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number
-and the certificate issuer stored in a tuple, so this value alone can
-be used to uniquely identify the user certificate. You can save this
-value in a database, a configuration file or any other place where an
-Erlang term can be stored and retrieved.</p></div>
-<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first
-retrieve the client certificate and then extract this information from
-it. Ranch does not provide a function to retrieve the client certificate.
-Instead you can use the <code>ssl:peercert/1</code> function. Once you have the
-certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to
-extract the <code>IssuerID</code> value.</p></div>
-<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client
-certificate was found. This snippet is intended to be used from your
-protocol code.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from the certificate for the current 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">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span>
- <span style="color: #000080">false</span>;
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</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>You then only need to match the <code>IssuerID</code> value to authenticate the
-user.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_purpose">Purpose</h2> +<div class="sectionbody"> +<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security.</p></div> +<div class="paragraph"><p>The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate.</p></div> +<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of <code>Transport:name/0</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free.</p></div> +<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser.</p></div> +<div class="ulist"><ul> +<li> +<p> +Open [CAcert.org](<a href="http://cacert.org">http://cacert.org</a>) in your favorite browser +</p> +</li> +<li> +<p> +Root Certificate link: install both certificates +</p> +</li> +<li> +<p> +Join (Register an account) +</p> +</li> +<li> +<p> +Verify your account (check your email inbox!) +</p> +</li> +<li> +<p> +Log in +</p> +</li> +<li> +<p> +Client Certificates: New +</p> +</li> +<li> +<p> +Follow instructions to create the certificate +</p> +</li> +<li> +<p> +Install the certificate in your browser +</p> +</li> +</ul></div> +<div class="paragraph"><p>You can optionally save the certificate for later use, for example +to extract the <code>IssuerID</code> information as will be detailed later on.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_transport_configuration">Transport configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport does not request a client certificate by default. +You need to specify the <code>{verify, verify_peer}</code> option when starting +the listener to enable this behavior.</p></div> +<div class="listingblock"> +<div class="title">Configure a listener for SSL authentication</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_ssl</span>, [ + {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>}, + {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>}, + {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>}, + {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>} + ], + <span style="color: #FF6600">my_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also +the <code>cacertfile</code> containing the CACert.org root certificate, and +the option to request the client certificate.</p></div> +<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_authentication">Authentication</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from a certificate</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">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>), + [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved.</p></div> +<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the <code>ssl:peercert/1</code> function. Once you have the +certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to +extract the <code>IssuerID</code> value.</p></div> +<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client +certificate was found. This snippet is intended to be used from your +protocol code.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from the certificate for the current 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">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span> + <span style="color: #000080">false</span>; + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</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>You then only need to match the <code>IssuerID</code> value to authenticate the +user.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/transports/index.html b/docs/en/ranch/1.2/guide/transports/index.html index e45b0d90..b60d99e6 100644 --- a/docs/en/ranch/1.2/guide/transports/index.html +++ b/docs/en/ranch/1.2/guide/transports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Transports</title> @@ -67,195 +67,198 @@ <h1 class="lined-header"><span>Transports</span></h1> -<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div>
-<div class="paragraph"><p>Transports can be used for connecting, listening and accepting
-connections, but also for receiving and sending data. Both
-passive and active mode are supported, although all sockets
-are initialized as passive.</p></div>
-<div class="sect1">
-<h2 id="_tcp_transport">TCP transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ssl_transport">SSL transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>. It requires
-the <code>crypto</code>, <code>asn1</code>, <code>public_key</code> and <code>ssl</code> applications
-to be started. When starting an SSL listener, Ranch will attempt
-to automatically start them. It will not try to stop them when
-the listener is removed, however.</p></div>
-<div class="listingblock">
-<div class="title">Starting the SSL application</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">ssl:start</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>In a proper OTP setting, you will need to make your application
-depend on the <code>crypto</code>, <code>public_key</code> and <code>ssl</code> applications.
-They will be started automatically when starting your release.</p></div>
-<div class="paragraph"><p>The SSL transport <code>accept/2</code> function performs both transport
-and SSL accepts. Errors occurring during the SSL accept phase
-are returned as <code>{error, {ssl_accept, atom()}}</code> to differentiate
-on which socket the problem occurred.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_and_receiving_data">Sending and receiving data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler
-(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected
-socket obtained through the listener.</p></div>
-<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code>
-function. The data can be given as <code>iodata()</code>, which is defined as
-<code>binary() | iolist()</code>. All the following calls will work:</p></div>
-<div class="listingblock">
-<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode
-means that you will perform a blocking <code>Transport:recv/3</code> call, while
-active mode means that you will receive the data as a message.</p></div>
-<div class="paragraph"><p>By default, all data will be received as binary. It is possible to
-receive data as strings, although this is not recommended as binaries
-are a more efficient construct, especially for binary protocols.</p></div>
-<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The
-first argument is the socket, and the third argument is a timeout duration
-before the call returns with <code>{error, timeout}</code>.</p></div>
-<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive.
-The function will wait for data until it has received exactly this amount.
-If you are not expecting a precise size, you can specify 0 which will make
-this call return as soon as data was read, regardless of its size.</p></div>
-<div class="listingblock">
-<div class="title">Receiving data from the socket in passive mode</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">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive
-data as a message and to write the code to actually receive it.</p></div>
-<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and
-<code>{active, true}</code>. The first will send a single message before going
-back to passive mode; the second will send messages indefinitely.
-We recommend not using the <code>{active, true}</code> mode as it could quickly
-flood your process mailbox. It’s better to keep the data in the socket
-and read it only when required.</p></div>
-<div class="paragraph"><p>Three different messages can be received:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>{OK, Socket, Data}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Closed, Socket}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Error, Socket, Reason}</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different
-depending on the transport being used. To be able to properly match
-on them you must first call the <code>Transport:messages/0</code> function.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code>
-function, and do so every time you want to receive data.</p></div>
-<div class="listingblock">
-<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(),
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
-<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</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">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]);
- {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>);
- {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</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>You can easily integrate active sockets with existing Erlang code as all
-you really need is just a few more clauses when receiving messages.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_files">Sending files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport
-handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div>
-<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file by filename</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">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of
-bytes and chunks of size <code>ChunkSize</code>:</p></div>
-<div class="listingblock">
-<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}],
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also
-possible to use a file descriptor opened in raw mode:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file opened in raw mode</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">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]),
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_a_transport_handler">Writing a transport handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior.
-It defines a certain number of callbacks that must be written in order to
-allow transparent usage of the transport handler.</p></div>
-<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a
-socket. These do not need to be common to all transports as it’s easy enough
-to write different initialization functions for the different transports that
-will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong>
-implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div>
-<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a
-fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument
-is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div> +<div class="paragraph"><p>Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive.</p></div> +<div class="sect1"> +<h2 id="_tcp_transport">TCP transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ssl_transport">SSL transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>. It requires +the <code>crypto</code>, <code>asn1</code>, <code>public_key</code> and <code>ssl</code> applications +to be started. When starting an SSL listener, Ranch will attempt +to automatically start them. It will not try to stop them when +the listener is removed, however.</p></div> +<div class="listingblock"> +<div class="title">Starting the SSL application</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">ssl:start</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In a proper OTP setting, you will need to make your application +depend on the <code>crypto</code>, <code>public_key</code> and <code>ssl</code> applications. +They will be started automatically when starting your release.</p></div> +<div class="paragraph"><p>The SSL transport <code>accept/2</code> function performs both transport +and SSL accepts. Errors occurring during the SSL accept phase +are returned as <code>{error, {ssl_accept, atom()}}</code> to differentiate +on which socket the problem occurred.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_and_receiving_data">Sending and receiving data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler +(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected +socket obtained through the listener.</p></div> +<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code> +function. The data can be given as <code>iodata()</code>, which is defined as +<code>binary() | iolist()</code>. All the following calls will work:</p></div> +<div class="listingblock"> +<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking <code>Transport:recv/3</code> call, while +active mode means that you will receive the data as a message.</p></div> +<div class="paragraph"><p>By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols.</p></div> +<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with <code>{error, timeout}</code>.</p></div> +<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size.</p></div> +<div class="listingblock"> +<div class="title">Receiving data from the socket in passive mode</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">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it.</p></div> +<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and +<code>{active, true}</code>. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the <code>{active, true}</code> mode as it could quickly +flood your process mailbox. It’s better to keep the data in the socket +and read it only when required.</p></div> +<div class="paragraph"><p>Three different messages can be received:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>{OK, Socket, Data}</code> +</p> +</li> +<li> +<p> +<code>{Closed, Socket}</code> +</p> +</li> +<li> +<p> +<code>{Error, Socket, Reason}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different +depending on the transport being used. To be able to properly match +on them you must first call the <code>Transport:messages/0</code> function.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> +function, and do so every time you want to receive data.</p></div> +<div class="listingblock"> +<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(), +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), +<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</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">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]); + {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>); + {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</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>You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_files">Sending files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport +handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div> +<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div> +<div class="listingblock"> +<div class="title">Sending a file by filename</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">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of +bytes and chunks of size <code>ChunkSize</code>:</p></div> +<div class="listingblock"> +<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}], +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode:</p></div> +<div class="listingblock"> +<div class="title">Sending a file opened in raw mode</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">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]), +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_a_transport_handler">Writing a transport handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler.</p></div> +<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a +socket. These do not need to be common to all transports as it’s easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong> +implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div> +<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a +fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument +is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/index.html b/docs/en/ranch/1.2/index.html index d87c4243..0194031a 100644 --- a/docs/en/ranch/1.2/index.html +++ b/docs/en/ranch/1.2/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/ranch/1.2/manual/index.html b/docs/en/ranch/1.2/manual/index.html index 08dcf0ce..eecb6cbe 100644 --- a/docs/en/ranch/1.2/manual/index.html +++ b/docs/en/ranch/1.2/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch Function Reference</title> @@ -67,38 +67,38 @@ <h1 class="lined-header"><span>Ranch Function Reference</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="ranch_app">ranch(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch">ranch(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_protocol">ranch_protocol(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_ssl">ranch_ssl(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_tcp">ranch_tcp(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_transport">ranch_transport(3)</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="ranch_app">ranch(7)</a> +</p> +</li> +<li> +<p> +<a href="ranch">ranch(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_protocol">ranch_protocol(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_ssl">ranch_ssl(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_tcp">ranch_tcp(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_transport">ranch_transport(3)</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.2/manual/ranch/index.html b/docs/en/ranch/1.2/manual/ranch/index.html index 2c72b236..2cbc5dec 100644 --- a/docs/en/ranch/1.2/manual/ranch/index.html +++ b/docs/en/ranch/1.2/manual/ranch/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(3)</title> @@ -67,423 +67,423 @@ <h1 class="lined-header"><span>ranch(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - socket acceptor pool</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and
-manipulating Ranch listeners.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3>
-<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div>
-<div class="paragraph"><p>This is a soft limit. The actual number of connections
-might be slightly above the limit due to concurrency
-when accepting new connections. Some connections may
-also be removed from this count explicitly by the user
-code.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>}
- | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()}
- | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>}
- | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Ranch-specific transport options.</p></div>
-<div class="paragraph"><p>These options are not passed on to the transports.
-They are used by Ranch while setting up the listeners.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ref_any">ref() = any()</h3>
-<div class="paragraph"><p>Unique name used to refer to a listener.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ack_timeout (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish.
-</p>
-</dd>
-<dt class="hdlist1">
-connection_type (worker)
-</dt>
-<dd>
-<p>
- Type of process that will handle the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_connections (1024)
-</dt>
-<dd>
-<p>
- Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for children to stop on listener shutdown.
-</p>
-</dd>
-<dt class="hdlist1">
-socket
-</dt>
-<dd>
-<p>
- Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div>
-<div class="paragraph"><p>This function MUST be used by a connection process to inform
-Ranch that it initialized properly and let it perform any
-additional operations before the socket can be safely used.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_child_spec_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NbAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return child specifications for a new listener.</p></div>
-<div class="paragraph"><p>This function can be used to embed a listener directly
-in an application instead of letting Ranch handle it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the interface used by this listener.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-Current maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Current protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div>
-<div class="paragraph"><p>You can use this function for long-running connection processes
-which spend most of their time idling rather than consuming
-resources. This allows Ranch to accept a lot more connections
-without sacrificing the latency of the system.</p></div>
-<div class="paragraph"><p>This function may only be called from a connection process.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-New maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately. If the new value is
-smaller than the previous one, Ranch will not kill the extra
-connections, but will wait for them to terminate properly.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-New protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the protocol options for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately for all new connections.
-Old connections will not receive the new options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_start_listener_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NbAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start listening for connections using the given transport
-and protocol. Returns the pid for this listener’s supervisor.</p></div>
-<div class="paragraph"><p>There are additional transport options that apply
-regardless of transport. They allow configuring how the
-connections are supervised, rate limited and more. Please
-consult the previous section for more details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stop the given listener.</p></div>
-<div class="paragraph"><p>The listener is stopped gracefully, first by closing the
-listening port, then by stopping the connection processes.
-These processes are stopped according to the <code>shutdown</code>
-transport option, which may be set to brutally kill all
-connection processes or give them some time to stop properly.</p></div>
-<div class="paragraph"><p>This function does not return until the listener is
-completely stopped.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - socket acceptor pool</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and +manipulating Ranch listeners.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3> +<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div> +<div class="paragraph"><p>This is a soft limit. The actual number of connections +might be slightly above the limit due to concurrency +when accepting new connections. Some connections may +also be removed from this count explicitly by the user +code.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>} + | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()} + | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>} + | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Ranch-specific transport options.</p></div> +<div class="paragraph"><p>These options are not passed on to the transports. +They are used by Ranch while setting up the listeners.</p></div> +</div> +<div class="sect2"> +<h3 id="_ref_any">ref() = any()</h3> +<div class="paragraph"><p>Unique name used to refer to a listener.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +ack_timeout (5000) +</dt> +<dd> +<p> + Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish. +</p> +</dd> +<dt class="hdlist1"> +connection_type (worker) +</dt> +<dd> +<p> + Type of process that will handle the connection. +</p> +</dd> +<dt class="hdlist1"> +max_connections (1024) +</dt> +<dd> +<p> + Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely. +</p> +</dd> +<dt class="hdlist1"> +shutdown (5000) +</dt> +<dd> +<p> + Maximum allowed time for children to stop on listener shutdown. +</p> +</dd> +<dt class="hdlist1"> +socket +</dt> +<dd> +<p> + Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div> +<div class="paragraph"><p>This function MUST be used by a connection process to inform +Ranch that it initialized properly and let it perform any +additional operations before the socket can be safely used.</p></div> +</div> +<div class="sect2"> +<h3 id="_child_spec_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NbAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return child specifications for a new listener.</p></div> +<div class="paragraph"><p>This function can be used to embed a listener directly +in an application instead of letting Ranch handle it.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the interface used by this listener. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +Current maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Current protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div> +<div class="paragraph"><p>You can use this function for long-running connection processes +which spend most of their time idling rather than consuming +resources. This allows Ranch to accept a lot more connections +without sacrificing the latency of the system.</p></div> +<div class="paragraph"><p>This function may only be called from a connection process.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +New maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will not kill the extra +connections, but will wait for them to terminate properly.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +New protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the protocol options for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately for all new connections. +Old connections will not receive the new options.</p></div> +</div> +<div class="sect2"> +<h3 id="_start_listener_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NbAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start listening for connections using the given transport +and protocol. Returns the pid for this listener’s supervisor.</p></div> +<div class="paragraph"><p>There are additional transport options that apply +regardless of transport. They allow configuring how the +connections are supervised, rate limited and more. Please +consult the previous section for more details.</p></div> +</div> +<div class="sect2"> +<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stop the given listener.</p></div> +<div class="paragraph"><p>The listener is stopped gracefully, first by closing the +listening port, then by stopping the connection processes. +These processes are stopped according to the <code>shutdown</code> +transport option, which may be set to brutally kill all +connection processes or give them some time to stop properly.</p></div> +<div class="paragraph"><p>This function does not return until the listener is +completely stopped.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_app/index.html b/docs/en/ranch/1.2/manual/ranch_app/index.html index fd930bf4..a3f2b89c 100644 --- a/docs/en/ranch/1.2/manual/ranch_app/index.html +++ b/docs/en/ranch/1.2/manual/ranch_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(7)</title> @@ -67,43 +67,43 @@ <h1 class="lined-header"><span>ranch(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application has no particular dependency required
-to start.</p></div>
-<div class="paragraph"><p>It has optional dependencies that are only required when
-listening for SSL connections. The dependencies are <code>crypto</code>,
-<code>asn1</code>, <code>public_key</code> and <code>ssl</code>. They are started automatically
-if they weren’t before.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application defines one application environment
-configuration parameter.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-profile (false)
-</dt>
-<dd>
-<p>
- When enabled, Ranch will start <code>eprof</code> profiling automatically.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop
-profiling and output the results to the files <em>procs.profile</em>
-and <em>total.profile</em>. Do not use in production.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application has no particular dependency required +to start.</p></div> +<div class="paragraph"><p>It has optional dependencies that are only required when +listening for SSL connections. The dependencies are <code>crypto</code>, +<code>asn1</code>, <code>public_key</code> and <code>ssl</code>. They are started automatically +if they weren’t before.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application defines one application environment +configuration parameter.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +profile (false) +</dt> +<dd> +<p> + When enabled, Ranch will start <code>eprof</code> profiling automatically. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop +profiling and output the results to the files <em>procs.profile</em> +and <em>total.profile</em>. Do not use in production.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_protocol/index.html b/docs/en/ranch/1.2/manual/ranch_protocol/index.html index e8411a2c..f88fad6c 100644 --- a/docs/en/ranch/1.2/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.2/manual/ranch_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_protocol(3)</title> @@ -67,83 +67,83 @@ <h1 class="lined-header"><span>ranch_protocol(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used
-by Ranch protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ranch:ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start a new connection process for the given socket.</p></div>
-<div class="paragraph"><p>The only purpose of this callback is to start a process that
-will handle the socket. It must spawn the process, link and
-then return the new pid. This function will always be called
-from inside a supervisor.</p></div>
-<div class="paragraph"><p>This callback can also return two pids. The first pid is the
-pid of the process that will be supervised. The second pid is
-the pid of the process that will receive ownership of the
-socket. This second process must be a child of the first. This
-form is only available when <code>connection_type</code> is set to
-<code>supervisor</code>.</p></div>
-<div class="paragraph"><p>If any other value is returned, the supervisor will close the
-socket and assume no process has been started.</p></div>
-<div class="paragraph"><p>Do not perform any operations in this callback, as this would
-block the supervisor responsible for starting connection
-processes and degrade performance severely.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used +by Ranch protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ranch:ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start a new connection process for the given socket.</p></div> +<div class="paragraph"><p>The only purpose of this callback is to start a process that +will handle the socket. It must spawn the process, link and +then return the new pid. This function will always be called +from inside a supervisor.</p></div> +<div class="paragraph"><p>This callback can also return two pids. The first pid is the +pid of the process that will be supervised. The second pid is +the pid of the process that will receive ownership of the +socket. This second process must be a child of the first. This +form is only available when <code>connection_type</code> is set to +<code>supervisor</code>.</p></div> +<div class="paragraph"><p>If any other value is returned, the supervisor will close the +socket and assume no process has been started.</p></div> +<div class="paragraph"><p>Do not perform any operations in this callback, as this would +block the supervisor responsible for starting connection +processes and degrade performance severely.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html index c006d8e6..d1b83d48 100644 --- a/docs/en/ranch/1.2/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_ssl(3)</title> @@ -67,349 +67,349 @@ <h1 class="lined-header"><span>ranch_ssl(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_ssl_opt">ssl_opt()</h3>
-<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: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]}
- | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}}
- | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>}
- | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>}
- | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>}
- | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}}
- | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)}
- | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]}
- | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()}
- | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>SSL-specific listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3>
-<div class="paragraph"><p>Listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code>
-or the <code>certfile</code> option. None of the other options are required.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-alpn_preferred_protocols
-</dt>
-<dd>
-<p>
- Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.
-</p>
-</dd>
-<dt class="hdlist1">
-cacertfile
-</dt>
-<dd>
-<p>
- Path to PEM encoded trusted certificates file used to verify peer certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cacerts
-</dt>
-<dd>
-<p>
- List of DER encoded trusted certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cert
-</dt>
-<dd>
-<p>
- DER encoded user certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-certfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded user certificate file. May also contain the private key.
-</p>
-</dd>
-<dt class="hdlist1">
-ciphers
-</dt>
-<dd>
-<p>
- List of ciphers that clients are allowed to use.
-</p>
-</dd>
-<dt class="hdlist1">
-client_renegotiation (true)
-</dt>
-<dd>
-<p>
- Whether to allow client-initiated renegotiation.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_cache ({ssl_crl_cache, {internal, []}})
-</dt>
-<dd>
-<p>
- Customize the module used to cache Certificate Revocation Lists.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_check (false)
-</dt>
-<dd>
-<p>
- Whether to perform CRL check on all certificates in the chain during validation.
-</p>
-</dd>
-<dt class="hdlist1">
-depth (1)
-</dt>
-<dd>
-<p>
- Maximum of intermediate certificates allowed in the certification path.
-</p>
-</dd>
-<dt class="hdlist1">
-dh
-</dt>
-<dd>
-<p>
- DER encoded Diffie-Hellman parameters.
-</p>
-</dd>
-<dt class="hdlist1">
-dhfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded Diffie-Hellman parameters file.
-</p>
-</dd>
-<dt class="hdlist1">
-fail_if_no_peer_cert (false)
-</dt>
-<dd>
-<p>
- Whether to refuse the connection if the client sends an empty certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-hibernate_after (undefined)
-</dt>
-<dd>
-<p>
- Time in ms after which SSL socket processes go into hibernation to reduce memory usage.
-</p>
-</dd>
-<dt class="hdlist1">
-honor_cipher_order (false)
-</dt>
-<dd>
-<p>
- If true, use the server’s preference for cipher selection. If false, use the client’s preference.
-</p>
-</dd>
-<dt class="hdlist1">
-key
-</dt>
-<dd>
-<p>
- DER encoded user private key.
-</p>
-</dd>
-<dt class="hdlist1">
-keyfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded private key file, if different than the certfile.
-</p>
-</dd>
-<dt class="hdlist1">
-log_alert (true)
-</dt>
-<dd>
-<p>
- If false, error reports will not be displayed.
-</p>
-</dd>
-<dt class="hdlist1">
-next_protocols_advertised
-</dt>
-<dd>
-<p>
- List of protocols to send to the client if it supports the Next Protocol extension.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-partial_chain
-</dt>
-<dd>
-<p>
- Claim an intermediate CA in the chain as trusted.
-</p>
-</dd>
-<dt class="hdlist1">
-password
-</dt>
-<dd>
-<p>
- Password to the private key file, if password protected.
-</p>
-</dd>
-<dt class="hdlist1">
-psk_identity
-</dt>
-<dd>
-<p>
- Provide the given PSK identity hint to the client during the handshake.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_session
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a session should be reused.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_sessions (false)
-</dt>
-<dd>
-<p>
- Whether to allow session reuse.
-</p>
-</dd>
-<dt class="hdlist1">
-secure_renegotiate (false)
-</dt>
-<dd>
-<p>
- Whether to reject renegotiation attempts that do not conform to RFC5746.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_fun
-</dt>
-<dd>
-<p>
- Function called when the client requests a host using Server Name Indication. Returns options to apply.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_hosts
-</dt>
-<dd>
-<p>
- Options to apply for the host that matches what the client requested with Server Name Indication.
-</p>
-</dd>
-<dt class="hdlist1">
-user_lookup_fun
-</dt>
-<dd>
-<p>
- Function called to determine the shared secret when using PSK, or provide parameters when using SRP.
-</p>
-</dd>
-<dt class="hdlist1">
-verify (verify_none)
-</dt>
-<dd>
-<p>
- Use <code>verify_peer</code> to request a certificate from the client.
-</p>
-</dd>
-<dt class="hdlist1">
-verify_fun
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a client certificate is valid.
-</p>
-</dd>
-<dt class="hdlist1">
-versions
-</dt>
-<dd>
-<p>
- TLS protocol versions that will be supported.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Note that the client will not send a certificate unless the
-value for the <code>verify</code> option is set to <code>verify_peer</code>. This
-means that the <code>fail_if_no_peer_cert</code> only apply when combined
-with the <code>verify</code> option. The <code>verify_fun</code> option allows
-greater control over the client certificate validation.</p></div>
-<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_ssl_opt">ssl_opt()</h3> +<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: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]} + | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}} + | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>} + | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>} + | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>} + | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}} + | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)} + | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]} + | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()} + | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>SSL-specific listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> +<div class="paragraph"><p>Listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code> +or the <code>certfile</code> option. None of the other options are required.</p></div> +<div class="paragraph"><p>The default value is given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +alpn_preferred_protocols +</dt> +<dd> +<p> + Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. +</p> +</dd> +<dt class="hdlist1"> +cacertfile +</dt> +<dd> +<p> + Path to PEM encoded trusted certificates file used to verify peer certificates. +</p> +</dd> +<dt class="hdlist1"> +cacerts +</dt> +<dd> +<p> + List of DER encoded trusted certificates. +</p> +</dd> +<dt class="hdlist1"> +cert +</dt> +<dd> +<p> + DER encoded user certificate. +</p> +</dd> +<dt class="hdlist1"> +certfile +</dt> +<dd> +<p> + Path to the PEM encoded user certificate file. May also contain the private key. +</p> +</dd> +<dt class="hdlist1"> +ciphers +</dt> +<dd> +<p> + List of ciphers that clients are allowed to use. +</p> +</dd> +<dt class="hdlist1"> +client_renegotiation (true) +</dt> +<dd> +<p> + Whether to allow client-initiated renegotiation. +</p> +</dd> +<dt class="hdlist1"> +crl_cache ({ssl_crl_cache, {internal, []}}) +</dt> +<dd> +<p> + Customize the module used to cache Certificate Revocation Lists. +</p> +</dd> +<dt class="hdlist1"> +crl_check (false) +</dt> +<dd> +<p> + Whether to perform CRL check on all certificates in the chain during validation. +</p> +</dd> +<dt class="hdlist1"> +depth (1) +</dt> +<dd> +<p> + Maximum of intermediate certificates allowed in the certification path. +</p> +</dd> +<dt class="hdlist1"> +dh +</dt> +<dd> +<p> + DER encoded Diffie-Hellman parameters. +</p> +</dd> +<dt class="hdlist1"> +dhfile +</dt> +<dd> +<p> + Path to the PEM encoded Diffie-Hellman parameters file. +</p> +</dd> +<dt class="hdlist1"> +fail_if_no_peer_cert (false) +</dt> +<dd> +<p> + Whether to refuse the connection if the client sends an empty certificate. +</p> +</dd> +<dt class="hdlist1"> +hibernate_after (undefined) +</dt> +<dd> +<p> + Time in ms after which SSL socket processes go into hibernation to reduce memory usage. +</p> +</dd> +<dt class="hdlist1"> +honor_cipher_order (false) +</dt> +<dd> +<p> + If true, use the server’s preference for cipher selection. If false, use the client’s preference. +</p> +</dd> +<dt class="hdlist1"> +key +</dt> +<dd> +<p> + DER encoded user private key. +</p> +</dd> +<dt class="hdlist1"> +keyfile +</dt> +<dd> +<p> + Path to the PEM encoded private key file, if different than the certfile. +</p> +</dd> +<dt class="hdlist1"> +log_alert (true) +</dt> +<dd> +<p> + If false, error reports will not be displayed. +</p> +</dd> +<dt class="hdlist1"> +next_protocols_advertised +</dt> +<dd> +<p> + List of protocols to send to the client if it supports the Next Protocol extension. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +partial_chain +</dt> +<dd> +<p> + Claim an intermediate CA in the chain as trusted. +</p> +</dd> +<dt class="hdlist1"> +password +</dt> +<dd> +<p> + Password to the private key file, if password protected. +</p> +</dd> +<dt class="hdlist1"> +psk_identity +</dt> +<dd> +<p> + Provide the given PSK identity hint to the client during the handshake. +</p> +</dd> +<dt class="hdlist1"> +reuse_session +</dt> +<dd> +<p> + Custom policy to decide whether a session should be reused. +</p> +</dd> +<dt class="hdlist1"> +reuse_sessions (false) +</dt> +<dd> +<p> + Whether to allow session reuse. +</p> +</dd> +<dt class="hdlist1"> +secure_renegotiate (false) +</dt> +<dd> +<p> + Whether to reject renegotiation attempts that do not conform to RFC5746. +</p> +</dd> +<dt class="hdlist1"> +sni_fun +</dt> +<dd> +<p> + Function called when the client requests a host using Server Name Indication. Returns options to apply. +</p> +</dd> +<dt class="hdlist1"> +sni_hosts +</dt> +<dd> +<p> + Options to apply for the host that matches what the client requested with Server Name Indication. +</p> +</dd> +<dt class="hdlist1"> +user_lookup_fun +</dt> +<dd> +<p> + Function called to determine the shared secret when using PSK, or provide parameters when using SRP. +</p> +</dd> +<dt class="hdlist1"> +verify (verify_none) +</dt> +<dd> +<p> + Use <code>verify_peer</code> to request a certificate from the client. +</p> +</dd> +<dt class="hdlist1"> +verify_fun +</dt> +<dd> +<p> + Custom policy to decide whether a client certificate is valid. +</p> +</dd> +<dt class="hdlist1"> +versions +</dt> +<dd> +<p> + TLS protocol versions that will be supported. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Note that the client will not send a certificate unless the +value for the <code>verify</code> option is set to <code>verify_peer</code>. This +means that the <code>fail_if_no_peer_cert</code> only apply when combined +with the <code>verify</code> option. The <code>verify_fun</code> option allows +greater control over the client certificate validation.</p></div> +<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_tcp/index.html b/docs/en/ranch/1.2/manual/ranch_tcp/index.html index 120010a5..989da87d 100644 --- a/docs/en/ranch/1.2/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.2/manual/ranch_tcp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_tcp(3)</title> @@ -67,274 +67,274 @@ <h1 class="lined-header"><span>ranch_tcp(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div>
-<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is
-recommended to disable async threads when using the
-<code>sendfile</code> function of this transport, as it can make
-the threads stuck indefinitely.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | <span style="color: #FF6600">inet</span>
- | <span style="color: #FF6600">inet6</span>
- | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()}
- | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}}
- | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
- | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}
- | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Listen options.</p></div>
-<div class="paragraph"><p>This does not represent the entirety of the options that can
-be set on the socket, but only the options that may be
-set independently of protocol implementation.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more
-thorough description of these options. This manual only aims
-to provide a short description along with what the defaults
-are. Defaults may be different in Ranch compared to <code>gen_tcp</code>.
-Defaults are given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-backlog (1024)
-</dt>
-<dd>
-<p>
- Max length of the queue of pending connections.
-</p>
-</dd>
-<dt class="hdlist1">
-buffer
-</dt>
-<dd>
-<p>
- Size of the buffer used by the Erlang driver. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-delay_send (false)
-</dt>
-<dd>
-<p>
- Always queue packets before sending, to send fewer, larger packets over the network.
-</p>
-</dd>
-<dt class="hdlist1">
-dontroute (false)
-</dt>
-<dd>
-<p>
- Don’t send via a gateway, only send to directly connected hosts.
-</p>
-</dd>
-<dt class="hdlist1">
-exit_on_close (true)
-</dt>
-<dd>
-<p>
- Disable to allow sending data after a close has been detected.
-</p>
-</dd>
-<dt class="hdlist1">
-fd
-</dt>
-<dd>
-<p>
- File descriptor of the socket, if it was opened externally.
-</p>
-</dd>
-<dt class="hdlist1">
-high_msgq_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the socket message queue before the socket queue becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-high_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-inet
-</dt>
-<dd>
-<p>
- Set up the socket for IPv4.
-</p>
-</dd>
-<dt class="hdlist1">
-inet6
-</dt>
-<dd>
-<p>
- Set up the socket for IPv6.
-</p>
-</dd>
-<dt class="hdlist1">
-ip
-</dt>
-<dd>
-<p>
- Interface to listen on. Listen on all interfaces by default.
-</p>
-</dd>
-<dt class="hdlist1">
-keepalive (false)
-</dt>
-<dd>
-<p>
- Enable sending of keep-alive messages.
-</p>
-</dd>
-<dt class="hdlist1">
-linger ({false, 0})
-</dt>
-<dd>
-<p>
- Whether to wait and how long to flush data sent before closing the socket.
-</p>
-</dd>
-<dt class="hdlist1">
-low_msgq_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the socket message queue before the socket queue leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-low_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-port (0)
-</dt>
-<dd>
-<p>
- TCP port number to listen on. 0 means a random port will be used.
-</p>
-</dd>
-<dt class="hdlist1">
-priority (0)
-</dt>
-<dd>
-<p>
- Priority value for all packets to be sent by this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-recbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s receive buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout (30000)
-</dt>
-<dd>
-<p>
- How long the send call may wait for confirmation before returning.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout_close (true)
-</dt>
-<dd>
-<p>
- Whether to close the socket when the confirmation wasn’t received.
-</p>
-</dd>
-<dt class="hdlist1">
-sndbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s send buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-tos
-</dt>
-<dd>
-<p>
- Value for the IP_TOS IP level option. Use with caution.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific
-options by specifying the protocol level, the option number and
-the actual option value specified as a binary. This option is not
-portable. Use with caution.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div> +<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is +recommended to disable async threads when using the +<code>sendfile</code> function of this transport, as it can make +the threads stuck indefinitely.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | <span style="color: #FF6600">inet</span> + | <span style="color: #FF6600">inet6</span> + | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()} + | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}} + | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} + | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()} + | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Listen options.</p></div> +<div class="paragraph"><p>This does not represent the entirety of the options that can +be set on the socket, but only the options that may be +set independently of protocol implementation.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to <code>gen_tcp</code>. +Defaults are given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +backlog (1024) +</dt> +<dd> +<p> + Max length of the queue of pending connections. +</p> +</dd> +<dt class="hdlist1"> +buffer +</dt> +<dd> +<p> + Size of the buffer used by the Erlang driver. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +delay_send (false) +</dt> +<dd> +<p> + Always queue packets before sending, to send fewer, larger packets over the network. +</p> +</dd> +<dt class="hdlist1"> +dontroute (false) +</dt> +<dd> +<p> + Don’t send via a gateway, only send to directly connected hosts. +</p> +</dd> +<dt class="hdlist1"> +exit_on_close (true) +</dt> +<dd> +<p> + Disable to allow sending data after a close has been detected. +</p> +</dd> +<dt class="hdlist1"> +fd +</dt> +<dd> +<p> + File descriptor of the socket, if it was opened externally. +</p> +</dd> +<dt class="hdlist1"> +high_msgq_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the socket message queue before the socket queue becomes busy. +</p> +</dd> +<dt class="hdlist1"> +high_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy. +</p> +</dd> +<dt class="hdlist1"> +inet +</dt> +<dd> +<p> + Set up the socket for IPv4. +</p> +</dd> +<dt class="hdlist1"> +inet6 +</dt> +<dd> +<p> + Set up the socket for IPv6. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> + Interface to listen on. Listen on all interfaces by default. +</p> +</dd> +<dt class="hdlist1"> +keepalive (false) +</dt> +<dd> +<p> + Enable sending of keep-alive messages. +</p> +</dd> +<dt class="hdlist1"> +linger ({false, 0}) +</dt> +<dd> +<p> + Whether to wait and how long to flush data sent before closing the socket. +</p> +</dd> +<dt class="hdlist1"> +low_msgq_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the socket message queue before the socket queue leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +low_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +port (0) +</dt> +<dd> +<p> + TCP port number to listen on. 0 means a random port will be used. +</p> +</dd> +<dt class="hdlist1"> +priority (0) +</dt> +<dd> +<p> + Priority value for all packets to be sent by this socket. +</p> +</dd> +<dt class="hdlist1"> +recbuf +</dt> +<dd> +<p> + Minimum size of the socket’s receive buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +send_timeout (30000) +</dt> +<dd> +<p> + How long the send call may wait for confirmation before returning. +</p> +</dd> +<dt class="hdlist1"> +send_timeout_close (true) +</dt> +<dd> +<p> + Whether to close the socket when the confirmation wasn’t received. +</p> +</dd> +<dt class="hdlist1"> +sndbuf +</dt> +<dd> +<p> + Minimum size of the socket’s send buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +tos +</dt> +<dd> +<p> + Value for the IP_TOS IP level option. Use with caution. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific +options by specifying the protocol level, the option number and +the actual option value specified as a binary. This option is not +portable. Use with caution.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_transport/index.html b/docs/en/ranch/1.2/manual/ranch_transport/index.html index a9e1ac4f..fcd30741 100644 --- a/docs/en/ranch/1.2/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.2/manual/ranch_transport/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_transport(3)</title> @@ -67,494 +67,494 @@ <h1 class="lined-header"><span>ranch_transport(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used
-by Ranch transports.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3>
-<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div>
-<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-LSocket = CSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Accept timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div>
-<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket
-after accepting the connection. This is most useful when the
-transport is not raw TCP, like with SSL for example.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Ack timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div>
-<div class="paragraph"><p>This function will be called by connection processes
-before performing any socket operation. It allows
-transports that require extra initialization to perform
-their task and make the socket ready to use.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Close the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-Pid = pid()
-</dt>
-<dd>
-<p>
-Pid of the new owner of the socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change the controlling process for the given socket.</p></div>
-<div class="paragraph"><p>The controlling process is the process that is allowed to
-perform operations on the socket, and that will receive
-messages from the socket when active mode is used. When
-the controlling process dies, the socket is closed.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-LSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Listen for connections on the given port.</p></div>
-<div class="paragraph"><p>The port is given as part of the transport options under
-the key <code>port</code>. Any other option is transport dependent.</p></div>
-<div class="paragraph"><p>The socket returned by this call can then be used to
-accept connections. It is not possible to send or receive
-data from the listening socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-OK = Closed = Error = atom()
-</dt>
-<dd>
-<p>
-Tuple names.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_name_8594_name">name() → Name</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name = atom()
-</dt>
-<dd>
-<p>
-Transport module name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the name of the transport.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the remote endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the remote endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Length = non_neg_integer()
-</dt>
-<dd>
-<p>
-Requested length.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Receive timeout.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata() | any()
-</dt>
-<dd>
-<p>
-Data received.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div>
-<div class="paragraph"><p>Trying to receive data from a socket that is in active mode
-will return an error.</p></div>
-<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div>
-<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>,
-this is highly discouraged as this could cause your process
-to get stuck waiting for data that will never come. This may
-happen when a socket becomes half-open due to a crash of the
-remote endpoint. Wi-Fi going down is another common culprit
-of this issue.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata()
-</dt>
-<dd>
-<p>
-Data to be sent.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data to the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>The file may be sent full or in parts, and may be specified
-by its filename or by an already open file descriptor.</p></div>
-<div class="paragraph"><p>Transports that manipulate TCP directly may use the
-<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile
-syscall where applicable (on Linux, for example). Other
-transports can use the <code>sendfile/6</code> function exported from
-this module.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-SockOpts = any()
-</dt>
-<dd>
-<p>
-Socket options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change options for the given socket.</p></div>
-<div class="paragraph"><p>This is mainly useful for switching to active or passive mode
-or to set protocol-specific options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-How = read | write | read_write
-</dt>
-<dd>
-<p>
-Which side(s) of the socket to close.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the local endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the local endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code>
-and may be used when transports are not manipulating TCP
-directly.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used +by Ranch transports.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3> +<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div> +<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +LSocket = CSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Accept timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div> +<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket +after accepting the connection. This is most useful when the +transport is not raw TCP, like with SSL for example.</p></div> +</div> +<div class="sect2"> +<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Ack timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div> +<div class="paragraph"><p>This function will be called by connection processes +before performing any socket operation. It allows +transports that require extra initialization to perform +their task and make the socket ready to use.</p></div> +</div> +<div class="sect2"> +<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Close the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +Pid = pid() +</dt> +<dd> +<p> +Pid of the new owner of the socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change the controlling process for the given socket.</p></div> +<div class="paragraph"><p>The controlling process is the process that is allowed to +perform operations on the socket, and that will receive +messages from the socket when active mode is used. When +the controlling process dies, the socket is closed.</p></div> +</div> +<div class="sect2"> +<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +LSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Listen for connections on the given port.</p></div> +<div class="paragraph"><p>The port is given as part of the transport options under +the key <code>port</code>. Any other option is transport dependent.</p></div> +<div class="paragraph"><p>The socket returned by this call can then be used to +accept connections. It is not possible to send or receive +data from the listening socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +OK = Closed = Error = atom() +</dt> +<dd> +<p> +Tuple names. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div> +</div> +<div class="sect2"> +<h3 id="_name_8594_name">name() → Name</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name = atom() +</dt> +<dd> +<p> +Transport module name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the name of the transport.</p></div> +</div> +<div class="sect2"> +<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the remote endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the remote endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div> +</div> +<div class="sect2"> +<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Length = non_neg_integer() +</dt> +<dd> +<p> +Requested length. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Receive timeout. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() | any() +</dt> +<dd> +<p> +Data received. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div> +<div class="paragraph"><p>Trying to receive data from a socket that is in active mode +will return an error.</p></div> +<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div> +<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>, +this is highly discouraged as this could cause your process +to get stuck waiting for data that will never come. This may +happen when a socket becomes half-open due to a crash of the +remote endpoint. Wi-Fi going down is another common culprit +of this issue.</p></div> +</div> +<div class="sect2"> +<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() +</dt> +<dd> +<p> +Data to be sent. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data to the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>The file may be sent full or in parts, and may be specified +by its filename or by an already open file descriptor.</p></div> +<div class="paragraph"><p>Transports that manipulate TCP directly may use the +<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile +syscall where applicable (on Linux, for example). Other +transports can use the <code>sendfile/6</code> function exported from +this module.</p></div> +</div> +<div class="sect2"> +<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +SockOpts = any() +</dt> +<dd> +<p> +Socket options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change options for the given socket.</p></div> +<div class="paragraph"><p>This is mainly useful for switching to active or passive mode +or to set protocol-specific options.</p></div> +</div> +<div class="sect2"> +<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +How = read | write | read_write +</dt> +<dd> +<p> +Which side(s) of the socket to close. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div> +</div> +<div class="sect2"> +<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the local endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the local endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code> +and may be used when transports are not manipulating TCP +directly.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.3/guide/embedded/index.html b/docs/en/ranch/1.3/guide/embedded/index.html index eea4e32b..a1d552af 100644 --- a/docs/en/ranch/1.3/guide/embedded/index.html +++ b/docs/en/ranch/1.3/guide/embedded/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Embedded mode</title> @@ -67,54 +67,57 @@ <h1 class="lined-header"><span>Embedded mode</span></h1> -<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly
-in your supervision tree. This allows for greater fault tolerance
-control by permitting the shutdown of a listener due to the
-failure of another part of the application and vice versa.</p></div>
-<div class="sect1">
-<h2 id="_embedding">Embedding</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs
-to your supervision tree. This can all be done in the <code>init/1</code> function
-of one of your application supervisors.</p></div>
-<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding.
-First, you need to add <code>ranch_sup</code> to your supervision tree, only once,
-regardless of the number of listeners you will use. Then you need to
-add the child specs for each listener.</p></div>
-<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs
-called <code>ranch:child_spec/5</code>, that works like <code>ranch:start_listener/5</code>,
-except that it doesn’t start anything, it only returns child specs.</p></div>
-<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a
-convenience function.</p></div>
-<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another
-application’s supervision tree.</p></div>
-<div class="listingblock">
-<div class="title">Embed Ranch directly in your supervision tree</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">init</span></span>([]) <span style="color: #990000">-></span>
- <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []},
- <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]},
- <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
- ),
- {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only
-one <code>ranch_sup</code> spec!</p></div>
-<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners
-are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for
-more details on how Ranch does it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa.</p></div> +<div class="sect1"> +<h2 id="_embedding">Embedding</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the <code>init/1</code> function +of one of your application supervisors.</p></div> +<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add <code>ranch_sup</code> to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener.</p></div> +<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs +called <code>ranch:child_spec/5</code>, that works like <code>ranch:start_listener/5</code>, +except that it doesn’t start anything, it only returns child specs.</p></div> +<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a +convenience function.</p></div> +<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another +application’s supervision tree.</p></div> +<div class="listingblock"> +<div class="title">Embed Ranch directly in your supervision tree</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">init</span></span>([]) <span style="color: #990000">-></span> + <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []}, + <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]}, + <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] + ), + {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only +one <code>ranch_sup</code> spec!</p></div> +<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners +are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for +more details on how Ranch does it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/index.html b/docs/en/ranch/1.3/guide/index.html index 11fff995..e9986a13 100644 --- a/docs/en/ranch/1.3/guide/index.html +++ b/docs/en/ranch/1.3/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch User Guide</title> @@ -67,48 +67,48 @@ <h1 class="lined-header"><span>Ranch User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<a href="transports/">Transports</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="embedded/">Embedded mode</a>
-</p>
-</li>
-<li>
-<p>
-<a href="parsers/">Writing parsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ssl_auth/">SSL client authentication</a>
-</p>
-</li>
-<li>
-<p>
-<a href="internals/">Internals</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="listeners/">Listeners</a> +</p> +</li> +<li> +<p> +<a href="transports/">Transports</a> +</p> +</li> +<li> +<p> +<a href="protocols/">Protocols</a> +</p> +</li> +<li> +<p> +<a href="embedded/">Embedded mode</a> +</p> +</li> +<li> +<p> +<a href="parsers/">Writing parsers</a> +</p> +</li> +<li> +<p> +<a href="ssl_auth/">SSL client authentication</a> +</p> +</li> +<li> +<p> +<a href="internals/">Internals</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.3/guide/internals/index.html b/docs/en/ranch/1.3/guide/internals/index.html index 7a08d075..f75bc639 100644 --- a/docs/en/ranch/1.3/guide/internals/index.html +++ b/docs/en/ranch/1.3/guide/internals/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Internals</title> @@ -67,99 +67,102 @@ <h1 class="lined-header"><span>Internals</span></h1> -<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you
-to use an architecture specific to your application, which may or may
-not be compatible with the description of the Ranch application.</p></div>
-<div class="paragraph"><p>Note that for everything related to efficiency and performance,
-you should perform the benchmarks yourself to get the numbers that
-matter to you. Generic benchmarks found on the web may or may not
-be of use to you, you can never know until you benchmark your own
-system.</p></div>
-<div class="sect1">
-<h2 id="_architecture">Architecture</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is an OTP application.</p></div>
-<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible
-for supervising the <code>ranch_server</code> process and all the listeners that
-will be started.</p></div>
-<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the
-listeners and their acceptors. It does so through the use of a public ets
-table called <code>ranch_server</code>. The table is owned by the top supervisor
-to improve fault tolerance. This way if the <code>ranch_server</code> gen_server
-fails, it doesn’t lose any information and the restarted process can
-continue as if nothing happened.</p></div>
-<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor
-keeps track of the number of connections and handles connection limits
-directly. While it is heavily optimized to perform the task of creating
-connection processes for accepted connections, it is still following the
-OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on
-it as expected.</p></div>
-<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and
-consist of three kinds of processes: the listener gen_server, the
-acceptor processes and the connection processes, both grouped under
-their own supervisor. All of these processes are registered to the
-<code>ranch_server</code> gen_server with varying amount of information.</p></div>
-<div class="paragraph"><p>All socket operations, including listening for connections, go through
-transport handlers. Accepted connections are given to the protocol handler.
-Transport handlers are simple callback modules for performing operations on
-sockets. Protocol handlers start a new process, which receives socket
-ownership, with no requirements on how the code should be written inside
-that new process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_number_of_acceptors">Number of acceptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The second argument to <code>ranch:start_listener/5</code> is the number of
-processes that will be accepting connections. Care should be taken
-when choosing this number.</p></div>
-<div class="paragraph"><p>First of all, it should not be confused with the maximum number
-of connections. Acceptor processes are only used for accepting and
-have nothing else in common with connection processes. Therefore
-there is nothing to be gained from setting this number too high,
-in fact it can slow everything else down.</p></div>
-<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept
-connections concurrently. But the number of cores available doesn’t
-seem to be the only factor for choosing this number, as we can
-observe faster accepts if we have more acceptors than cores. It
-might be entirely dependent on the protocol, however.</p></div>
-<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware
-is a good solution, as it’s big enough to always have acceptors ready
-and it’s low enough that it doesn’t have a negative impact on the
-system’s performances.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>.
-They can be of interest because they generally are related to
-optimizations provided by the underlying OS. They can still be enabled
-thanks to the <code>raw</code> option, for which we will see an example.</p></div>
-<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified
-accept mechanism which will wait for application data to come in before
-handing out the connection to the Erlang process.</p></div>
-<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly
-idle, perhaps part of a connection pool. They can be handled by the
-kernel directly until they send any real data, instead of allocating
-resources to idle connections.</p></div>
-<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div>
-<div class="listingblock">
-<div class="title">Using raw transport 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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div>
-<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application.</p></div> +<div class="paragraph"><p>Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system.</p></div> +<div class="sect1"> +<h2 id="_architecture">Architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is an OTP application.</p></div> +<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the <code>ranch_server</code> process and all the listeners that +will be started.</p></div> +<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called <code>ranch_server</code>. The table is owned by the top supervisor +to improve fault tolerance. This way if the <code>ranch_server</code> gen_server +fails, it doesn’t lose any information and the restarted process can +continue as if nothing happened.</p></div> +<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on +it as expected.</p></div> +<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +<code>ranch_server</code> gen_server with varying amount of information.</p></div> +<div class="paragraph"><p>All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_number_of_acceptors">Number of acceptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The second argument to <code>ranch:start_listener/5</code> is the number of +processes that will be accepting connections. Care should be taken +when choosing this number.</p></div> +<div class="paragraph"><p>First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down.</p></div> +<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn’t +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however.</p></div> +<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it’s big enough to always have acceptors ready +and it’s low enough that it doesn’t have a negative impact on the +system’s performances.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the <code>raw</code> option, for which we will see an example.</p></div> +<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process.</p></div> +<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections.</p></div> +<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div> +<div class="listingblock"> +<div class="title">Using raw transport 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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div> +<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/introduction/index.html b/docs/en/ranch/1.3/guide/introduction/index.html index 8997b000..9c795d8b 100644 --- a/docs/en/ranch/1.3/guide/introduction/index.html +++ b/docs/en/ranch/1.3/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,40 +67,43 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div>
-<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections
-with a small code base and low latency while being easy to use directly
-as an application or to embed into your own.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience
-with socket programming and TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_supported_platforms">Supported platforms</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.</p></div>
-<div class="paragraph"><p>Ranch is developed for Erlang/OTP R16B+.</p></div>
-<div class="paragraph"><p>There are known issues with the SSL application found in Erlang/OTP
-18.3.2 and 18.3.3. These versions are therefore not supported.</p></div>
-<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code
-modifications but there is no guarantee that it will work as expected.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div>
-</div>
-</div>
+<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div> +<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supported_platforms">Supported platforms</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.</p></div> +<div class="paragraph"><p>Ranch is developed for Erlang/OTP R16B+.</p></div> +<div class="paragraph"><p>There are known issues with the SSL application found in Erlang/OTP +18.3.2 and 18.3.3. These versions are therefore not supported.</p></div> +<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/listeners/index.html b/docs/en/ranch/1.3/guide/listeners/index.html index 6cc4d0a1..bb7f3310 100644 --- a/docs/en/ranch/1.3/guide/listeners/index.html +++ b/docs/en/ranch/1.3/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,373 +67,376 @@ <h1 class="lined-header"><span>Listeners</span></h1> -<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port
-for new connections. It manages a pool of acceptor processes, each
-of them indefinitely accepting connections. When it does, it starts
-a new process executing the protocol handler code. All the socket
-programming is abstracted through the use of transport handlers.</p></div>
-<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection
-processes, allowing developers to focus on building their application.</p></div>
-<div class="sect1">
-<h2 id="_starting_a_listener">Starting a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer
-to request that Ranch listens for connections.</p></div>
-<div class="paragraph"><p>A listener can be started and stopped at will.</p></div>
-<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A name to identify it locally and be able to interact with it.
-</p>
-</li>
-<li>
-<p>
-The number of acceptors in the pool.
-</p>
-</li>
-<li>
-<p>
-A transport handler and its associated options.
-</p>
-</li>
-<li>
-<p>
-A protocol handler and its associated options.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively
-<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div>
-<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code>
-function. Before doing so however, you must ensure that the <code>ranch</code>
-application is started.</p></div>
-<div class="listingblock">
-<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will
-have a pool of 100 acceptors, use a TCP transport and forward connections
-to the <code>echo_protocol</code> handler.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on port 5555</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the
-examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em>
-directory and run the following command:</p></div>
-<div class="listingblock">
-<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div>
-<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply
-everything you send to it. Then when you’re done testing, you can use
-the <code>Ctrl+]</code> key to escape to the telnet command line and type
-<code>quit</code> to exit.</p></div>
-<div class="listingblock">
-<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span>
-Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span>
-Connected to localhost<span style="color: #990000">.</span>
-Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span>
-Hello<span style="color: #990000">!</span>
-Hello<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-<span style="color: #990000">^]</span>
-
-telnet<span style="color: #990000">></span> quit
-Connection closed<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stopping_a_listener">Stopping a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All you need to stop a Ranch listener is to call the
-<code>ranch:stop_listener/1</code> function with the listener’s name
-as argument. In the previous section we started the listener
-named <code>tcp_echo</code>. We can now stop it.</p></div>
-<div class="listingblock">
-<div class="title">Stopping a listener</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">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_default_transport_options">Default transport options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the
-options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set.
-These values can’t be overriden when starting the listener, but
-they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div>
-<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which
-can be overriden at listener startup.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_a_random_port">Listening on a random port</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give
-the port number 0, or if you omit the port number entirely, Ranch will
-start listening on a random port.</p></div>
-<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The
-argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on a random port</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span>
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons.
-This can easily be identified by an <code>{error, eacces}</code> error when trying
-to open a listening socket on such a port.</p></div>
-<div class="paragraph"><p>The methods for listening on privileged ports vary between systems,
-please refer to your system’s documentation for more information.</p></div>
-<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server,
-and load balancing for systems with multiple servers. Documenting these
-solutions is however out of the scope of this guide.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the
-<code>socket</code> transport option, which should just be the relevant data returned
-from the connect function for the transport or the underlying socket library
-(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be
-called on the passed in socket. You should connect the socket in
-<code>{active, false}</code> mode, as well.</p></div>
-<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an
-SSL listen socket prior to R16. Ranch will catch the error thrown, but the
-owner of the SSL socket will remain as whatever process created the socket.
-However, this will not affect accept behaviour unless the owner process dies,
-in which case the socket is closed. Therefore, to use this feature with SSL
-with an erlang release prior to R16, ensure that the SSL socket is opened in a
-persistant process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number
-of concurrent connections. It defaults to 1024. Its purpose is to
-prevent your system from being overloaded and ensuring all the
-connections are handled optimally.</p></div>
-<div class="listingblock">
-<div class="title">Customizing the maximum number of concurrent connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div>
-<div class="listingblock">
-<div class="title">Disabling the limit for the number of connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The maximum number of connections is a soft limit. In practice, it
-can reach <code>max_connections</code> + the number of acceptors.</p></div>
-<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop
-accepting connections. This will not result in further connections
-being rejected, as the kernel option allows queueing incoming
-connections. The size of this queue is determined by the <code>backlog</code>
-option and defaults to 1024. Ranch does not know about the number
-of connections that are in the backlog.</p></div>
-<div class="paragraph"><p>You may not always want connections to be counted when checking for
-<code>max_connections</code>. For example you might have a protocol where both
-short-lived and long-lived connections are possible. If the long-lived
-connections are mostly waiting for messages, then they don’t consume
-much resources and can safely be removed from the count.</p></div>
-<div class="paragraph"><p>To remove the connection from the count, you must call the
-<code>ranch:remove_connection/1</code> from within the connection process,
-with the name of the listener as the only argument.</p></div>
-<div class="listingblock">
-<div class="title">Removing a connection from the count of connections</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">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the
-first argument of the protocol’s <code>start_link/4</code> callback.</p></div>
-<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by
-using the <code>ranch:set_max_connections/2</code> function, with the name of the
-listener as first argument and the new value as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the maximum number of connections</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">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The change will occur immediately.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is
-to accept connections and spawn a connection process for every
-new connection.</p></div>
-<div class="paragraph"><p>This number can be tweaked to improve performance. A good
-number is typically between 10 or 100 acceptors. You must
-measure to find the best value for your application.</p></div>
-<div class="listingblock">
-<div class="title">Specifying a custom number of acceptor processes</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Operating systems have limits on the number of sockets
-which can be opened by applications. When this maximum is
-reached the listener can no longer accept new connections. The
-accept rate of the listener will be automatically reduced, and a
-warning message will be logged.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 ===
-Ranch acceptor reducing accept rate: out of file descriptors</code></pre>
-</div></div>
-<div class="paragraph"><p>If you notice messages like this you should increase the number
-of file-descriptors which can be opened by your application. How
-this should be done is operating-system dependent. Please consult
-the documentation of your operating system.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to define the type of process that will be used
-for the connection processes. By default it expects a <code>worker</code>.
-When the <code>connection_type</code> configuration value is set to <code>supervisor</code>,
-Ranch will consider that the connection process it manages is a
-supervisor and will reflect that in its supervision tree.</p></div>
-<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the
-socket directly or through one of their children. In the latter
-case the start function for the connection process must return
-two pids: the pid of the supervisor you created (that will be
-supervised) and the pid of the protocol handling process (that
-will receive the socket).</p></div>
-<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return
-<code>{ok, SupPid, ConnPid}</code>.</p></div>
-<div class="paragraph"><p>It is very important that the connection process be created
-under the supervisor process so that everything works as intended.
-If not, you will most likely experience issues when the supervised
-process is stopped.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading">Upgrading</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect
-immediately and for all subsequent connections.</p></div>
-<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code>
-with the name of the listener as first argument and the new options
-as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the protocol 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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All future connections will use the new options.</p></div>
-<div class="paragraph"><p>You can also retrieve the current options similarly by
-calling <code>ranch:get_protocol_options/1</code>.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the current protocol 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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch provides two functions for retrieving information about the
-listeners, for reporting and diagnostic purposes.</p></div>
-<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information
-about all listeners.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving detailed information</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">ranch:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener
-processes for a given listener.</p></div>
-<div class="listingblock">
-<div class="title">Get all acceptor processes</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">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get all connection processes</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">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the use of transport handlers.</p></div> +<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application.</p></div> +<div class="sect1"> +<h2 id="_starting_a_listener">Starting a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections.</p></div> +<div class="paragraph"><p>A listener can be started and stopped at will.</p></div> +<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div> +<div class="ulist"><ul> +<li> +<p> +A name to identify it locally and be able to interact with it. +</p> +</li> +<li> +<p> +The number of acceptors in the pool. +</p> +</li> +<li> +<p> +A transport handler and its associated options. +</p> +</li> +<li> +<p> +A protocol handler and its associated options. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively +<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div> +<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code> +function. Before doing so however, you must ensure that the <code>ranch</code> +application is started.</p></div> +<div class="listingblock"> +<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the <code>echo_protocol</code> handler.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on port 5555</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the +examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em> +directory and run the following command:</p></div> +<div class="listingblock"> +<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div> +<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you’re done testing, you can use +the <code>Ctrl+]</code> key to escape to the telnet command line and type +<code>quit</code> to exit.</p></div> +<div class="listingblock"> +<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span> +Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span> +Connected to localhost<span style="color: #990000">.</span> +Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span> +Hello<span style="color: #990000">!</span> +Hello<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +<span style="color: #990000">^]</span> + +telnet<span style="color: #990000">></span> quit +Connection closed<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stopping_a_listener">Stopping a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All you need to stop a Ranch listener is to call the +<code>ranch:stop_listener/1</code> function with the listener’s name +as argument. In the previous section we started the listener +named <code>tcp_echo</code>. We can now stop it.</p></div> +<div class="listingblock"> +<div class="title">Stopping a listener</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">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_default_transport_options">Default transport options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the +options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set. +These values can’t be overriden when starting the listener, but +they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div> +<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which +can be overriden at listener startup.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_a_random_port">Listening on a random port</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port.</p></div> +<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The +argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on a random port</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span> +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an <code>{error, eacces}</code> error when trying +to open a listening socket on such a port.</p></div> +<div class="paragraph"><p>The methods for listening on privileged ports vary between systems, +please refer to your system’s documentation for more information.</p></div> +<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the +<code>socket</code> transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be +called on the passed in socket. You should connect the socket in +<code>{active, false}</code> mode, as well.</p></div> +<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally.</p></div> +<div class="listingblock"> +<div class="title">Customizing the maximum number of concurrent connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div> +<div class="listingblock"> +<div class="title">Disabling the limit for the number of connections</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The maximum number of connections is a soft limit. In practice, it +can reach <code>max_connections</code> + the number of acceptors.</p></div> +<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop +accepting connections. This will not result in further connections +being rejected, as the kernel option allows queueing incoming +connections. The size of this queue is determined by the <code>backlog</code> +option and defaults to 1024. Ranch does not know about the number +of connections that are in the backlog.</p></div> +<div class="paragraph"><p>You may not always want connections to be counted when checking for +<code>max_connections</code>. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don’t consume +much resources and can safely be removed from the count.</p></div> +<div class="paragraph"><p>To remove the connection from the count, you must call the +<code>ranch:remove_connection/1</code> from within the connection process, +with the name of the listener as the only argument.</p></div> +<div class="listingblock"> +<div class="title">Removing a connection from the count of connections</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">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol’s <code>start_link/4</code> callback.</p></div> +<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by +using the <code>ranch:set_max_connections/2</code> function, with the name of the +listener as first argument and the new value as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the maximum number of connections</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">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The change will occur immediately.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is +to accept connections and spawn a connection process for every +new connection.</p></div> +<div class="paragraph"><p>This number can be tweaked to improve performance. A good +number is typically between 10 or 100 acceptors. You must +measure to find the best value for your application.</p></div> +<div class="listingblock"> +<div class="title">Specifying a custom number of acceptor processes</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Operating systems have limits on the number of sockets +which can be opened by applications. When this maximum is +reached the listener can no longer accept new connections. The +accept rate of the listener will be automatically reduced, and a +warning message will be logged.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 === +Ranch acceptor reducing accept rate: out of file descriptors</code></pre> +</div></div> +<div class="paragraph"><p>If you notice messages like this you should increase the number +of file-descriptors which can be opened by your application. How +this should be done is operating-system dependent. Please consult +the documentation of your operating system.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a <code>worker</code>. +When the <code>connection_type</code> configuration value is set to <code>supervisor</code>, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree.</p></div> +<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket).</p></div> +<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return +<code>{ok, SupPid, ConnPid}</code>.</p></div> +<div class="paragraph"><p>It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading">Upgrading</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections.</p></div> +<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code> +with the name of the listener as first argument and the new options +as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the protocol 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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All future connections will use the new options.</p></div> +<div class="paragraph"><p>You can also retrieve the current options similarly by +calling <code>ranch:get_protocol_options/1</code>.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the current protocol 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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch provides two functions for retrieving information about the +listeners, for reporting and diagnostic purposes.</p></div> +<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information +about all listeners.</p></div> +<div class="listingblock"> +<div class="title">Retrieving detailed information</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">ranch:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener +processes for a given listener.</p></div> +<div class="listingblock"> +<div class="title">Get all acceptor processes</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">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get all connection processes</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">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/parsers/index.html b/docs/en/ranch/1.3/guide/parsers/index.html index 67fef620..41f19b7e 100644 --- a/docs/en/ranch/1.3/guide/parsers/index.html +++ b/docs/en/ranch/1.3/guide/parsers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Writing parsers</title> @@ -67,115 +67,118 @@ <h1 class="lined-header"><span>Writing parsers</span></h1> -<div class="paragraph"><p>There are three kinds of protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Text protocols
-</p>
-</li>
-<li>
-<p>
-Schema-less binary protocols
-</p>
-</li>
-<li>
-<p>
-Schema-based binary protocols
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover
-more advanced topics such as continuations or parser generators.</p></div>
-<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that
-you know how to read data from the socket. The data you read and
-the data that hasn’t been parsed is saved in a buffer. Every
-time you read from the socket, the data read is appended to the
-buffer. What happens next depends on the kind of protocol. We
-will only cover the first two.</p></div>
-<div class="sect1">
-<h2 id="_parsing_text">Parsing text</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t
-do anything with them until we receive the full line.</p></div>
-<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/2 to get a line of input</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000">_</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>);
- [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was
-a line break in the buffer and we get it split into two parts,
-the line and the rest of the buffer; or there was no line break
-in the buffer and we need to get more data from the socket.</p></div>
-<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again
-split, here on space. The difference is that we want to split
-on all spaces character, as we want to tokenize the whole string.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/3 to split text</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>();
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>);
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>)
- <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest
-of the tokens in variables and call the respective functions.</p></div>
-<div class="paragraph"><p>After doing this, you will want to check if there is another
-line in the buffer, and handle it immediately if any.
-Otherwise wait for more data.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_parsing_binary">Parsing binary</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Binary protocols can be more varied, although most of them are
-pretty similar. The first four bytes of a frame tend to be
-the size of the frame, which is followed by a certain number
-of bytes for the type of frame and then various parameters.</p></div>
-<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes,
-sometimes not. Other times this size is encoded over two bytes.
-And even other times little-endian is used instead of big-endian.</p></div>
-<div class="paragraph"><p>The general idea stays the same though.</p></div>
-<div class="listingblock">
-<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>,
-<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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>You will then need to parse this frame using binary pattern
-matching, and handle it. Then you will want to check if there
-is another frame fully received in the buffer, and handle it
-immediately if any. Otherwise wait for more data.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>There are three kinds of protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +Text protocols +</p> +</li> +<li> +<p> +Schema-less binary protocols +</p> +</li> +<li> +<p> +Schema-based binary protocols +</p> +</li> +</ul></div> +<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators.</p></div> +<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn’t been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two.</p></div> +<div class="sect1"> +<h2 id="_parsing_text">Parsing text</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t +do anything with them until we receive the full line.</p></div> +<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/2 to get a line of input</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000">_</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>); + [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket.</p></div> +<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/3 to split text</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">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>(); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions.</p></div> +<div class="paragraph"><p>After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_parsing_binary">Parsing binary</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters.</p></div> +<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian.</p></div> +<div class="paragraph"><p>The general idea stays the same though.</p></div> +<div class="listingblock"> +<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>, +<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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>You will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/protocols/index.html b/docs/en/ranch/1.3/guide/protocols/index.html index 45e13bf7..d42e9d7d 100644 --- a/docs/en/ranch/1.3/guide/protocols/index.html +++ b/docs/en/ranch/1.3/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Protocols</title> @@ -67,110 +67,113 @@ <h1 class="lined-header"><span>Protocols</span></h1> -<div class="paragraph"><p>A protocol handler starts a connection process and defines the
-protocol logic executed in this process.</p></div>
-<div class="sect1">
-<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior
-which defines a single callback, <code>start_link/4</code>. This callback is
-responsible for spawning a new process for handling the connection.
-It receives four arguments: the name of the listener, the socket, the
-transport handler being used and the protocol options defined in
-the call to <code>ranch:start_listener/5</code>. This callback must
-return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div>
-<div class="paragraph"><p>The newly started process can then freely initialize itself. However,
-it must call <code>ranch:accept_ack/1</code> before doing any socket operation.
-This will ensure the connection process is the owner of the socket.
-It expects the listener’s name as argument.</p></div>
-<div class="listingblock">
-<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If your protocol code requires specific socket options, you should
-set them while initializing your connection process, after
-calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code>
-for that purpose.</p></div>
-<div class="paragraph"><p>Following is the complete protocol code for the example found
-in <code>examples/tcp_echo/</code>.</p></div>
-<div class="listingblock">
-<div class="title">Protocol module that echoes everything it receives</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: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</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="_using_gen_server">Using gen_server</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code>
-behaviours have the particularity of having their <code>start_link</code> call not
-return until the <code>init</code> function returns. This is problematic, because
-you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback
-as this would cause a deadlock to happen.</p></div>
-<div class="paragraph"><p>Use the <code>gen_server:enter_loop/3</code> function. It allows you to start your process
-normally (although it must be started with <code>proc_lib</code> like all special
-processes), then perform any needed operations before falling back into
-the normal <code>gen_server</code> execution loop.</p></div>
-<div class="listingblock">
-<div class="title">Use a gen_server for protocol handling</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: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>])<span style="color: #990000">.</span>
-<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">proc_lib:spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [{<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>}])}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>({<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []}) <span style="color: #990000">-></span>
- <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
- <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Check the <code>tcp_reverse</code> example for a complete example.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A protocol handler starts a connection process and defines the +protocol logic executed in this process.</p></div> +<div class="sect1"> +<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior +which defines a single callback, <code>start_link/4</code>. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to <code>ranch:start_listener/5</code>. This callback must +return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div> +<div class="paragraph"><p>The newly started process can then freely initialize itself. However, +it must call <code>ranch:accept_ack/1</code> before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener’s name as argument.</p></div> +<div class="listingblock"> +<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code> +for that purpose.</p></div> +<div class="paragraph"><p>Following is the complete protocol code for the example found +in <code>examples/tcp_echo/</code>.</p></div> +<div class="listingblock"> +<div class="title">Protocol module that echoes everything it receives</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: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</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="_using_gen_server">Using gen_server</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code> +behaviours have the particularity of having their <code>start_link</code> call not +return until the <code>init</code> function returns. This is problematic, because +you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback +as this would cause a deadlock to happen.</p></div> +<div class="paragraph"><p>Use the <code>gen_server:enter_loop/3</code> function. It allows you to start your process +normally (although it must be started with <code>proc_lib</code> like all special +processes), then perform any needed operations before falling back into +the normal <code>gen_server</code> execution loop.</p></div> +<div class="listingblock"> +<div class="title">Use a gen_server for protocol handling</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: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>])<span style="color: #990000">.</span> +<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">proc_lib:spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [{<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>}])}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>({<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []}) <span style="color: #990000">-></span> + <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), + <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div> +<div class="paragraph"><p>Check the <code>tcp_reverse</code> example for a complete example.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/ssl_auth/index.html b/docs/en/ranch/1.3/guide/ssl_auth/index.html index b831fbe2..3cc585f2 100644 --- a/docs/en/ranch/1.3/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.3/guide/ssl_auth/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: SSL client authentication</title> @@ -67,164 +67,167 @@ <h1 class="lined-header"><span>SSL client authentication</span></h1> -<div class="sect1">
-<h2 id="_purpose">Purpose</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to
-identify certificates. This allows your application to make sure that
-the client is an authorized certificate, but makes no claim about
-whether the user can be trusted. This can be combined with a password
-based authentication to attain greater security.</p></div>
-<div class="paragraph"><p>The server only needs to retain the certificate serial number and
-the certificate issuer to authenticate the certificate. Together,
-they can be used to uniquely identify a certicate.</p></div>
-<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and
-non-SSL transports, you need to make sure you are in an SSL context
-before attempting to perform an SSL client authentication. This
-can be done by checking the return value of <code>Transport:name/0</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can obtain client certificates from various sources. You can
-generate them yourself, or you can use a service like CAcert.org
-which allows you to generate client and server certificates for
-free.</p></div>
-<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org
-account, generate a certificate and install it in your favorite
-browser.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Open <a href="http://cacert.org">http://cacert.org</a> in your favorite browser
-</p>
-</li>
-<li>
-<p>
-Root Certificate link: install both certificates
-</p>
-</li>
-<li>
-<p>
-Join (Register an account)
-</p>
-</li>
-<li>
-<p>
-Verify your account (check your email inbox!)
-</p>
-</li>
-<li>
-<p>
-Log in
-</p>
-</li>
-<li>
-<p>
-Client Certificates: New
-</p>
-</li>
-<li>
-<p>
-Follow instructions to create the certificate
-</p>
-</li>
-<li>
-<p>
-Install the certificate in your browser
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>You can optionally save the certificate for later use, for example
-to extract the <code>IssuerID</code> information as will be detailed later on.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_transport_configuration">Transport configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport does not request a client certificate by default.
-You need to specify the <code>{verify, verify_peer}</code> option when starting
-the listener to enable this behavior.</p></div>
-<div class="listingblock">
-<div class="title">Configure a listener for SSL authentication</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>,
- <span style="color: #FF6600">ranch_ssl</span>, [
- {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>},
- {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>},
- {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>},
- {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>}
- ],
- <span style="color: #FF6600">my_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also
-the <code>cacertfile</code> containing the CACert.org root certificate, and
-the option to request the client certificate.</p></div>
-<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does
-not have a client certificate configured for your domain, then no
-certificate will be sent. This allows you to use SSL for more than
-just authenticated clients.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_authentication">Authentication</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To authenticate users, you must first save the certificate information
-required. If you have your users' certificate files, you can simply
-load the certificate and retrieve the information directly.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from a certificate</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">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>),
- [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number
-and the certificate issuer stored in a tuple, so this value alone can
-be used to uniquely identify the user certificate. You can save this
-value in a database, a configuration file or any other place where an
-Erlang term can be stored and retrieved.</p></div>
-<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first
-retrieve the client certificate and then extract this information from
-it. Ranch does not provide a function to retrieve the client certificate.
-Instead you can use the <code>ssl:peercert/1</code> function. Once you have the
-certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to
-extract the <code>IssuerID</code> value.</p></div>
-<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client
-certificate was found. This snippet is intended to be used from your
-protocol code.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from the certificate for the current 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">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span>
- <span style="color: #000080">false</span>;
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</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>You then only need to match the <code>IssuerID</code> value to authenticate the
-user.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_purpose">Purpose</h2> +<div class="sectionbody"> +<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security.</p></div> +<div class="paragraph"><p>The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate.</p></div> +<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of <code>Transport:name/0</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free.</p></div> +<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser.</p></div> +<div class="ulist"><ul> +<li> +<p> +Open <a href="http://cacert.org">http://cacert.org</a> in your favorite browser +</p> +</li> +<li> +<p> +Root Certificate link: install both certificates +</p> +</li> +<li> +<p> +Join (Register an account) +</p> +</li> +<li> +<p> +Verify your account (check your email inbox!) +</p> +</li> +<li> +<p> +Log in +</p> +</li> +<li> +<p> +Client Certificates: New +</p> +</li> +<li> +<p> +Follow instructions to create the certificate +</p> +</li> +<li> +<p> +Install the certificate in your browser +</p> +</li> +</ul></div> +<div class="paragraph"><p>You can optionally save the certificate for later use, for example +to extract the <code>IssuerID</code> information as will be detailed later on.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_transport_configuration">Transport configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport does not request a client certificate by default. +You need to specify the <code>{verify, verify_peer}</code> option when starting +the listener to enable this behavior.</p></div> +<div class="listingblock"> +<div class="title">Configure a listener for SSL authentication</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, + <span style="color: #FF6600">ranch_ssl</span>, [ + {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>}, + {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>}, + {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>}, + {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>} + ], + <span style="color: #FF6600">my_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also +the <code>cacertfile</code> containing the CACert.org root certificate, and +the option to request the client certificate.</p></div> +<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_authentication">Authentication</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from a certificate</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">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>), + [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved.</p></div> +<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the <code>ssl:peercert/1</code> function. Once you have the +certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to +extract the <code>IssuerID</code> value.</p></div> +<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client +certificate was found. This snippet is intended to be used from your +protocol code.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from the certificate for the current 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">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span> + <span style="color: #000080">false</span>; + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</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>You then only need to match the <code>IssuerID</code> value to authenticate the +user.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/transports/index.html b/docs/en/ranch/1.3/guide/transports/index.html index 56103db3..1b13c696 100644 --- a/docs/en/ranch/1.3/guide/transports/index.html +++ b/docs/en/ranch/1.3/guide/transports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Transports</title> @@ -67,185 +67,188 @@ <h1 class="lined-header"><span>Transports</span></h1> -<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div>
-<div class="paragraph"><p>Transports can be used for connecting, listening and accepting
-connections, but also for receiving and sending data. Both
-passive and active mode are supported, although all sockets
-are initialized as passive.</p></div>
-<div class="sect1">
-<h2 id="_tcp_transport">TCP transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ssl_transport">SSL transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>.</p></div>
-<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary
-dependencies will start when Ranch is started. It is
-possible to remove the dependency when the SSL transport
-will not be used. Refer to your release build tool’s
-documentation for more information.</p></div>
-<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport,
-your application must depend on the <code>ssl</code> application for
-proper behavior.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_and_receiving_data">Sending and receiving data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler
-(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected
-socket obtained through the listener.</p></div>
-<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code>
-function. The data can be given as <code>iodata()</code>, which is defined as
-<code>binary() | iolist()</code>. All the following calls will work:</p></div>
-<div class="listingblock">
-<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode
-means that you will perform a blocking <code>Transport:recv/3</code> call, while
-active mode means that you will receive the data as a message.</p></div>
-<div class="paragraph"><p>By default, all data will be received as binary. It is possible to
-receive data as strings, although this is not recommended as binaries
-are a more efficient construct, especially for binary protocols.</p></div>
-<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The
-first argument is the socket, and the third argument is a timeout duration
-before the call returns with <code>{error, timeout}</code>.</p></div>
-<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive.
-The function will wait for data until it has received exactly this amount.
-If you are not expecting a precise size, you can specify 0 which will make
-this call return as soon as data was read, regardless of its size.</p></div>
-<div class="listingblock">
-<div class="title">Receiving data from the socket in passive mode</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">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive
-data as a message and to write the code to actually receive it.</p></div>
-<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and
-<code>{active, true}</code>. The first will send a single message before going
-back to passive mode; the second will send messages indefinitely.
-We recommend not using the <code>{active, true}</code> mode as it could quickly
-flood your process mailbox. It’s better to keep the data in the socket
-and read it only when required.</p></div>
-<div class="paragraph"><p>Three different messages can be received:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>{OK, Socket, Data}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Closed, Socket}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Error, Socket, Reason}</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different
-depending on the transport being used. To be able to properly match
-on them you must first call the <code>Transport:messages/0</code> function.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code>
-function, and do so every time you want to receive data.</p></div>
-<div class="listingblock">
-<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(),
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
-<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</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">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]);
- {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>);
- {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</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>You can easily integrate active sockets with existing Erlang code as all
-you really need is just a few more clauses when receiving messages.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_files">Sending files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport
-handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div>
-<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file by filename</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">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of
-bytes and chunks of size <code>ChunkSize</code>:</p></div>
-<div class="listingblock">
-<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}],
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also
-possible to use a file descriptor opened in raw mode:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file opened in raw mode</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">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]),
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_a_transport_handler">Writing a transport handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior.
-It defines a certain number of callbacks that must be written in order to
-allow transparent usage of the transport handler.</p></div>
-<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a
-socket. These do not need to be common to all transports as it’s easy enough
-to write different initialization functions for the different transports that
-will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong>
-implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div>
-<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a
-fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument
-is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div> +<div class="paragraph"><p>Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive.</p></div> +<div class="sect1"> +<h2 id="_tcp_transport">TCP transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ssl_transport">SSL transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>.</p></div> +<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary +dependencies will start when Ranch is started. It is +possible to remove the dependency when the SSL transport +will not be used. Refer to your release build tool’s +documentation for more information.</p></div> +<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport, +your application must depend on the <code>ssl</code> application for +proper behavior.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_and_receiving_data">Sending and receiving data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler +(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected +socket obtained through the listener.</p></div> +<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code> +function. The data can be given as <code>iodata()</code>, which is defined as +<code>binary() | iolist()</code>. All the following calls will work:</p></div> +<div class="listingblock"> +<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking <code>Transport:recv/3</code> call, while +active mode means that you will receive the data as a message.</p></div> +<div class="paragraph"><p>By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols.</p></div> +<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with <code>{error, timeout}</code>.</p></div> +<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size.</p></div> +<div class="listingblock"> +<div class="title">Receiving data from the socket in passive mode</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">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it.</p></div> +<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and +<code>{active, true}</code>. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the <code>{active, true}</code> mode as it could quickly +flood your process mailbox. It’s better to keep the data in the socket +and read it only when required.</p></div> +<div class="paragraph"><p>Three different messages can be received:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>{OK, Socket, Data}</code> +</p> +</li> +<li> +<p> +<code>{Closed, Socket}</code> +</p> +</li> +<li> +<p> +<code>{Error, Socket, Reason}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different +depending on the transport being used. To be able to properly match +on them you must first call the <code>Transport:messages/0</code> function.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> +function, and do so every time you want to receive data.</p></div> +<div class="listingblock"> +<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(), +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), +<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</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">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]); + {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>); + {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</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>You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_files">Sending files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport +handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div> +<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div> +<div class="listingblock"> +<div class="title">Sending a file by filename</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">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of +bytes and chunks of size <code>ChunkSize</code>:</p></div> +<div class="listingblock"> +<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}], +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode:</p></div> +<div class="listingblock"> +<div class="title">Sending a file opened in raw mode</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">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]), +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_a_transport_handler">Writing a transport handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler.</p></div> +<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a +socket. These do not need to be common to all transports as it’s easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong> +implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div> +<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a +fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument +is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/manual/index.html b/docs/en/ranch/1.3/manual/index.html index a1122ab0..c0d63cf2 100644 --- a/docs/en/ranch/1.3/manual/index.html +++ b/docs/en/ranch/1.3/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch Function Reference</title> @@ -67,38 +67,38 @@ <h1 class="lined-header"><span>Ranch Function Reference</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="ranch_app">ranch(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch">ranch(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_protocol">ranch_protocol(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_ssl">ranch_ssl(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_tcp">ranch_tcp(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_transport">ranch_transport(3)</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="ranch_app">ranch(7)</a> +</p> +</li> +<li> +<p> +<a href="ranch">ranch(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_protocol">ranch_protocol(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_ssl">ranch_ssl(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_tcp">ranch_tcp(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_transport">ranch_transport(3)</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.3/manual/ranch/index.html b/docs/en/ranch/1.3/manual/ranch/index.html index 5c2f9f3e..b8b4b35d 100644 --- a/docs/en/ranch/1.3/manual/ranch/index.html +++ b/docs/en/ranch/1.3/manual/ranch/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(3)</title> @@ -67,567 +67,567 @@ <h1 class="lined-header"><span>ranch(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - socket acceptor pool</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and
-manipulating Ranch listeners.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3>
-<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div>
-<div class="paragraph"><p>This is a soft limit. The actual number of connections
-might be slightly above the limit due to concurrency
-when accepting new connections. Some connections may
-also be removed from this count explicitly by the user
-code.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>}
- | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()}
- | {<span style="color: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()}
- | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>}
- | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Ranch-specific transport options.</p></div>
-<div class="paragraph"><p>These options are not passed on to the transports.
-They are used by Ranch while setting up the listeners.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ref_any">ref() = any()</h3>
-<div class="paragraph"><p>Unique name used to refer to a listener.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ack_timeout (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish.
-</p>
-</dd>
-<dt class="hdlist1">
-connection_type (worker)
-</dt>
-<dd>
-<p>
- Type of process that will handle the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_connections (1024)
-</dt>
-<dd>
-<p>
- Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely.
-</p>
-</dd>
-<dt class="hdlist1">
-num_acceptors (10)
-</dt>
-<dd>
-<p>
- Number of processes that accept connections.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for children to stop on listener shutdown.
-</p>
-</dd>
-<dt class="hdlist1">
-socket
-</dt>
-<dd>
-<p>
- Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div>
-<div class="paragraph"><p>This function MUST be used by a connection process to inform
-Ranch that it initialized properly and let it perform any
-additional operations before the socket can be safely used.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_child_spec_ref_numacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NumAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return child specifications for a new listener.</p></div>
-<div class="paragraph"><p>This function can be used to embed a listener directly
-in an application instead of letting Ranch handle it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the interface used by this listener.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-Current maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Current protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_info_8594_ref_key_value">info() → [{Ref, [{Key, Value}]}]</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Key = atom()
-</dt>
-<dd>
-<p>
-Information key.
-</p>
-</dd>
-<dt class="hdlist1">
-Value = any()
-</dt>
-<dd>
-<p>
-Information value.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return detailed information about all Ranch listeners.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-pid
-</dt>
-<dd>
-<p>
-Pid of the listener’s top-level supervisor.
-</p>
-</dd>
-<dt class="hdlist1">
-ip
-</dt>
-<dd>
-<p>
-Interface Ranch listens on.
-</p>
-</dd>
-<dt class="hdlist1">
-port
-</dt>
-<dd>
-<p>
-Port number Ranch listens on.
-</p>
-</dd>
-<dt class="hdlist1">
-num_acceptors
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-max_connections
-</dt>
-<dd>
-<p>
-Maximum number of connections.
-</p>
-</dd>
-<dt class="hdlist1">
-active_connections
-</dt>
-<dd>
-<p>
-Number of active connections.
-</p>
-</dd>
-<dt class="hdlist1">
-all_connections
-</dt>
-<dd>
-<p>
-Number of connections, including those removed from the count.
-</p>
-</dd>
-<dt class="hdlist1">
-transport
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-transport_options
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-protocol
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-protocol_options
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_procs_ref_acceptors_connections_8594_pid">procs(Ref, acceptors | connections) → [pid()]</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return all acceptor or connection processes for one listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div>
-<div class="paragraph"><p>You can use this function for long-running connection processes
-which spend most of their time idling rather than consuming
-resources. This allows Ranch to accept a lot more connections
-without sacrificing the latency of the system.</p></div>
-<div class="paragraph"><p>This function may only be called from a connection process.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-New maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately. If the new value is
-smaller than the previous one, Ranch will not kill the extra
-connections, but will wait for them to terminate properly.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-New protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the protocol options for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately for all new connections.
-Old connections will not receive the new options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_start_listener_ref_numacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NumAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start listening for connections using the given transport
-and protocol. Returns the pid for this listener’s supervisor.</p></div>
-<div class="paragraph"><p>There are additional transport options that apply
-regardless of transport. They allow configuring how the
-connections are supervised, rate limited and more. Please
-consult the previous section for more details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stop the given listener.</p></div>
-<div class="paragraph"><p>The listener is stopped gracefully, first by closing the
-listening port, then by stopping the connection processes.
-These processes are stopped according to the <code>shutdown</code>
-transport option, which may be set to brutally kill all
-connection processes or give them some time to stop properly.</p></div>
-<div class="paragraph"><p>This function does not return until the listener is
-completely stopped.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - socket acceptor pool</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and +manipulating Ranch listeners.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3> +<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div> +<div class="paragraph"><p>This is a soft limit. The actual number of connections +might be slightly above the limit due to concurrency +when accepting new connections. Some connections may +also be removed from this count explicitly by the user +code.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>} + | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()} + | {<span style="color: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()} + | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>} + | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Ranch-specific transport options.</p></div> +<div class="paragraph"><p>These options are not passed on to the transports. +They are used by Ranch while setting up the listeners.</p></div> +</div> +<div class="sect2"> +<h3 id="_ref_any">ref() = any()</h3> +<div class="paragraph"><p>Unique name used to refer to a listener.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +ack_timeout (5000) +</dt> +<dd> +<p> + Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish. +</p> +</dd> +<dt class="hdlist1"> +connection_type (worker) +</dt> +<dd> +<p> + Type of process that will handle the connection. +</p> +</dd> +<dt class="hdlist1"> +max_connections (1024) +</dt> +<dd> +<p> + Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely. +</p> +</dd> +<dt class="hdlist1"> +num_acceptors (10) +</dt> +<dd> +<p> + Number of processes that accept connections. +</p> +</dd> +<dt class="hdlist1"> +shutdown (5000) +</dt> +<dd> +<p> + Maximum allowed time for children to stop on listener shutdown. +</p> +</dd> +<dt class="hdlist1"> +socket +</dt> +<dd> +<p> + Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div> +<div class="paragraph"><p>This function MUST be used by a connection process to inform +Ranch that it initialized properly and let it perform any +additional operations before the socket can be safely used.</p></div> +</div> +<div class="sect2"> +<h3 id="_child_spec_ref_numacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NumAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return child specifications for a new listener.</p></div> +<div class="paragraph"><p>This function can be used to embed a listener directly +in an application instead of letting Ranch handle it.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the interface used by this listener. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +Current maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Current protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_info_8594_ref_key_value">info() → [{Ref, [{Key, Value}]}]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Key = atom() +</dt> +<dd> +<p> +Information key. +</p> +</dd> +<dt class="hdlist1"> +Value = any() +</dt> +<dd> +<p> +Information value. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return detailed information about all Ranch listeners.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +pid +</dt> +<dd> +<p> +Pid of the listener’s top-level supervisor. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> +Interface Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +port +</dt> +<dd> +<p> +Port number Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +num_acceptors +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +max_connections +</dt> +<dd> +<p> +Maximum number of connections. +</p> +</dd> +<dt class="hdlist1"> +active_connections +</dt> +<dd> +<p> +Number of active connections. +</p> +</dd> +<dt class="hdlist1"> +all_connections +</dt> +<dd> +<p> +Number of connections, including those removed from the count. +</p> +</dd> +<dt class="hdlist1"> +transport +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +transport_options +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +protocol +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +protocol_options +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_procs_ref_acceptors_connections_8594_pid">procs(Ref, acceptors | connections) → [pid()]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return all acceptor or connection processes for one listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div> +<div class="paragraph"><p>You can use this function for long-running connection processes +which spend most of their time idling rather than consuming +resources. This allows Ranch to accept a lot more connections +without sacrificing the latency of the system.</p></div> +<div class="paragraph"><p>This function may only be called from a connection process.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +New maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will not kill the extra +connections, but will wait for them to terminate properly.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +New protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the protocol options for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately for all new connections. +Old connections will not receive the new options.</p></div> +</div> +<div class="sect2"> +<h3 id="_start_listener_ref_numacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NumAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start listening for connections using the given transport +and protocol. Returns the pid for this listener’s supervisor.</p></div> +<div class="paragraph"><p>There are additional transport options that apply +regardless of transport. They allow configuring how the +connections are supervised, rate limited and more. Please +consult the previous section for more details.</p></div> +</div> +<div class="sect2"> +<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stop the given listener.</p></div> +<div class="paragraph"><p>The listener is stopped gracefully, first by closing the +listening port, then by stopping the connection processes. +These processes are stopped according to the <code>shutdown</code> +transport option, which may be set to brutally kill all +connection processes or give them some time to stop properly.</p></div> +<div class="paragraph"><p>This function does not return until the listener is +completely stopped.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_app/index.html b/docs/en/ranch/1.3/manual/ranch_app/index.html index 3c834556..2ad98222 100644 --- a/docs/en/ranch/1.3/manual/ranch_app/index.html +++ b/docs/en/ranch/1.3/manual/ranch_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(7)</title> @@ -67,41 +67,41 @@ <h1 class="lined-header"><span>ranch(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application depends on the <code>ssl</code> application to
-start. It is used for handling secure connections, when the
-transport is <code>ranch_ssl</code>. It can be disabled if SSL is not
-used.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application defines one application environment
-configuration parameter.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-profile (false)
-</dt>
-<dd>
-<p>
- When enabled, Ranch will start <code>eprof</code> profiling automatically.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop
-profiling and output the results to the files <em>procs.profile</em>
-and <em>total.profile</em>. Do not use in production.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application depends on the <code>ssl</code> application to +start. It is used for handling secure connections, when the +transport is <code>ranch_ssl</code>. It can be disabled if SSL is not +used.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application defines one application environment +configuration parameter.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +profile (false) +</dt> +<dd> +<p> + When enabled, Ranch will start <code>eprof</code> profiling automatically. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop +profiling and output the results to the files <em>procs.profile</em> +and <em>total.profile</em>. Do not use in production.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_protocol/index.html b/docs/en/ranch/1.3/manual/ranch_protocol/index.html index 59f945d2..ce82c3f0 100644 --- a/docs/en/ranch/1.3/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.3/manual/ranch_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_protocol(3)</title> @@ -67,83 +67,83 @@ <h1 class="lined-header"><span>ranch_protocol(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used
-by Ranch protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ranch:ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start a new connection process for the given socket.</p></div>
-<div class="paragraph"><p>The only purpose of this callback is to start a process that
-will handle the socket. It must spawn the process, link and
-then return the new pid. This function will always be called
-from inside a supervisor.</p></div>
-<div class="paragraph"><p>This callback can also return two pids. The first pid is the
-pid of the process that will be supervised. The second pid is
-the pid of the process that will receive ownership of the
-socket. This second process must be a child of the first. This
-form is only available when <code>connection_type</code> is set to
-<code>supervisor</code>.</p></div>
-<div class="paragraph"><p>If any other value is returned, the supervisor will close the
-socket and assume no process has been started.</p></div>
-<div class="paragraph"><p>Do not perform any operations in this callback, as this would
-block the supervisor responsible for starting connection
-processes and degrade performance severely.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used +by Ranch protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ranch:ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start a new connection process for the given socket.</p></div> +<div class="paragraph"><p>The only purpose of this callback is to start a process that +will handle the socket. It must spawn the process, link and +then return the new pid. This function will always be called +from inside a supervisor.</p></div> +<div class="paragraph"><p>This callback can also return two pids. The first pid is the +pid of the process that will be supervised. The second pid is +the pid of the process that will receive ownership of the +socket. This second process must be a child of the first. This +form is only available when <code>connection_type</code> is set to +<code>supervisor</code>.</p></div> +<div class="paragraph"><p>If any other value is returned, the supervisor will close the +socket and assume no process has been started.</p></div> +<div class="paragraph"><p>Do not perform any operations in this callback, as this would +block the supervisor responsible for starting connection +processes and degrade performance severely.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_ssl/index.html b/docs/en/ranch/1.3/manual/ranch_ssl/index.html index d923f172..3a466dee 100644 --- a/docs/en/ranch/1.3/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.3/manual/ranch_ssl/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_ssl(3)</title> @@ -67,385 +67,385 @@ <h1 class="lined-header"><span>ranch_ssl(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_ssl_opt">ssl_opt()</h3>
-<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: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">beast_mitigation</span>, <span style="color: #FF6600">one_n_minus_one</span> | <span style="color: #FF6600">zero_n</span> | <span style="color: #FF6600">disabled</span>}
- | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]}
- | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}}
- | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>}
- | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>}
- | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>}
- | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}}
- | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">padding_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)}
- | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">signature_algs</span>, [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]}
- | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]}
- | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">v2_hello_compatible</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()}
- | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>SSL-specific listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3>
-<div class="paragraph"><p>Listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code>
-or the <code>certfile</code> option. None of the other options are required.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-alpn_preferred_protocols
-</dt>
-<dd>
-<p>
- Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.
-</p>
-</dd>
-<dt class="hdlist1">
-beast_mitigation
-</dt>
-<dd>
-<p>
- Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software.
-</p>
-</dd>
-<dt class="hdlist1">
-cacertfile
-</dt>
-<dd>
-<p>
- Path to PEM encoded trusted certificates file used to verify peer certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cacerts
-</dt>
-<dd>
-<p>
- List of DER encoded trusted certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cert
-</dt>
-<dd>
-<p>
- DER encoded user certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-certfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded user certificate file. May also contain the private key.
-</p>
-</dd>
-<dt class="hdlist1">
-ciphers
-</dt>
-<dd>
-<p>
- List of ciphers that clients are allowed to use.
-</p>
-</dd>
-<dt class="hdlist1">
-client_renegotiation (true)
-</dt>
-<dd>
-<p>
- Whether to allow client-initiated renegotiation.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_cache ({ssl_crl_cache, {internal, []}})
-</dt>
-<dd>
-<p>
- Customize the module used to cache Certificate Revocation Lists.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_check (false)
-</dt>
-<dd>
-<p>
- Whether to perform CRL check on all certificates in the chain during validation.
-</p>
-</dd>
-<dt class="hdlist1">
-depth (1)
-</dt>
-<dd>
-<p>
- Maximum of intermediate certificates allowed in the certification path.
-</p>
-</dd>
-<dt class="hdlist1">
-dh
-</dt>
-<dd>
-<p>
- DER encoded Diffie-Hellman parameters.
-</p>
-</dd>
-<dt class="hdlist1">
-dhfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded Diffie-Hellman parameters file.
-</p>
-</dd>
-<dt class="hdlist1">
-fail_if_no_peer_cert (false)
-</dt>
-<dd>
-<p>
- Whether to refuse the connection if the client sends an empty certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-hibernate_after (undefined)
-</dt>
-<dd>
-<p>
- Time in ms after which SSL socket processes go into hibernation to reduce memory usage.
-</p>
-</dd>
-<dt class="hdlist1">
-honor_cipher_order (false)
-</dt>
-<dd>
-<p>
- If true, use the server’s preference for cipher selection. If false, use the client’s preference.
-</p>
-</dd>
-<dt class="hdlist1">
-key
-</dt>
-<dd>
-<p>
- DER encoded user private key.
-</p>
-</dd>
-<dt class="hdlist1">
-keyfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded private key file, if different than the certfile.
-</p>
-</dd>
-<dt class="hdlist1">
-log_alert (true)
-</dt>
-<dd>
-<p>
- If false, error reports will not be displayed.
-</p>
-</dd>
-<dt class="hdlist1">
-next_protocols_advertised
-</dt>
-<dd>
-<p>
- List of protocols to send to the client if it supports the Next Protocol extension.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-padding_check
-</dt>
-<dd>
-<p>
- Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software.
-</p>
-</dd>
-<dt class="hdlist1">
-partial_chain
-</dt>
-<dd>
-<p>
- Claim an intermediate CA in the chain as trusted.
-</p>
-</dd>
-<dt class="hdlist1">
-password
-</dt>
-<dd>
-<p>
- Password to the private key file, if password protected.
-</p>
-</dd>
-<dt class="hdlist1">
-psk_identity
-</dt>
-<dd>
-<p>
- Provide the given PSK identity hint to the client during the handshake.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_session
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a session should be reused.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_sessions (false)
-</dt>
-<dd>
-<p>
- Whether to allow session reuse.
-</p>
-</dd>
-<dt class="hdlist1">
-secure_renegotiate (false)
-</dt>
-<dd>
-<p>
- Whether to reject renegotiation attempts that do not conform to RFC5746.
-</p>
-</dd>
-<dt class="hdlist1">
-signature_algs
-</dt>
-<dd>
-<p>
- The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_fun
-</dt>
-<dd>
-<p>
- Function called when the client requests a host using Server Name Indication. Returns options to apply.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_hosts
-</dt>
-<dd>
-<p>
- Options to apply for the host that matches what the client requested with Server Name Indication.
-</p>
-</dd>
-<dt class="hdlist1">
-user_lookup_fun
-</dt>
-<dd>
-<p>
- Function called to determine the shared secret when using PSK, or provide parameters when using SRP.
-</p>
-</dd>
-<dt class="hdlist1">
-v2_hello_compatible
-</dt>
-<dd>
-<p>
- Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions.
-</p>
-</dd>
-<dt class="hdlist1">
-verify (verify_none)
-</dt>
-<dd>
-<p>
- Use <code>verify_peer</code> to request a certificate from the client.
-</p>
-</dd>
-<dt class="hdlist1">
-verify_fun
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a client certificate is valid.
-</p>
-</dd>
-<dt class="hdlist1">
-versions
-</dt>
-<dd>
-<p>
- TLS protocol versions that will be supported.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Note that the client will not send a certificate unless the
-value for the <code>verify</code> option is set to <code>verify_peer</code>. This
-means that the <code>fail_if_no_peer_cert</code> only apply when combined
-with the <code>verify</code> option. The <code>verify_fun</code> option allows
-greater control over the client certificate validation.</p></div>
-<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_ssl_opt">ssl_opt()</h3> +<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: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">beast_mitigation</span>, <span style="color: #FF6600">one_n_minus_one</span> | <span style="color: #FF6600">zero_n</span> | <span style="color: #FF6600">disabled</span>} + | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]} + | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}} + | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>} + | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>} + | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>} + | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}} + | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">padding_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)} + | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">signature_algs</span>, [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]} + | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]} + | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">v2_hello_compatible</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()} + | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>SSL-specific listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> +<div class="paragraph"><p>Listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code> +or the <code>certfile</code> option. None of the other options are required.</p></div> +<div class="paragraph"><p>The default value is given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +alpn_preferred_protocols +</dt> +<dd> +<p> + Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. +</p> +</dd> +<dt class="hdlist1"> +beast_mitigation +</dt> +<dd> +<p> + Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software. +</p> +</dd> +<dt class="hdlist1"> +cacertfile +</dt> +<dd> +<p> + Path to PEM encoded trusted certificates file used to verify peer certificates. +</p> +</dd> +<dt class="hdlist1"> +cacerts +</dt> +<dd> +<p> + List of DER encoded trusted certificates. +</p> +</dd> +<dt class="hdlist1"> +cert +</dt> +<dd> +<p> + DER encoded user certificate. +</p> +</dd> +<dt class="hdlist1"> +certfile +</dt> +<dd> +<p> + Path to the PEM encoded user certificate file. May also contain the private key. +</p> +</dd> +<dt class="hdlist1"> +ciphers +</dt> +<dd> +<p> + List of ciphers that clients are allowed to use. +</p> +</dd> +<dt class="hdlist1"> +client_renegotiation (true) +</dt> +<dd> +<p> + Whether to allow client-initiated renegotiation. +</p> +</dd> +<dt class="hdlist1"> +crl_cache ({ssl_crl_cache, {internal, []}}) +</dt> +<dd> +<p> + Customize the module used to cache Certificate Revocation Lists. +</p> +</dd> +<dt class="hdlist1"> +crl_check (false) +</dt> +<dd> +<p> + Whether to perform CRL check on all certificates in the chain during validation. +</p> +</dd> +<dt class="hdlist1"> +depth (1) +</dt> +<dd> +<p> + Maximum of intermediate certificates allowed in the certification path. +</p> +</dd> +<dt class="hdlist1"> +dh +</dt> +<dd> +<p> + DER encoded Diffie-Hellman parameters. +</p> +</dd> +<dt class="hdlist1"> +dhfile +</dt> +<dd> +<p> + Path to the PEM encoded Diffie-Hellman parameters file. +</p> +</dd> +<dt class="hdlist1"> +fail_if_no_peer_cert (false) +</dt> +<dd> +<p> + Whether to refuse the connection if the client sends an empty certificate. +</p> +</dd> +<dt class="hdlist1"> +hibernate_after (undefined) +</dt> +<dd> +<p> + Time in ms after which SSL socket processes go into hibernation to reduce memory usage. +</p> +</dd> +<dt class="hdlist1"> +honor_cipher_order (false) +</dt> +<dd> +<p> + If true, use the server’s preference for cipher selection. If false, use the client’s preference. +</p> +</dd> +<dt class="hdlist1"> +key +</dt> +<dd> +<p> + DER encoded user private key. +</p> +</dd> +<dt class="hdlist1"> +keyfile +</dt> +<dd> +<p> + Path to the PEM encoded private key file, if different than the certfile. +</p> +</dd> +<dt class="hdlist1"> +log_alert (true) +</dt> +<dd> +<p> + If false, error reports will not be displayed. +</p> +</dd> +<dt class="hdlist1"> +next_protocols_advertised +</dt> +<dd> +<p> + List of protocols to send to the client if it supports the Next Protocol extension. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +padding_check +</dt> +<dd> +<p> + Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software. +</p> +</dd> +<dt class="hdlist1"> +partial_chain +</dt> +<dd> +<p> + Claim an intermediate CA in the chain as trusted. +</p> +</dd> +<dt class="hdlist1"> +password +</dt> +<dd> +<p> + Password to the private key file, if password protected. +</p> +</dd> +<dt class="hdlist1"> +psk_identity +</dt> +<dd> +<p> + Provide the given PSK identity hint to the client during the handshake. +</p> +</dd> +<dt class="hdlist1"> +reuse_session +</dt> +<dd> +<p> + Custom policy to decide whether a session should be reused. +</p> +</dd> +<dt class="hdlist1"> +reuse_sessions (false) +</dt> +<dd> +<p> + Whether to allow session reuse. +</p> +</dd> +<dt class="hdlist1"> +secure_renegotiate (false) +</dt> +<dd> +<p> + Whether to reject renegotiation attempts that do not conform to RFC5746. +</p> +</dd> +<dt class="hdlist1"> +signature_algs +</dt> +<dd> +<p> + The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake. +</p> +</dd> +<dt class="hdlist1"> +sni_fun +</dt> +<dd> +<p> + Function called when the client requests a host using Server Name Indication. Returns options to apply. +</p> +</dd> +<dt class="hdlist1"> +sni_hosts +</dt> +<dd> +<p> + Options to apply for the host that matches what the client requested with Server Name Indication. +</p> +</dd> +<dt class="hdlist1"> +user_lookup_fun +</dt> +<dd> +<p> + Function called to determine the shared secret when using PSK, or provide parameters when using SRP. +</p> +</dd> +<dt class="hdlist1"> +v2_hello_compatible +</dt> +<dd> +<p> + Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions. +</p> +</dd> +<dt class="hdlist1"> +verify (verify_none) +</dt> +<dd> +<p> + Use <code>verify_peer</code> to request a certificate from the client. +</p> +</dd> +<dt class="hdlist1"> +verify_fun +</dt> +<dd> +<p> + Custom policy to decide whether a client certificate is valid. +</p> +</dd> +<dt class="hdlist1"> +versions +</dt> +<dd> +<p> + TLS protocol versions that will be supported. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Note that the client will not send a certificate unless the +value for the <code>verify</code> option is set to <code>verify_peer</code>. This +means that the <code>fail_if_no_peer_cert</code> only apply when combined +with the <code>verify</code> option. The <code>verify_fun</code> option allows +greater control over the client certificate validation.</p></div> +<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_tcp/index.html b/docs/en/ranch/1.3/manual/ranch_tcp/index.html index b33bfd20..60574604 100644 --- a/docs/en/ranch/1.3/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.3/manual/ranch_tcp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_tcp(3)</title> @@ -67,283 +67,283 @@ <h1 class="lined-header"><span>ranch_tcp(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div>
-<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is
-recommended to disable async threads when using the
-<code>sendfile</code> function of this transport, as it can make
-the threads stuck indefinitely.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | <span style="color: #FF6600">inet</span>
- | <span style="color: #FF6600">inet6</span>
- | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()}
- | {<span style="color: #FF6600">ipv6_v6only</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}}
- | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
- | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}
- | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Listen options.</p></div>
-<div class="paragraph"><p>This does not represent the entirety of the options that can
-be set on the socket, but only the options that may be
-set independently of protocol implementation.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more
-thorough description of these options. This manual only aims
-to provide a short description along with what the defaults
-are. Defaults may be different in Ranch compared to <code>gen_tcp</code>.
-Defaults are given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-backlog (1024)
-</dt>
-<dd>
-<p>
- Max length of the queue of pending connections.
-</p>
-</dd>
-<dt class="hdlist1">
-buffer
-</dt>
-<dd>
-<p>
- Size of the buffer used by the Erlang driver. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-delay_send (false)
-</dt>
-<dd>
-<p>
- Always queue packets before sending, to send fewer, larger packets over the network.
-</p>
-</dd>
-<dt class="hdlist1">
-dontroute (false)
-</dt>
-<dd>
-<p>
- Don’t send via a gateway, only send to directly connected hosts.
-</p>
-</dd>
-<dt class="hdlist1">
-exit_on_close (true)
-</dt>
-<dd>
-<p>
- Disable to allow sending data after a close has been detected.
-</p>
-</dd>
-<dt class="hdlist1">
-fd
-</dt>
-<dd>
-<p>
- File descriptor of the socket, if it was opened externally.
-</p>
-</dd>
-<dt class="hdlist1">
-high_msgq_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the socket message queue before the socket queue becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-high_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-inet
-</dt>
-<dd>
-<p>
- Set up the socket for IPv4.
-</p>
-</dd>
-<dt class="hdlist1">
-inet6
-</dt>
-<dd>
-<p>
- Set up the socket for IPv6.
-</p>
-</dd>
-<dt class="hdlist1">
-ip
-</dt>
-<dd>
-<p>
- Interface to listen on. Listen on all interfaces by default.
-</p>
-</dd>
-<dt class="hdlist1">
-ipv6_v6only (false)
-</dt>
-<dd>
-<p>
- Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6.
-</p>
-</dd>
-<dt class="hdlist1">
-keepalive (false)
-</dt>
-<dd>
-<p>
- Enable sending of keep-alive messages.
-</p>
-</dd>
-<dt class="hdlist1">
-linger ({false, 0})
-</dt>
-<dd>
-<p>
- Whether to wait and how long to flush data sent before closing the socket.
-</p>
-</dd>
-<dt class="hdlist1">
-low_msgq_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the socket message queue before the socket queue leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-low_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-port (0)
-</dt>
-<dd>
-<p>
- TCP port number to listen on. 0 means a random port will be used.
-</p>
-</dd>
-<dt class="hdlist1">
-priority (0)
-</dt>
-<dd>
-<p>
- Priority value for all packets to be sent by this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-recbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s receive buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout (30000)
-</dt>
-<dd>
-<p>
- How long the send call may wait for confirmation before returning.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout_close (true)
-</dt>
-<dd>
-<p>
- Whether to close the socket when the confirmation wasn’t received.
-</p>
-</dd>
-<dt class="hdlist1">
-sndbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s send buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-tos
-</dt>
-<dd>
-<p>
- Value for the IP_TOS IP level option. Use with caution.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific
-options by specifying the protocol level, the option number and
-the actual option value specified as a binary. This option is not
-portable. Use with caution.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div> +<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is +recommended to disable async threads when using the +<code>sendfile</code> function of this transport, as it can make +the threads stuck indefinitely.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | <span style="color: #FF6600">inet</span> + | <span style="color: #FF6600">inet6</span> + | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()} + | {<span style="color: #FF6600">ipv6_v6only</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}} + | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} + | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()} + | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Listen options.</p></div> +<div class="paragraph"><p>This does not represent the entirety of the options that can +be set on the socket, but only the options that may be +set independently of protocol implementation.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to <code>gen_tcp</code>. +Defaults are given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +backlog (1024) +</dt> +<dd> +<p> + Max length of the queue of pending connections. +</p> +</dd> +<dt class="hdlist1"> +buffer +</dt> +<dd> +<p> + Size of the buffer used by the Erlang driver. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +delay_send (false) +</dt> +<dd> +<p> + Always queue packets before sending, to send fewer, larger packets over the network. +</p> +</dd> +<dt class="hdlist1"> +dontroute (false) +</dt> +<dd> +<p> + Don’t send via a gateway, only send to directly connected hosts. +</p> +</dd> +<dt class="hdlist1"> +exit_on_close (true) +</dt> +<dd> +<p> + Disable to allow sending data after a close has been detected. +</p> +</dd> +<dt class="hdlist1"> +fd +</dt> +<dd> +<p> + File descriptor of the socket, if it was opened externally. +</p> +</dd> +<dt class="hdlist1"> +high_msgq_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the socket message queue before the socket queue becomes busy. +</p> +</dd> +<dt class="hdlist1"> +high_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy. +</p> +</dd> +<dt class="hdlist1"> +inet +</dt> +<dd> +<p> + Set up the socket for IPv4. +</p> +</dd> +<dt class="hdlist1"> +inet6 +</dt> +<dd> +<p> + Set up the socket for IPv6. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> + Interface to listen on. Listen on all interfaces by default. +</p> +</dd> +<dt class="hdlist1"> +ipv6_v6only (false) +</dt> +<dd> +<p> + Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6. +</p> +</dd> +<dt class="hdlist1"> +keepalive (false) +</dt> +<dd> +<p> + Enable sending of keep-alive messages. +</p> +</dd> +<dt class="hdlist1"> +linger ({false, 0}) +</dt> +<dd> +<p> + Whether to wait and how long to flush data sent before closing the socket. +</p> +</dd> +<dt class="hdlist1"> +low_msgq_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the socket message queue before the socket queue leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +low_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +port (0) +</dt> +<dd> +<p> + TCP port number to listen on. 0 means a random port will be used. +</p> +</dd> +<dt class="hdlist1"> +priority (0) +</dt> +<dd> +<p> + Priority value for all packets to be sent by this socket. +</p> +</dd> +<dt class="hdlist1"> +recbuf +</dt> +<dd> +<p> + Minimum size of the socket’s receive buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +send_timeout (30000) +</dt> +<dd> +<p> + How long the send call may wait for confirmation before returning. +</p> +</dd> +<dt class="hdlist1"> +send_timeout_close (true) +</dt> +<dd> +<p> + Whether to close the socket when the confirmation wasn’t received. +</p> +</dd> +<dt class="hdlist1"> +sndbuf +</dt> +<dd> +<p> + Minimum size of the socket’s send buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +tos +</dt> +<dd> +<p> + Value for the IP_TOS IP level option. Use with caution. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific +options by specifying the protocol level, the option number and +the actual option value specified as a binary. This option is not +portable. Use with caution.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_transport/index.html b/docs/en/ranch/1.3/manual/ranch_transport/index.html index aa57afd8..8840daad 100644 --- a/docs/en/ranch/1.3/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.3/manual/ranch_transport/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_transport(3)</title> @@ -67,494 +67,494 @@ <h1 class="lined-header"><span>ranch_transport(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used
-by Ranch transports.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3>
-<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div>
-<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-LSocket = CSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Accept timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div>
-<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket
-after accepting the connection. This is most useful when the
-transport is not raw TCP, like with SSL for example.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Ack timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div>
-<div class="paragraph"><p>This function will be called by connection processes
-before performing any socket operation. It allows
-transports that require extra initialization to perform
-their task and make the socket ready to use.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Close the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-Pid = pid()
-</dt>
-<dd>
-<p>
-Pid of the new owner of the socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change the controlling process for the given socket.</p></div>
-<div class="paragraph"><p>The controlling process is the process that is allowed to
-perform operations on the socket, and that will receive
-messages from the socket when active mode is used. When
-the controlling process dies, the socket is closed.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-LSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Listen for connections on the given port.</p></div>
-<div class="paragraph"><p>The port is given as part of the transport options under
-the key <code>port</code>. Any other option is transport dependent.</p></div>
-<div class="paragraph"><p>The socket returned by this call can then be used to
-accept connections. It is not possible to send or receive
-data from the listening socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-OK = Closed = Error = atom()
-</dt>
-<dd>
-<p>
-Tuple names.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_name_8594_name">name() → Name</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name = atom()
-</dt>
-<dd>
-<p>
-Transport module name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the name of the transport.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the remote endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the remote endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Length = non_neg_integer()
-</dt>
-<dd>
-<p>
-Requested length.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Receive timeout.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata() | any()
-</dt>
-<dd>
-<p>
-Data received.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div>
-<div class="paragraph"><p>Trying to receive data from a socket that is in active mode
-will return an error.</p></div>
-<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div>
-<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>,
-this is highly discouraged as this could cause your process
-to get stuck waiting for data that will never come. This may
-happen when a socket becomes half-open due to a crash of the
-remote endpoint. Wi-Fi going down is another common culprit
-of this issue.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata()
-</dt>
-<dd>
-<p>
-Data to be sent.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data to the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>The file may be sent full or in parts, and may be specified
-by its filename or by an already open file descriptor.</p></div>
-<div class="paragraph"><p>Transports that manipulate TCP directly may use the
-<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile
-syscall where applicable (on Linux, for example). Other
-transports can use the <code>sendfile/6</code> function exported from
-this module.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-SockOpts = any()
-</dt>
-<dd>
-<p>
-Socket options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change options for the given socket.</p></div>
-<div class="paragraph"><p>This is mainly useful for switching to active or passive mode
-or to set protocol-specific options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-How = read | write | read_write
-</dt>
-<dd>
-<p>
-Which side(s) of the socket to close.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the local endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the local endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code>
-and may be used when transports are not manipulating TCP
-directly.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used +by Ranch transports.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3> +<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div> +<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +LSocket = CSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Accept timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div> +<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket +after accepting the connection. This is most useful when the +transport is not raw TCP, like with SSL for example.</p></div> +</div> +<div class="sect2"> +<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Ack timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div> +<div class="paragraph"><p>This function will be called by connection processes +before performing any socket operation. It allows +transports that require extra initialization to perform +their task and make the socket ready to use.</p></div> +</div> +<div class="sect2"> +<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Close the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +Pid = pid() +</dt> +<dd> +<p> +Pid of the new owner of the socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change the controlling process for the given socket.</p></div> +<div class="paragraph"><p>The controlling process is the process that is allowed to +perform operations on the socket, and that will receive +messages from the socket when active mode is used. When +the controlling process dies, the socket is closed.</p></div> +</div> +<div class="sect2"> +<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +LSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Listen for connections on the given port.</p></div> +<div class="paragraph"><p>The port is given as part of the transport options under +the key <code>port</code>. Any other option is transport dependent.</p></div> +<div class="paragraph"><p>The socket returned by this call can then be used to +accept connections. It is not possible to send or receive +data from the listening socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +OK = Closed = Error = atom() +</dt> +<dd> +<p> +Tuple names. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div> +</div> +<div class="sect2"> +<h3 id="_name_8594_name">name() → Name</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name = atom() +</dt> +<dd> +<p> +Transport module name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the name of the transport.</p></div> +</div> +<div class="sect2"> +<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the remote endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the remote endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div> +</div> +<div class="sect2"> +<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Length = non_neg_integer() +</dt> +<dd> +<p> +Requested length. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Receive timeout. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() | any() +</dt> +<dd> +<p> +Data received. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div> +<div class="paragraph"><p>Trying to receive data from a socket that is in active mode +will return an error.</p></div> +<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div> +<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>, +this is highly discouraged as this could cause your process +to get stuck waiting for data that will never come. This may +happen when a socket becomes half-open due to a crash of the +remote endpoint. Wi-Fi going down is another common culprit +of this issue.</p></div> +</div> +<div class="sect2"> +<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() +</dt> +<dd> +<p> +Data to be sent. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data to the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>The file may be sent full or in parts, and may be specified +by its filename or by an already open file descriptor.</p></div> +<div class="paragraph"><p>Transports that manipulate TCP directly may use the +<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile +syscall where applicable (on Linux, for example). Other +transports can use the <code>sendfile/6</code> function exported from +this module.</p></div> +</div> +<div class="sect2"> +<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +SockOpts = any() +</dt> +<dd> +<p> +Socket options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change options for the given socket.</p></div> +<div class="paragraph"><p>This is mainly useful for switching to active or passive mode +or to set protocol-specific options.</p></div> +</div> +<div class="sect2"> +<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +How = read | write | read_write +</dt> +<dd> +<p> +Which side(s) of the socket to close. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div> +</div> +<div class="sect2"> +<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the local endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the local endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code> +and may be used when transports are not manipulating TCP +directly.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/index.html b/docs/en/ranch/index.html index d87c4243..0194031a 100644 --- a/docs/en/ranch/index.html +++ b/docs/en/ranch/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file |
