diff options
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_app/index.html | 11 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_handler/index.html | 8 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_loop/index.html | 181 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_middleware/index.html | 115 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_websocket/index.html | 1 | ||||
| -rw-r--r-- | docs/index.xml | 11 |
6 files changed, 155 insertions, 172 deletions
diff --git a/docs/en/cowboy/2.0/manual/cowboy_app/index.html b/docs/en/cowboy/2.0/manual/cowboy_app/index.html index eeaa33e3..6eb67fce 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_app/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_app/index.html @@ -152,16 +152,7 @@ related standards, like Websocket or Server-Sent Events.</p></div> <li>
<p>
<a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_sub_protocol">cowboy_sub_protocol(3)</a> - Sub protocols
+
</p>
</li>
<li>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html index 604c8f26..17164fc5 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html @@ -102,10 +102,10 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
+<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
+<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
+<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
+ | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
<div class="paragraph"><p>These two callbacks are common to all handlers.</p></div>
<div class="paragraph"><p>Plain HTTP handlers do all their work in the <code>init/2</code>
callback. Returning <code>ok</code> terminates the handler. If no
diff --git a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html index e5d69511..5882a278 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html @@ -72,51 +72,79 @@ <div class="sect1">
<h2 id="_name">Name</h2>
<div class="sectionbody">
-<div class="paragraph"><p>cowboy_loop - loop handlers</p></div>
+<div class="paragraph"><p>cowboy_loop - Loop handlers</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">Description</h2>
<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_loop</code> module implements a handler interface for
-long running HTTP connections. It is the recommended interface
-for long polling and server-sent events, amongst others.</p></div>
-<div class="paragraph"><p>This module is a sub protocol that defines three callbacks to
-be implemented by handlers. The <code>init/2</code> and <code>terminate/3</code>
-callbacks are common to all handler types and are documented
-in the manual for the <a href="cowboy_handler.asciidoc">cowboy_handler</a> module.</p></div>
-<div class="paragraph"><p>The <code>info/3</code> callback is specific to loop handlers and will be
-called as many times as necessary until a reply is sent.</p></div>
-<div class="paragraph"><p>It is highly recommended to return a timeout value from the
-<code>init/2</code> callback to ensure that the process is terminated
-when no data has been received during that timespan. The
-default timeout is <code>infinity</code>, which should only be used if
-you have alternate means of ending inactive connections.</p></div>
+<div class="paragraph"><p>The module <code>cowboy_loop</code> defines a callback interface for
+long running HTTP connections.</p></div>
+<div class="paragraph"><p>You should switch to this behavior for long polling,
+server-sent events and similar long-running requests.</p></div>
+<div class="paragraph"><p>There are generally two usage patterns:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Loop until receiving a specific message, then send
+ a response and stop execution (for example long polling);
+</p>
+</li>
+<li>
+<p>
+Or initiate a response in <code>init/2</code> and stream the
+ body in <code>info/3</code> as necessary (for example server-sent events).
+</p>
+</li>
+</ul></div>
</div>
</div>
<div class="sect1">
-<h2 id="_terminate_reasons">Terminate reasons</h2>
+<h2 id="_callbacks">Callbacks</h2>
<div class="sectionbody">
-<div class="paragraph"><p>The following values may be received as the terminate reason
-in the optional <code>terminate/3</code> callback.</p></div>
+<div class="paragraph"><p>Loop handlers implement the following interface:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
+ <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
+ | {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
+ | {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
+ | {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), <span style="color: #FF6600">hibernate</span>}
+
+<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
+ <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
+ | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
+ | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
+
+<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
+
+<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
+<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
+<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
+<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="color: #FF6600">stop</span> | <span style="color: #FF6600">timeout</span>
+ | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
+<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch
+to the loop behavior, it must return <code>cowboy_loop</code> as the
+first element of the tuple.</p></div>
+<div class="paragraph"><p>The <code>info/3</code> callback will be called for every Erlang message
+received. It may choose to continue the receive loop or stop
+it.</p></div>
+<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
+with the reason for the termination of the handler.
+Cowboy will terminate the process right after this. There
+is no need to perform any cleanup in this callback.</p></div>
+<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-normal
-</dt>
-<dd>
-<p>
- The connection was closed normally before switching to the
- loop sub protocol. This typically happens if an <code>ok</code> tuple is
- returned from the <code>init/2</code> callback.
-</p>
-</dd>
-<dt class="hdlist1">
stop
</dt>
<dd>
<p>
- The handler requested to close the connection by returning
- a <code>stop</code> tuple.
+ The handler requested to close the connection by returning
+ a <code>stop</code> tuple.
</p>
</dd>
<dt class="hdlist1">
@@ -124,9 +152,9 @@ timeout </dt>
<dd>
<p>
- The connection has been closed due to inactivity. The timeout
- value can be configured from <code>init/2</code>. The response sent when
- this happens is a <code>204 No Content</code>.
+ The connection has been closed due to inactivity. The timeout
+ value can be configured from <code>init/2</code>. The response sent when
+ this happens is a <code>204 No Content</code>.
</p>
</dd>
<dt class="hdlist1">
@@ -134,87 +162,38 @@ timeout </dt>
<dd>
<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, overflow}
-</dt>
-<dd>
-<p>
- The connection is being closed and the process terminated
- because the buffer Cowboy uses to keep data sent by the
- client has reached its maximum. The buffer size can be
- configured through the environment value <code>loop_max_buffer</code>
- and defaults to 5000 bytes.
- <br />
- If the long running request comes with a body it is recommended
- to process this body before switching to the loop sub protocol.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, closed}
-</dt>
-<dd>
-<p>
- The socket has been closed brutally without a close frame being
- received first.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, Reason}
-</dt>
-<dd>
-<p>
- A socket error ocurred.
+ A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
+ used to obtain more information about the crash. The function
+ <code>erlang:get_stacktrace/0</code> can also be called to obtain the
+ stacktrace of the process when the crash occurred.
</p>
</dd>
</dl></div>
</div>
</div>
<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
+<h2 id="_changelog">Changelog</h2>
<div class="sectionbody">
-<div class="sect2">
-<h3 id="_info_info_req_state_8594_ok_req_state_ok_req_state_hibernate_stop_req_state">info(Info, Req, State) → {ok, Req, State} | {ok, Req, State, hibernate} | {stop, Req, State}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Info = any()
-</dt>
-<dd>
-<p>
-Message received by the process.
-</p>
-</dd>
-<dt class="hdlist1">
-Req = cowboy_req:req()
-</dt>
-<dd>
+<div class="ulist"><ul>
+<li>
<p>
-The Req object.
+<strong>2.0</strong>: Cowboy temporarily no longer checks the socket for data with HTTP/1.1.
</p>
-</dd>
-<dt class="hdlist1">
-State = any()
-</dt>
-<dd>
+</li>
+<li>
<p>
-Handler state.
+<strong>1.0</strong>: Behavior introduced.
</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Handle the Erlang message received.</p></div>
-<div class="paragraph"><p>This function will be called every time an Erlang message
-has been received. The message can be any Erlang term.</p></div>
-<div class="paragraph"><p>The <code>stop</code> return value can be used to stop the receive loop,
-typically because a response has been sent.</p></div>
-<div class="paragraph"><p>The <code>hibernate</code> option will hibernate the process until
-it receives another message.</p></div>
+</li>
+</ul></div>
</div>
</div>
+<div class="sect1">
+<h2 id="_see_also">See also</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><a href="../cowboy_app">cowboy(7)</a>,
+<a href="../cowboy_handler">cowboy_handler(3)</a></p></div>
+</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html index ebc7ba07..2a78e5b6 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html @@ -72,89 +72,110 @@ <div class="sect1">
<h2 id="_name">Name</h2>
<div class="sectionbody">
-<div class="paragraph"><p>cowboy_middleware - behaviour for middlewares</p></div>
+<div class="paragraph"><p>cowboy_middleware - Middlewares</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">Description</h2>
<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_middleware</code> behaviour defines the interface used
-by Cowboy middleware modules.</p></div>
+<div class="paragraph"><p>The module <code>cowboy_middleware</code> defines a callback interface for
+Cowboy middlewares.</p></div>
<div class="paragraph"><p>Middlewares process the request sequentially in the order they
are configured.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_env_atom_any">env() = [{atom(), any()}]</h3>
-<div class="paragraph"><p>The environment variable.</p></div>
-<div class="paragraph"><p>One is created for every request. It is passed to each
-middleware module executed and subsequently returned,
-optionally with its contents modified.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
<h2 id="_callbacks">Callbacks</h2>
<div class="sectionbody">
-<div class="sect2">
-<h3 id="_execute_req_env_8594_ok_req_env_suspend_module_function_args_stop_req">execute(Req, Env) → {ok, Req, Env} | {suspend, Module, Function, Args} | {stop, Req}</h3>
+<div class="paragraph"><p>Middlewares implement the following interface:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>)
+ <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>}
+ | {<span style="color: #FF6600">suspend</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), [<span style="font-weight: bold"><span style="color: #000000">any</span></span>()]}
+ | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>}
+
+<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
+<span style="color: #009900">Env</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>()</tt></pre></div></div>
+<div class="paragraph"><p>The <code>execute/2</code> is the only callback that needs to be
+implemented. It must execute the middleware and return
+with instructions for Cowboy.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-Req = cowboy_req:req()
+ok
</dt>
<dd>
<p>
-The Req object.
+Cowboy should continue processing the request using the
+returned Req object and environment.
</p>
</dd>
<dt class="hdlist1">
-Env = env()
+suspend
</dt>
<dd>
<p>
-The request environment.
+Cowboy will hibernate the process. When resuming, Cowboy
+will apply the returned module, function and arguments.
</p>
</dd>
<dt class="hdlist1">
-Module = module()
+stop
</dt>
<dd>
<p>
-MFA to call when resuming the process.
+Cowboy will stop middleware execution. No other middleware
+will be executed. This effectively ends the processing of
+the request.
</p>
</dd>
-<dt class="hdlist1">
-Function = atom()
-</dt>
-<dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_types">Types</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_env">env()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">env</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
+<div class="paragraph"><p>Middleware environment.</p></div>
+<div class="paragraph"><p>A new environment is created for every request. The initial
+environment contained the user configured environment values
+(like <code>dispatch</code> for example) plus the <code>listener</code> value which
+contains the name of the listener for this connection.</p></div>
+<div class="paragraph"><p>Middlewares may modify the environment as necessary.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_changelog">Changelog</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
<p>
-MFA to call when resuming the process.
+<strong>2.0</strong>: The <code>env</code> type is now a map instead of a proplist.
</p>
-</dd>
-<dt class="hdlist1">
-Args = [any()]
-</dt>
-<dd>
+</li>
+<li>
<p>
-MFA to call when resuming the process.
+<strong>1.0</strong>: Behavior introduced.
</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Execute the middleware.</p></div>
-<div class="paragraph"><p>The <code>ok</code> return value indicates that everything went well
-and that Cowboy should continue processing the request. A
-response may or may not have been sent.</p></div>
-<div class="paragraph"><p>The <code>suspend</code> return value will hibernate the process until
-an Erlang message is received. Note that when resuming, any
-previous stacktrace information will be gone.</p></div>
-<div class="paragraph"><p>The <code>stop</code> return value stops Cowboy from doing any further
-processing of the request, even if there are middlewares
-that haven’t been executed yet. The connection may be left
-open to receive more requests from the client.</p></div>
+</li>
+</ul></div>
+</div>
</div>
+<div class="sect1">
+<h2 id="_see_also">See also</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><a href="../cowboy_app">cowboy(7)</a></p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html index e6cb088a..1d426ebd 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html @@ -304,6 +304,7 @@ timeout <h2 id="_see_also">See also</h2>
<div class="sectionbody">
<div class="paragraph"><p><a href="../cowboy_app">cowboy(7)</a>,
+<a href="../cowboy_handler">cowboy_handler(3)</a>,
<a href="../cowboy_http">cowboy_http(3)</a>,
<a href="../cowboy_http2">cowboy_http2(3)</a></p></div>
</div>
diff --git a/docs/index.xml b/docs/index.xml index a50f1675..994f3669 100644 --- a/docs/index.xml +++ b/docs/index.xml @@ -1582,16 +1582,7 @@ related standards, like Websocket or Server-Sent Events.</p></div> <li>
<p>
<a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_sub_protocol">cowboy_sub_protocol(3)</a> - Sub protocols
+
</p>
</li>
<li>
|