diff options
Diffstat (limited to 'docs/en/cowboy/2.2/guide')
30 files changed, 196 insertions, 136 deletions
diff --git a/docs/en/cowboy/2.2/guide/constraints/index.html b/docs/en/cowboy/2.2/guide/constraints/index.html index 7405b833..7ab31189 100644 --- a/docs/en/cowboy/2.2/guide/constraints/index.html +++ b/docs/en/cowboy/2.2/guide/constraints/index.html @@ -71,7 +71,7 @@ <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> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -85,7 +85,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <p>When there's only one constraint, it can be provided directly without wrapping it into a list:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -107,7 +107,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_custom_constraints">Custom constraints</h2> <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> <p>Cowboy currently defines three operations. The operation used for validating and converting user input is the <code>forward</code> operation.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -120,7 +120,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <p>The value must be returned even if it is not converted by the constraint.</p> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -132,7 +132,7 @@ http://www.gnu.org/software/src-highlite --> <b><font color="#0000FF">end</font></b>;</tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -198,6 +198,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/cookies/index.html b/docs/en/cowboy/2.2/guide/cookies/index.html index 5c682860..96012abf 100644 --- a/docs/en/cowboy/2.2/guide/cookies/index.html +++ b/docs/en/cowboy/2.2/guide/cookies/index.html @@ -71,7 +71,7 @@ <p>Cookies may be sent repeatedly. This is often useful to update the expiration time and avoid losing a cookie.</p> <h2 id="_setting_cookies">Setting cookies</h2> <p>By default cookies are defined for the duration of the session:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:set_resp_cookie</font></b>(<font color="#990000"><<</font><font color="#FF0000">"sessionid"</font><font color="#990000">>></font>, <font color="#009900">SessionID</font>, <font color="#009900">Req0</font>)<font color="#990000">.</font></tt></pre> </div></div> <p>They can also be set for a duration in seconds:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -88,7 +88,7 @@ http://www.gnu.org/software/src-highlite --> #{<font color="#0000FF">max_age</font> <font color="#990000">=></font> <font color="#993399">3600</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>To delete cookies, set <code>max_age</code> to 0:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -97,7 +97,7 @@ http://www.gnu.org/software/src-highlite --> #{<font color="#0000FF">max_age</font> <font color="#990000">=></font> <font color="#993399">0</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>To restrict cookies to a specific domain and path, the options of the same name can be used:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <p>To restrict cookies to secure channels (typically resources available over HTTPS):</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -115,7 +115,7 @@ http://www.gnu.org/software/src-highlite --> #{<font color="#0000FF">secure</font> <font color="#990000">=></font> <font color="#000080">true</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>To prevent client-side scripts from accessing a cookie:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -128,7 +128,7 @@ http://www.gnu.org/software/src-highlite --> <p>The client only ever sends back the cookie name and value. All other options that can be set are never sent back.</p> <p>Cowboy provides two functions for reading cookies. Both involve parsing the cookie header(s) and so should not be called repeatedly.</p> <p>You can get all cookies as a key/value list:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -136,14 +136,14 @@ http://www.gnu.org/software/src-highlite --> {<font color="#990000">_</font>, <font color="#009900">Lang</font>} <font color="#990000">=</font> <b><font color="#000000">lists:keyfind</font></b>(<font color="#990000"><<</font><font color="#FF0000">"lang"</font><font color="#990000">>></font>, <font color="#993399">1</font>, <font color="#009900">Cookies</font>)<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>#{<font color="#FF6600">id</font> <font color="#990000">:=</font> <font color="#009900">ID</font>, <font color="#FF6600">lang</font> <font color="#990000">:=</font> <font color="#009900">Lang</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy_req:match_cookies</font></b>([<font color="#FF6600">id</font>, <font color="#FF6600">lang</font>], <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -151,7 +151,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <p>Note that if two cookies share the same name, then the map value will be a list of the two cookie values.</p> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -215,6 +215,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/erlang_web/index.html b/docs/en/cowboy/2.2/guide/erlang_web/index.html index ebb6174f..e928eecd 100644 --- a/docs/en/cowboy/2.2/guide/erlang_web/index.html +++ b/docs/en/cowboy/2.2/guide/erlang_web/index.html @@ -164,6 +164,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/flow_diagram/index.html b/docs/en/cowboy/2.2/guide/flow_diagram/index.html index 84505c22..4a5e732b 100644 --- a/docs/en/cowboy/2.2/guide/flow_diagram/index.html +++ b/docs/en/cowboy/2.2/guide/flow_diagram/index.html @@ -142,6 +142,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/getting_started/index.html b/docs/en/cowboy/2.2/guide/getting_started/index.html index 80d52c47..bc56e161 100644 --- a/docs/en/cowboy/2.2/guide/getting_started/index.html +++ b/docs/en/cowboy/2.2/guide/getting_started/index.html @@ -68,7 +68,7 @@ <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> <h2 id="_bootstrap">Bootstrap</h2> <p>First, let's create the directory for our application.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -76,21 +76,21 @@ http://www.gnu.org/software/src-highlite --> $ cd hello_erlang</tt></pre> </div></div> <p>Then we need to download Erlang.mk. Either use the following command or download it manually.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>$ wget https<font color="#990000">:</font>//erlang<font color="#990000">.</font>mk/erlang<font color="#990000">.</font>mk</tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>$ make -f erlang<font color="#990000">.</font>mk bootstrap bootstrap-rel</tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -102,7 +102,7 @@ http://www.gnu.org/software/src-highlite --> <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> <h2 id="_cowboy_setup">Cowboy setup</h2> <p>We will modify the <em>Makefile</em> to tell the build system it needs to fetch and compile Cowboy:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -120,7 +120,7 @@ include erlang.mk</tt></pre> <h2 id="_listening_for_connections">Listening for connections</h2> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -139,14 +139,14 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_handling_requests">Handling requests</h2> <p>Cowboy features different kinds of handlers, including REST and Websocket handlers. For this tutorial we will use a plain HTTP handler.</p> <p>Generate a handler from a template:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>$ make new <font color="#009900">t</font><font color="#990000">=</font>cowboy<font color="#990000">.</font>http <font color="#009900">n</font><font color="#990000">=</font>hello_handler</tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -216,6 +216,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/handlers/index.html b/docs/en/cowboy/2.2/guide/handlers/index.html index 3afcf92a..2f55cdba 100644 --- a/docs/en/cowboy/2.2/guide/handlers/index.html +++ b/docs/en/cowboy/2.2/guide/handlers/index.html @@ -67,7 +67,7 @@ <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> <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> <p>A handler that does nothing would look like this:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -76,7 +76,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <p>We need to use the Req object to reply.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -93,7 +93,7 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -102,7 +102,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <h2 id="_cleaning_up">Cleaning up</h2> <p>All handler types provide the optional <code>terminate/3</code> callback.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -169,6 +169,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/index.html b/docs/en/cowboy/2.2/guide/index.html index 8e9e8dff..0e08e239 100644 --- a/docs/en/cowboy/2.2/guide/index.html +++ b/docs/en/cowboy/2.2/guide/index.html @@ -175,6 +175,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/introduction/index.html b/docs/en/cowboy/2.2/guide/introduction/index.html index 82ac9f36..0cc465bf 100644 --- a/docs/en/cowboy/2.2/guide/introduction/index.html +++ b/docs/en/cowboy/2.2/guide/introduction/index.html @@ -152,6 +152,8 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</pre></div></div> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/listeners/index.html b/docs/en/cowboy/2.2/guide/listeners/index.html index c445ce06..999848d3 100644 --- a/docs/en/cowboy/2.2/guide/listeners/index.html +++ b/docs/en/cowboy/2.2/guide/listeners/index.html @@ -68,7 +68,7 @@ <h2 id="_clear_tcp_listener">Clear TCP listener</h2> <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> <p>The following snippet starts listening for connections on port 8080:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -90,7 +90,7 @@ http://www.gnu.org/software/src-highlite --> <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> <!-- @todo Make a complete list of restrictions.--> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -173,6 +173,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/loop_handlers/index.html b/docs/en/cowboy/2.2/guide/loop_handlers/index.html index 282581a3..ff5d3ae7 100644 --- a/docs/en/cowboy/2.2/guide/loop_handlers/index.html +++ b/docs/en/cowboy/2.2/guide/loop_handlers/index.html @@ -70,7 +70,7 @@ <h2 id="_initialization">Initialization</h2> <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> <p>This snippet enables the loop handler:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -78,7 +78,7 @@ http://www.gnu.org/software/src-highlite --> {<font color="#FF6600">cowboy_loop</font>, <font color="#009900">Req</font>, <font color="#009900">State</font>}<font color="#990000">.</font></tt></pre> </div></div> <p>This also makes the process hibernate:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -88,7 +88,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_receive_loop">Receive loop</h2> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_streaming_loop">Streaming loop</h2> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -184,6 +184,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/middlewares/index.html b/docs/en/cowboy/2.2/guide/middlewares/index.html index ee0edc31..129ac341 100644 --- a/docs/en/cowboy/2.2/guide/middlewares/index.html +++ b/docs/en/cowboy/2.2/guide/middlewares/index.html @@ -150,6 +150,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html b/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html index 1228810c..e8a2c1d9 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html @@ -232,6 +232,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html b/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html index dae82463..5639f80e 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html @@ -167,6 +167,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html b/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html index 62d00ae8..1d10126e 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html @@ -178,6 +178,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html b/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html index 18949119..02b6078a 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html @@ -132,6 +132,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/modern_web/index.html b/docs/en/cowboy/2.2/guide/modern_web/index.html index fd461288..dd71b961 100644 --- a/docs/en/cowboy/2.2/guide/modern_web/index.html +++ b/docs/en/cowboy/2.2/guide/modern_web/index.html @@ -146,6 +146,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/multipart/index.html b/docs/en/cowboy/2.2/guide/multipart/index.html index 1e38b817..816b76b3 100644 --- a/docs/en/cowboy/2.2/guide/multipart/index.html +++ b/docs/en/cowboy/2.2/guide/multipart/index.html @@ -73,7 +73,7 @@ <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> <h2 id="_checking_for_multipart_messages">Checking for multipart messages</h2> <p>The content-type header indicates the presence of a multipart message:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -85,7 +85,7 @@ http://www.gnu.org/software/src-highlite --> <p>The <code>cowboy_req:read_part/1,2</code> functions return the next part's headers, if any.</p> <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> <p>To read a multipart message you need to iterate over all its parts:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -101,7 +101,7 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <p>The following snippet will use this function and use different strategies depending on whether the part is a file:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -130,14 +130,14 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <p>To change the defaults for part headers:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req</font>, #{<b><font color="#000080">length</font></b> <font color="#990000">=></font> <font color="#993399">128000</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>And for part bodies:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -146,7 +146,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_skipping_unwanted_parts">Skipping unwanted parts</h2> <p>Part bodies do not have to be read. Cowboy will automatically skip it when you request the next part's body.</p> <p>The following snippet reads all part headers and skips all bodies:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -219,6 +219,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/req/index.html b/docs/en/cowboy/2.2/guide/req/index.html index 5f466e5b..f4974e90 100644 --- a/docs/en/cowboy/2.2/guide/req/index.html +++ b/docs/en/cowboy/2.2/guide/req/index.html @@ -69,7 +69,7 @@ <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> <p>Note that the <code>version</code> field can be used to determine whether a connection is using HTTP/2.</p> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -96,14 +96,14 @@ http://www.gnu.org/software/src-highlite --> <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> <h2 id="_request_method">Request method</h2> <p>The request method can be retrieved directly:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>#{<font color="#FF6600">method</font> <font color="#990000">:=</font> <font color="#009900">Method</font>} <font color="#990000">=</font> <font color="#009900">Req</font><font color="#990000">.</font></tt></pre> </div></div> <p>Or using a function:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -115,14 +115,14 @@ http://www.gnu.org/software/src-highlite --> <p>There is typically no need to change behavior based on the HTTP version: Cowboy already does it for you.</p> <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> <p>The HTTP version can be retrieved directly:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>#{<font color="#FF6600">version</font> <font color="#990000">:=</font> <font color="#009900">Version</font>} <font color="#990000">=</font> <font color="#009900">Req</font><font color="#990000">.</font></tt></pre> </div></div> <p>Or using a function:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -131,7 +131,7 @@ http://www.gnu.org/software/src-highlite --> <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> <h2 id="_effective_request_uri">Effective request URI</h2> <p>The scheme, host, port, path and query string components of the effective request URI can all be retrieved directly:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -144,7 +144,7 @@ http://www.gnu.org/software/src-highlite --> } <font color="#990000">=</font> <font color="#009900">Req</font><font color="#990000">.</font></tt></pre> </div></div> <p>Or using the related functions:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -158,7 +158,7 @@ http://www.gnu.org/software/src-highlite --> <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> <!-- @todo Is that tested well?--> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -166,7 +166,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">URI</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:uri</font></b>(<font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -174,7 +174,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">URI</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:uri</font></b>(<font color="#009900">Req</font>, #{<font color="#0000FF">host</font> <font color="#990000">=></font> <font color="#000080">undefined</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>The protocol relative form:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -182,14 +182,14 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">URI</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:uri</font></b>(<font color="#009900">Req</font>, #{<font color="#0000FF">scheme</font> <font color="#990000">=></font> <font color="#000080">undefined</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>The absolute URI without a query string:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">URI</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:uri</font></b>(<font color="#009900">Req</font>, #{<font color="#0000FF">qs</font> <font color="#990000">=></font> <font color="#000080">undefined</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>A different host:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -200,21 +200,21 @@ http://www.gnu.org/software/src-highlite --> <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> <p>Cowboy provides functions to retrieve one or all bindings.</p> <p>To retrieve a single value:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">Value</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:binding</font></b>(<font color="#FF6600">userid</font>, <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">Value</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:binding</font></b>(<font color="#FF6600">userid</font>, <font color="#009900">Req</font>, <font color="#993399">42</font>)<font color="#990000">.</font></tt></pre> </div></div> <p>To retrieve everything that was bound:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -223,14 +223,14 @@ http://www.gnu.org/software/src-highlite --> <p>They are returned as a map, with keys being atoms.</p> <p>The Cowboy router also allows you to capture many host or path segments at once using the <code>...</code> qualifier.</p> <p>To retrieve the segments captured from the host name:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">HostInfo</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:host_info</font></b>(<font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre> </div></div> <p>And the path segments:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -239,7 +239,7 @@ http://www.gnu.org/software/src-highlite --> <p>Cowboy will return <code>undefined</code> if <code>...</code> was not used in the route.</p> <h2 id="_query_parameters">Query parameters</h2> <p>Cowboy provides two functions to access query parameters. You can use the first to get the entire list of parameters.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -251,21 +251,21 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>#{<font color="#FF6600">id</font> <font color="#990000">:=</font> <font color="#009900">ID</font>, <font color="#FF6600">lang</font> <font color="#990000">:=</font> <font color="#009900">Lang</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy_req:match_qs</font></b>([<font color="#FF6600">id</font>, <font color="#FF6600">lang</font>], <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">QsMap</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:match_qs</font></b>([{<font color="#FF6600">id</font>, <font color="#FF6600">int</font>}, {<font color="#FF6600">lang</font>, <font color="#FF6600">nonempty</font>}], <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -276,7 +276,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_headers">Headers</h2> <p>Header values can be retrieved either as a binary string or parsed into a more meaningful representation.</p> <p>The get the raw value:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -284,21 +284,21 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <p>When the header is missing from the request, <code>undefined</code> will be returned. A different default can be provided:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">HeaderVal</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:header</font></b>(<font color="#990000"><<</font><font color="#FF0000">"content-type"</font><font color="#990000">>></font>, <font color="#009900">Req</font>, <font color="#990000"><<</font><font color="#FF0000">"text/plain"</font><font color="#990000">>></font>)<font color="#990000">.</font></tt></pre> </div></div> <p>All headers can be retrieved at once, either directly:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>#{<font color="#FF6600">headers</font> <font color="#990000">:=</font> <font color="#009900">AllHeaders</font>} <font color="#990000">=</font> <font color="#009900">Req</font><font color="#990000">.</font></tt></pre> </div></div> <p>Or using a function:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -306,7 +306,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <p>Cowboy provides equivalent functions to parse individual headers. There is no function to parse all headers at once.</p> <p>To parse a specific header:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -314,7 +314,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -324,14 +324,14 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_peer">Peer</h2> <p>The peer address and port number for the connection can be retrieved either directly or using a function.</p> <p>To retrieve the peer directly:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>#{<font color="#FF6600">peer</font> <font color="#990000">:=</font> {<font color="#009900">IP</font>, <font color="#009900">Port</font>}} <font color="#990000">=</font> <font color="#009900">Req</font><font color="#990000">.</font></tt></pre> </div></div> <p>And using a function:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -395,6 +395,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/req_body/index.html b/docs/en/cowboy/2.2/guide/req_body/index.html index d6677edb..22bb3fb5 100644 --- a/docs/en/cowboy/2.2/guide/req_body/index.html +++ b/docs/en/cowboy/2.2/guide/req_body/index.html @@ -69,7 +69,7 @@ <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> <h2 id="_request_body_presence">Request body presence</h2> <p>Not all requests come with a body. You can check for the presence of a request body with this function:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite --> <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> <h2 id="_request_body_length">Request body length</h2> <p>You can obtain the length of the body:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -89,7 +89,7 @@ http://www.gnu.org/software/src-highlite --> <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> <h2 id="_reading_the_body">Reading the body</h2> <p>You can read the entire body with one function call:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -98,7 +98,7 @@ http://www.gnu.org/software/src-highlite --> <p>Cowboy returns an <code>ok</code> tuple when the body has been read fully.</p> <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> <p>These values can be customized. For example, to read only up to 1MB for up to 5 seconds:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite --> #{<b><font color="#000080">length</font></b> <font color="#990000">=></font> <font color="#993399">1000000</font>, <font color="#0000FF">period</font> <font color="#990000">=></font> <font color="#993399">5000</font>})<font color="#990000">.</font></tt></pre> </div></div> <p>You may also disable the length limit:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -116,7 +116,7 @@ http://www.gnu.org/software/src-highlite --> <p>These two options can effectively be used to control the rate of transmission of the request body.</p> <h2 id="_streaming_the_body">Streaming the body</h2> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -133,7 +133,7 @@ http://www.gnu.org/software/src-highlite --> <p>The <code>length</code> and <code>period</code> options can also be used. They need to be passed for every call.</p> <h2 id="_reading_a_form_urlencoded_body">Reading a form urlencoded body</h2> <p>Cowboy provides a convenient function for reading and parsing bodies sent as application/x-www-form-urlencoded.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -141,7 +141,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <p>This function returns a list of key/values, exactly like the function <code>cowboy_req:parse_qs/1</code>.</p> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -205,6 +205,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/resource_design/index.html b/docs/en/cowboy/2.2/guide/resource_design/index.html index 01447fb5..b93da6e0 100644 --- a/docs/en/cowboy/2.2/guide/resource_design/index.html +++ b/docs/en/cowboy/2.2/guide/resource_design/index.html @@ -178,6 +178,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/resp/index.html b/docs/en/cowboy/2.2/guide/resp/index.html index 2ad38c40..b25fe3a1 100644 --- a/docs/en/cowboy/2.2/guide/resp/index.html +++ b/docs/en/cowboy/2.2/guide/resp/index.html @@ -69,14 +69,14 @@ <h2 id="_reply">Reply</h2> <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> <p>When you need to set only the status code, use <code>cowboy_req:reply/2</code>:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:reply</font></b>(<font color="#993399">200</font>, <font color="#009900">Req0</font>)<font color="#990000">.</font></tt></pre> </div></div> <p>When you need to set response headers at the same time, use <code>cowboy_req:reply/3</code>:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -86,7 +86,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <p>Note that the header name must always be a lowercase binary.</p> <p>When you also need to set the response body, use <code>cowboy_req:reply/4</code>:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -96,7 +96,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -112,7 +112,7 @@ http://www.gnu.org/software/src-highlite --> <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> <!-- @todo For HTTP/1.1 Cowboy should probably not use chunked transfer-encoding if the content-length is set.--> <p>When you need to set only the status code, use <code>cowboy_req:stream_reply/2</code>:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -124,7 +124,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -139,7 +139,7 @@ http://www.gnu.org/software/src-highlite --> <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> <p>Cowboy also provides a function to send response trailers. Response trailers are semantically equivalent to the headers you send in the response, only they are sent at the end. This is especially useful to attach information to the response that could not be generated until the response body was fully generated.</p> <p>Trailer fields must be listed in the trailer header. Any field not listed might be dropped by the client or an intermediary.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -160,7 +160,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_preset_response_headers">Preset response headers</h2> <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> <p>To set response headers:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -169,7 +169,7 @@ http://www.gnu.org/software/src-highlite --> <p>Header names must be a lowercase binary.</p> <p>Do not use this function for setting cookies. Refer to the <a href="../cookies">Cookies</a> chapter for more information.</p> <p>To check if a response header has already been set:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -177,7 +177,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <p>It returns <code>true</code> if the header was set, <code>false</code> otherwise.</p> <p>To delete a response header that was set previously:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -202,7 +202,7 @@ http://www.gnu.org/software/src-highlite --> <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> <p>Similarly, preset headers will always override required headers.</p> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -213,7 +213,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_preset_response_body">Preset response body</h2> <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> <p>To set the response body:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -222,7 +222,7 @@ http://www.gnu.org/software/src-highlite --> <!-- @todo Yeah we probably should add that function that--> <!-- also sets the content-type at the same time...--> <p>To check if a response body has already been set:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -235,7 +235,7 @@ http://www.gnu.org/software/src-highlite --> <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> <h2 id="_sending_files">Sending files</h2> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -244,7 +244,7 @@ http://www.gnu.org/software/src-highlite --> <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> <p>The length is required even for sending the entire file. Cowboy sends it in the content-length header.</p> <p>To send a file while replying:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -265,7 +265,7 @@ http://www.gnu.org/software/src-highlite --> <p>Cowboy allows you to send informational responses.</p> <p>Informational responses are responses that have a status code between 100 and 199. Any number can be sent before the proper response. Sending an informational response does not change the behavior of the proper response, and clients are expected to ignore any informational response they do not understand.</p> <p>The following snippet sends a 103 informational response with some headers that are expected to be in the final response.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -281,7 +281,7 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <p>The following snippet pushes a CSS file that is linked to in the response:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -295,7 +295,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#FF0000">"<body><p>Welcome to Erlang!</p></body></html>"</font>], <font color="#009900">Req0</font>)<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -362,6 +362,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html b/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html index 0496db5f..e8ddb8a1 100644 --- a/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html +++ b/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html @@ -176,6 +176,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/rest_handlers/index.html b/docs/en/cowboy/2.2/guide/rest_handlers/index.html index 4c83fc1c..c3e3dbab 100644 --- a/docs/en/cowboy/2.2/guide/rest_handlers/index.html +++ b/docs/en/cowboy/2.2/guide/rest_handlers/index.html @@ -66,7 +66,7 @@ <p>The REST handler is the recommended way to handle HTTP requests.</p> <h2 id="_initialization">Initialization</h2> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -274,6 +274,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/rest_principles/index.html b/docs/en/cowboy/2.2/guide/rest_principles/index.html index 34ec3366..4f769edf 100644 --- a/docs/en/cowboy/2.2/guide/rest_principles/index.html +++ b/docs/en/cowboy/2.2/guide/rest_principles/index.html @@ -150,6 +150,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/routing/index.html b/docs/en/cowboy/2.2/guide/routing/index.html index b0b06a50..18229ec4 100644 --- a/docs/en/cowboy/2.2/guide/routing/index.html +++ b/docs/en/cowboy/2.2/guide/routing/index.html @@ -68,14 +68,14 @@ <p>Routes need to be compiled before they can be used by Cowboy. The result of the compilation is the dispatch rules.</p> <h2 id="_syntax">Syntax</h2> <p>The general structure for the routes is defined as follow.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">Routes</font> <font color="#990000">=</font> [<font color="#009900">Host1</font>, <font color="#009900">Host2</font>, <font color="#990000">...</font> <font color="#009900">HostN</font>]<font color="#990000">.</font></tt></pre> </div></div> <p>Each host contains matching rules for the host along with optional constraints, and a list of routes for the path component.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -83,14 +83,14 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">Host2</font> <font color="#990000">=</font> {<font color="#009900">HostMatch</font>, <font color="#009900">Constraints</font>, <font color="#009900">PathsList</font>}<font color="#990000">.</font></tt></pre> </div></div> <p>The list of routes for the path component is defined similar to the list of hosts.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">PathsList</font> <font color="#990000">=</font> [<font color="#009900">Path1</font>, <font color="#009900">Path2</font>, <font color="#990000">...</font> <font color="#009900">PathN</font>]<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -102,7 +102,7 @@ http://www.gnu.org/software/src-highlite --> <p>The match syntax is used to associate host names and paths with their respective handlers.</p> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -112,7 +112,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">HostMatch1</font> <font color="#990000">=</font> <font color="#FF0000">"cowboy.example.org"</font><font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -120,7 +120,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">PathMatch3</font> <font color="#990000">=</font> <font color="#FF0000">"/path/to/resource/"</font><font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -130,7 +130,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -139,14 +139,14 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">HostMatch</font> <font color="#990000">=</font> <font color="#FF0000">"ninenines.:_"</font><font color="#990000">.</font></tt></pre> </div></div> <p>Similarly, it is possible to have optional segments. Anything between brackets is optional.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -154,14 +154,14 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">HostMatch</font> <font color="#990000">=</font> <font color="#FF0000">"[www.]ninenines.eu"</font><font color="#990000">.</font></tt></pre> </div></div> <p>You can also have imbricated optional segments.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">PathMatch</font> <font color="#990000">=</font> <font color="#FF0000">"/hats/[page/[:number]]"</font><font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -169,21 +169,21 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">HostMatch</font> <font color="#990000">=</font> <font color="#FF0000">"[...]ninenines.eu"</font><font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">PathMatch</font> <font color="#990000">=</font> <font color="#FF0000">"/hats/:name/:name"</font><font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><font color="#009900">PathMatch</font> <font color="#990000">=</font> <font color="#FF0000">"/hats/:name/[:name]"</font><font color="#990000">.</font></tt></pre> </div></div> <p>If a binding is defined in both the host and path, then they must also share the same value.</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -191,7 +191,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">HostMatch</font> <font color="#990000">=</font> <font color="#FF0000">":user.github.com"</font><font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -199,7 +199,7 @@ http://www.gnu.org/software/src-highlite --> <font color="#009900">HostMatch</font> <font color="#990000">=</font> <font color="#FF6600">'_'</font><font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -212,7 +212,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_compilation">Compilation</h2> <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> <p>To compile routes, just call the appropriate function:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -228,7 +228,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <h2 id="_live_update">Live update</h2> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -293,6 +293,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/specs/index.html b/docs/en/cowboy/2.2/guide/specs/index.html index 8fedf01b..9bd4a261 100644 --- a/docs/en/cowboy/2.2/guide/specs/index.html +++ b/docs/en/cowboy/2.2/guide/specs/index.html @@ -447,6 +447,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/static_files/index.html b/docs/en/cowboy/2.2/guide/static_files/index.html index c4c80cd7..e6ef0b75 100644 --- a/docs/en/cowboy/2.2/guide/static_files/index.html +++ b/docs/en/cowboy/2.2/guide/static_files/index.html @@ -68,14 +68,14 @@ <h2 id="_serve_one_file">Serve one file</h2> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>{<font color="#FF0000">"/"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_file</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/index.html"</font>}}</tt></pre> </div></div> <p>You can also specify the absolute path to a file, or the path to the file relative to the current directory:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -85,14 +85,14 @@ http://www.gnu.org/software/src-highlite --> <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> <p>You can specify the directory relative to an application's private directory.</p> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_dir</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/assets"</font>}}</tt></pre> </div></div> <p>You can also specify the absolute path to the directory or set it relative to the current directory:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -103,7 +103,7 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -112,7 +112,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <p>To use the function that will detect almost any mimetype, the following configuration will do:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -120,7 +120,7 @@ http://www.gnu.org/software/src-highlite --> [{<font color="#FF6600">mimetypes</font>, <font color="#FF6600">cow_mimetypes</font>, <font color="#FF6600">all</font>}]}}</tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -130,7 +130,7 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -140,7 +140,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_generate_an_etag">Generate an etag</h2> <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> <p>You can however change the way the etag is calculated:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -149,7 +149,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <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> <p>You can also completely disable etag handling:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -213,6 +213,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/streams/index.html b/docs/en/cowboy/2.2/guide/streams/index.html index 652210af..d1d96c34 100644 --- a/docs/en/cowboy/2.2/guide/streams/index.html +++ b/docs/en/cowboy/2.2/guide/streams/index.html @@ -135,6 +135,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/ws_handlers/index.html b/docs/en/cowboy/2.2/guide/ws_handlers/index.html index 6a40521e..f60eedce 100644 --- a/docs/en/cowboy/2.2/guide/ws_handlers/index.html +++ b/docs/en/cowboy/2.2/guide/ws_handlers/index.html @@ -66,7 +66,7 @@ <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> <h2 id="_upgrade">Upgrade</h2> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite --> <p>If the server only understands MQTT it can return:</p> <div class="listingblock"><div class="content"><pre>sec-websocket-protocol: mqtt</pre></div></div> <p>This selection must be done in <code>init/2</code>. An example usage could be:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -115,7 +115,7 @@ http://www.gnu.org/software/src-highlite --> {<font color="#FF6600">ok</font>, <font color="#009900">State</font>}<font color="#990000">.</font></tt></pre> </div></div> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -126,7 +126,7 @@ http://www.gnu.org/software/src-highlite --> <p>Cowboy will call <code>websocket_handle/2</code> whenever a text, binary, ping or pong frame arrives from the client.</p> <p>The handler can handle or ignore the frames. It can also send frames back to the client or stop the connection.</p> <p>The following snippet echoes back any text frame received and ignores all others:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -140,7 +140,7 @@ http://www.gnu.org/software/src-highlite --> <p>Cowboy will call <code>websocket_info/2</code> whenever an Erlang message arrives.</p> <p>The handler can handle or ignore the messages. It can also send frames to the client or stop the connection.</p> <p>The following snippet forwards log messages to the client and ignores all others:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -155,7 +155,7 @@ http://www.gnu.org/software/src-highlite --> <!-- functionality easily.--> <p>All <code>websocket_</code> callbacks share return values. They may send zero, one or many frames to the client.</p> <p>To send nothing, just return an ok tuple:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -163,7 +163,7 @@ http://www.gnu.org/software/src-highlite --> {<font color="#FF6600">ok</font>, <font color="#009900">State</font>}<font color="#990000">.</font></tt></pre> </div></div> <p>To send one frame, return a reply tuple with the frame to send:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -172,7 +172,7 @@ http://www.gnu.org/software/src-highlite --> </div></div> <p>You can send frames of any type: text, binary, ping, pong or close frames.</p> <p>To send many frames at once, return a reply tuple with the list of frames to send:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -189,7 +189,7 @@ http://www.gnu.org/software/src-highlite --> <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> <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> <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 class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -201,7 +201,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_saving_memory">Saving memory</h2> <p>The Websocket connection process can be set to hibernate after the callback returns.</p> <p>Simply add an <code>hibernate</code> field to the ok or reply tuples:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -218,7 +218,7 @@ http://www.gnu.org/software/src-highlite --> <h2 id="_closing_the_connection">Closing the connection</h2> <p>The connection can be closed at any time, either by telling Cowboy to stop it or by sending a close frame.</p> <p>To tell Cowboy to close the connection, use a stop tuple:</p> -<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> @@ -283,6 +283,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> diff --git a/docs/en/cowboy/2.2/guide/ws_protocol/index.html b/docs/en/cowboy/2.2/guide/ws_protocol/index.html index 3f77bc47..ae657e6e 100644 --- a/docs/en/cowboy/2.2/guide/ws_protocol/index.html +++ b/docs/en/cowboy/2.2/guide/ws_protocol/index.html @@ -134,6 +134,8 @@ + <li><a href="/docs/en/cowboy/2.7/guide">2.7</a></li> + <li><a href="/docs/en/cowboy/2.6/guide">2.6</a></li> <li><a href="/docs/en/cowboy/2.5/guide">2.5</a></li> |