diff options
Diffstat (limited to 'docs/en/cowboy/2.0/guide/handlers/index.html')
| -rw-r--r-- | docs/en/cowboy/2.0/guide/handlers/index.html | 106 |
1 files changed, 36 insertions, 70 deletions
diff --git a/docs/en/cowboy/2.0/guide/handlers/index.html b/docs/en/cowboy/2.0/guide/handlers/index.html index 28a6c5ec..dccd2faf 100644 --- a/docs/en/cowboy/2.0/guide/handlers/index.html +++ b/docs/en/cowboy/2.0/guide/handlers/index.html @@ -62,91 +62,57 @@ <h1 class="lined-header"><span>Handlers</span></h1> -<div class="paragraph"><p>Handlers are Erlang modules that handle HTTP requests.</p></div> -<div class="sect1"> +<p>Handlers are Erlang modules that handle HTTP requests.</p> <h2 id="_plain_http_handlers">Plain HTTP handlers</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The most basic handler in Cowboy implements the mandatory -<code>init/2</code> callback, manipulates the request, optionally -sends a response and then returns.</p></div> -<div class="paragraph"><p>This callback receives the <a href="../req">Req object</a> and the initial -state defined in the <a href="../routing">router configuration</a>.</p></div> -<div class="paragraph"><p>A handler that does nothing would look like this:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<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 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Despite sending no reply, a <code>204 No Content</code> response will be -sent to the client, as Cowboy makes sure that a response is -sent for every request.</p></div> -<div class="paragraph"><p>We need to use the Req object to reply.</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">init</font></b>(<font color="#009900">Req</font>, <font color="#009900">State</font>) <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">Req</font>, <font color="#009900">State</font>}<font color="#990000">.</font></tt></pre> +</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 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> - <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:reply</span></span>(<span style="color: #993399">200</span>, #{ - <span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/plain"</span><span style="color: #990000">>></span> - }, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello World!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Cowboy will immediately send a response when <code>cowboy:reply/4</code> -is called.</p></div> -<div class="paragraph"><p>We then return a 3-tuple. <code>ok</code> means that the handler ran -successfully. We also give the modified Req back to Cowboy.</p></div> -<div class="paragraph"><p>The last value of the tuple is a state that will be used -in every subsequent callbacks to this handler. Plain HTTP -handlers only have one additional callback, the optional -and rarely used <code>terminate/3</code>.</p></div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">init</font></b>(<font color="#009900">Req0</font>, <font color="#009900">State</font>) <font color="#990000">-></font> + <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="#990000"><<</font><font color="#FF0000">"content-type"</font><font color="#990000">>></font> <font color="#990000">=></font> <font color="#990000"><<</font><font color="#FF0000">"text/plain"</font><font color="#990000">>></font> + }, <font color="#990000"><<</font><font color="#FF0000">"Hello World!"</font><font color="#990000">>></font>, <font color="#009900">Req0</font>), + {<font color="#FF6600">ok</font>, <font color="#009900">Req</font>, <font color="#009900">State</font>}<font color="#990000">.</font></tt></pre> +</div></div> +<p>Cowboy will immediately send a response when <code>cowboy:reply/4</code> is called.</p> +<p>We then return a 3-tuple. <code>ok</code> means that the handler ran successfully. We also give the modified Req back to Cowboy.</p> +<p>The last value of the tuple is a state that will be used in every subsequent callbacks to this handler. Plain HTTP handlers only have one additional callback, the optional and rarely used <code>terminate/3</code>.</p> <h2 id="_other_handlers">Other handlers</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The <code>init/2</code> callback can also be used to inform Cowboy -that this is a different kind of handler and that Cowboy -should switch to it. To do this you simply need to return -the module name of the handler type you want to switch to.</p></div> -<div class="paragraph"><p>Cowboy comes with three handler types you can switch to: -<a href="../rest_handlers">cowboy_rest</a>, <a href="#ws_handlers">cowboy_websocket</a> -and <a href="../loop_handlers">cowboy_loop</a>. In addition to those you -can define your own handler types.</p></div> -<div class="paragraph"><p>Switching is simple. Instead of returning <code>ok</code>, you simply -return the name of the handler type you want to use. The -following snippet switches to a Websocket handler:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<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 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> - {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">init</font></b>(<font color="#009900">Req</font>, <font color="#009900">State</font>) <font color="#990000">-></font> + {<font color="#FF6600">cowboy_websocket</font>, <font color="#009900">Req</font>, <font color="#009900">State</font>}<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_cleaning_up">Cleaning up</h2> -<div class="sectionbody"> -<div class="paragraph"><p>All handler types provide the optional <code>terminate/3</code> callback.</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<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 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">_Reason</span>, <span style="color: #009900">_Req</span>, <span style="color: #009900">_State</span>) <span style="color: #990000">-></span> - <span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>This callback is strictly reserved for any required cleanup. -You cannot send a response from this function. There is no -other return value.</p></div> -<div class="paragraph"><p>This callback is optional because it is rarely necessary. -Cleanup should be done in separate processes directly (by -monitoring the handler process to detect when it exits).</p></div> -<div class="paragraph"><p>Cowboy does not reuse processes for different requests. The -process will terminate soon after this call returns.</p></div> -</div> -</div> +<pre><tt><b><font color="#000000">terminate</font></b>(<font color="#009900">_Reason</font>, <font color="#009900">_Req</font>, <font color="#009900">_State</font>) <font color="#990000">-></font> + <font color="#FF6600">ok</font><font color="#990000">.</font></tt></pre> +</div></div> +<p>This callback is strictly reserved for any required cleanup. You cannot send a response from this function. There is no other return value.</p> +<p>This callback is optional because it is rarely necessary. Cleanup should be done in separate processes directly (by monitoring the handler process to detect when it exits).</p> +<p>Cowboy does not reuse processes for different requests. The process will terminate soon after this call returns.</p> + |