diff options
20 files changed, 164 insertions, 205 deletions
diff --git a/docs/en/cowboy/2.0/guide/cookies.asciidoc b/docs/en/cowboy/2.0/guide/cookies.asciidoc index 33a19404..4825031b 100644 --- a/docs/en/cowboy/2.0/guide/cookies.asciidoc +++ b/docs/en/cowboy/2.0/guide/cookies.asciidoc @@ -33,24 +33,21 @@ update the expiration time and avoid losing a cookie. === Setting cookies -// @todo So I am not particularly happy about set_resp_cookie/4 -// having Opts as a *third* argument, instead of the *last* like -// all other functions that come with an Opts argument. We will -// probably need to change this before 2.0. - By default cookies are defined for the duration of the session: [source,erlang] +---- SessionID = generate_session_id(), Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0). +---- They can also be set for a duration in seconds: [source,erlang] ---- SessionID = generate_session_id(), -Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, - #{max_age => 3600}, Req0). +Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0, + #{max_age => 3600}). ---- To delete cookies, set `max_age` to 0: @@ -58,8 +55,8 @@ To delete cookies, set `max_age` to 0: [source,erlang] ---- SessionID = generate_session_id(), -Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, - #{max_age => 0}, Req0). +Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0, + #{max_age => 0}). ---- To restrict cookies to a specific domain and path, the options @@ -67,8 +64,8 @@ of the same name can be used: [source,erlang] ---- -Req = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, - #{domain => "my.example.org", path => "/account"}, Req0). +Req = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, Req0, + #{domain => "my.example.org", path => "/account"}). ---- Cookies will be sent with requests to this domain and all @@ -81,8 +78,8 @@ available over HTTPS): [source,erlang] ---- SessionID = generate_session_id(), -Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, - #{secure => true}, Req0). +Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0, + #{secure => true}). ---- To prevent client-side scripts from accessing a cookie: @@ -90,8 +87,8 @@ To prevent client-side scripts from accessing a cookie: [source,erlang] ---- SessionID = generate_session_id(), -Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, - #{http_only => true}, Req0). +Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0, + #{http_only => true}). ---- Cookies may also be set client-side, for example using diff --git a/docs/en/cowboy/2.0/guide/cookies/index.html b/docs/en/cowboy/2.0/guide/cookies/index.html index 2f9ddb08..ae8c4ab9 100644 --- a/docs/en/cowboy/2.0/guide/cookies/index.html +++ b/docs/en/cowboy/2.0/guide/cookies/index.html @@ -110,8 +110,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</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:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
+ #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>To delete cookies, set <code>max_age</code> to 0:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
@@ -119,8 +119,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</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:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
+ #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>To restrict cookies to a specific domain and path, the options
of the same name can be used:</p></div>
<div class="listingblock">
@@ -128,8 +128,8 @@ of the same name can be used:</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>,
- #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>,
+ #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Cookies will be sent with requests to this domain and all
its subdomains, and to resources on this path or deeper
in the path hierarchy.</p></div>
@@ -141,8 +141,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</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:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
+ #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>To prevent client-side scripts from accessing a cookie:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
@@ -150,8 +150,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</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:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
+ #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Cookies may also be set client-side, for example using
Javascript.</p></div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc index 2c82c530..dbee9271 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc @@ -34,7 +34,7 @@ loop handler behavior. This tuple may optionally contain a timeout value and/or the atom `hibernate` to make the process enter hibernation until a message is received. -This snippet enables the loop handler. +This snippet enables the loop handler: [source,erlang] ---- @@ -42,14 +42,12 @@ init(Req, State) -> {cowboy_loop, Req, State}. ---- -However it is largely recommended that you set a timeout -value. The next example sets a timeout value of 30s and -also makes the process hibernate. +This also makes the process hibernate: [source,erlang] ---- init(Req, State) -> - {cowboy_loop, Req, State, 30000, hibernate}. + {cowboy_loop, Req, State, hibernate}. ---- === Receive loop @@ -123,25 +121,6 @@ a subsequent request. Please refer to the xref:handlers[Handlers chapter] for general instructions about cleaning up. -=== Timeout - -Note that this feature currently does not work. It will be -brought back in a future 2.0 pre-release. - -By default Cowboy will not attempt to close the connection -if there is no activity from the client. This is not always -desirable, which is why you can set a timeout. Cowboy will -close the connection if no data was received from the client -after the configured time. The timeout only needs to be set -once and can't be modified afterwards. - -Because the request may have had a body, or may be followed -by another request, Cowboy is forced to buffer all data it -receives. This data may grow to become too large though, -so there is a configurable limit for it. The default buffer -size is of 5000 bytes, but it may be changed by setting the -`loop_max_buffer` middleware environment value. - === Hibernate To save memory, you may hibernate the process in between diff --git a/docs/en/cowboy/2.0/guide/loop_handlers/index.html b/docs/en/cowboy/2.0/guide/loop_handlers/index.html index 7f3be1d7..09b9a5e1 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/loop_handlers/index.html @@ -95,7 +95,7 @@ for plain HTTP handlers.</p></div> loop handler behavior. This tuple may optionally contain
a timeout value and/or the atom <code>hibernate</code> to make the
process enter hibernation until a message is received.</p></div>
-<div class="paragraph"><p>This snippet enables the loop handler.</p></div>
+<div class="paragraph"><p>This snippet enables the loop handler:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
@@ -103,16 +103,14 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
{<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>However it is largely recommended that you set a timeout
-value. The next example sets a timeout value of 30s and
-also makes the process hibernate.</p></div>
+<div class="paragraph"><p>This also makes the process hibernate:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #993399">30000</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+ {<span style="color: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
</div>
</div>
<div class="sect1">
@@ -185,25 +183,6 @@ for general instructions about cleaning up.</p></div> </div>
</div>
<div class="sect1">
-<h2 id="_timeout">Timeout</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Note that this feature currently does not work. It will be
-brought back in a future 2.0 pre-release.</p></div>
-<div class="paragraph"><p>By default Cowboy will not attempt to close the connection
-if there is no activity from the client. This is not always
-desirable, which is why you can set a timeout. Cowboy will
-close the connection if no data was received from the client
-after the configured time. The timeout only needs to be set
-once and can’t be modified afterwards.</p></div>
-<div class="paragraph"><p>Because the request may have had a body, or may be followed
-by another request, Cowboy is forced to buffer all data it
-receives. This data may grow to become too large though,
-so there is a configurable limit for it. The default buffer
-size is of 5000 bytes, but it may be changed by setting the
-<code>loop_max_buffer</code> middleware environment value.</p></div>
-</div>
-</div>
-<div class="sect1">
<h2 id="_hibernate">Hibernate</h2>
<div class="sectionbody">
<div class="paragraph"><p>To save memory, you may hibernate the process in between
diff --git a/docs/en/cowboy/2.0/guide/req.asciidoc b/docs/en/cowboy/2.0/guide/req.asciidoc index 9afee098..b879fa3d 100644 --- a/docs/en/cowboy/2.0/guide/req.asciidoc +++ b/docs/en/cowboy/2.0/guide/req.asciidoc @@ -197,8 +197,6 @@ And any other combination. === Bindings -// @todo Bindings should probably be a map themselves. - 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. @@ -222,10 +220,7 @@ To retrieve everything that was bound: [source,erlang] Bindings = cowboy_req:bindings(Req). -They are returned as a list of key/value pairs, with -keys being atoms. - -// ... +They are returned as a map, with keys being atoms. The Cowboy router also allows you to capture many host or path segments at once using the `...` qualifier. diff --git a/docs/en/cowboy/2.0/guide/req/index.html b/docs/en/cowboy/2.0/guide/req/index.html index 08b5f18f..8f561dd8 100644 --- a/docs/en/cowboy/2.0/guide/req/index.html +++ b/docs/en/cowboy/2.0/guide/req/index.html @@ -303,8 +303,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">Bindings</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:bindings</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>They are returned as a list of key/value pairs, with
-keys being atoms.</p></div>
+<div class="paragraph"><p>They are returned as a map, with keys being atoms.</p></div>
<div class="paragraph"><p>The Cowboy router also allows you to capture many host
or path segments at once using the <code>...</code> qualifier.</p></div>
<div class="paragraph"><p>To retrieve the segments captured from the host name:</p></div>
diff --git a/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc b/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc index 2ab96bcf..83fa975c 100644 --- a/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc +++ b/docs/en/cowboy/2.0/guide/sub_protocols.asciidoc @@ -20,31 +20,31 @@ init(Req, State) -> {cowboy_websocket, Req, State}. ---- -The return value may also have a `Timeout` value and/or the -atom `hibernate`. These options are useful for long living -connections. When they are not provided, the timeout value -defaults to `infinity` and the hibernate value to `run`. +The returned tuple may also have a fourth element containing +options for the sub protocol. No option is universal. While +it will usually be a map of options, it doesn't have to be. +For example loop handlers accept the atom `hibernate`. The following snippet switches to the `my_protocol` sub protocol, sets the timeout value to 5 seconds and enables hibernation: -// @todo Yeah maybe what we really need is an Opts map. - [source,erlang] ---- init(Req, State) -> - {my_protocol, Req, State, 5000, hibernate}. + {my_protocol, Req, State, #{ + timeout => 5000, + compress => true}}. ---- -If a sub protocol does not make use of these options, it should -crash if it receives anything other than the default values. +Sub protocols should ignore unknown options so as to not waste +resources doing unnecessary validation. === Upgrade -After the `init/2` function returns, Cowboy will then call the -`upgrade/6` function. This is the only callback defined by the -`cowboy_sub_protocol` behavior. +After the `init/2` function returns, Cowboy will call either +the `upgrade/4` or the `upgrade/5` function. The former is called +when no options were given; the latter when they were given. The function is named `upgrade` because it mimics the mechanism of HTTP protocol upgrades. For some sub protocols, like Websocket, @@ -53,16 +53,19 @@ only an upgrade at Cowboy's level and the client has nothing to do about it. The upgrade callback receives the Req object, the middleware -environment, the handler and its options, and the aforementioned -timeout and hibernate values. +environment, the handler and its state, and for `upgrade/5` +also the aformentioned options. [source,erlang] ---- -upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) -> +upgrade(Req, Env, Handler, State) -> + %% Sub protocol code here. + +upgrade(Req, Env, Handler, State, Opts) -> %% Sub protocol code here. ---- -This callback is expected to behave like a middleware and to +These callbacks are expected to behave like middlewares and to return an updated environment and Req object. Sub protocols are expected to call the `cowboy_handler:terminate/4` diff --git a/docs/en/cowboy/2.0/guide/sub_protocols/index.html b/docs/en/cowboy/2.0/guide/sub_protocols/index.html index 96ff7661..0d6e1bfc 100644 --- a/docs/en/cowboy/2.0/guide/sub_protocols/index.html +++ b/docs/en/cowboy/2.0/guide/sub_protocols/index.html @@ -87,10 +87,10 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
{<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The return value may also have a <code>Timeout</code> value and/or the
-atom <code>hibernate</code>. These options are useful for long living
-connections. When they are not provided, the timeout value
-defaults to <code>infinity</code> and the hibernate value to <code>run</code>.</p></div>
+<div class="paragraph"><p>The returned tuple may also have a fourth element containing
+options for the sub protocol. No option is universal. While
+it will usually be a map of options, it doesn’t have to be.
+For example loop handlers accept the atom <code>hibernate</code>.</p></div>
<div class="paragraph"><p>The following snippet switches to the <code>my_protocol</code> sub
protocol, sets the timeout value to 5 seconds and enables
hibernation:</p></div>
@@ -100,33 +100,38 @@ by 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">my_protocol</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If a sub protocol does not make use of these options, it should
-crash if it receives anything other than the default values.</p></div>
+ {<span style="color: #FF6600">my_protocol</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, #{
+ <span style="color: #0000FF">timeout</span> <span style="color: #990000">=></span> <span style="color: #993399">5000</span>,
+ <span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>}}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Sub protocols should ignore unknown options so as to not waste
+resources doing unnecessary validation.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_upgrade">Upgrade</h2>
<div class="sectionbody">
-<div class="paragraph"><p>After the <code>init/2</code> function returns, Cowboy will then call the
-<code>upgrade/6</code> function. This is the only callback defined by the
-<code>cowboy_sub_protocol</code> behavior.</p></div>
+<div class="paragraph"><p>After the <code>init/2</code> function returns, Cowboy will call either
+the <code>upgrade/4</code> or the <code>upgrade/5</code> function. The former is called
+when no options were given; the latter when they were given.</p></div>
<div class="paragraph"><p>The function is named <code>upgrade</code> because it mimics the mechanism
of HTTP protocol upgrades. For some sub protocols, like Websocket,
an actual upgrade is performed. For others, like REST, this is
only an upgrade at Cowboy’s level and the client has nothing to
do about it.</p></div>
<div class="paragraph"><p>The upgrade callback receives the Req object, the middleware
-environment, the handler and its options, and the aforementioned
-timeout and hibernate values.</p></div>
+environment, the handler and its state, and for <code>upgrade/5</code>
+also the aformentioned options.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">upgrade</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">HandlerOpts</span>, <span style="color: #009900">Timeout</span>, <span style="color: #009900">Hibernate</span>) <span style="color: #990000">-></span>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">upgrade</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ <span style="font-style: italic"><span style="color: #9A1900">%% Sub protocol code here.</span></span>
+
+<span style="font-weight: bold"><span style="color: #000000">upgrade</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
<span style="font-style: italic"><span style="color: #9A1900">%% Sub protocol code here.</span></span></tt></pre></div></div>
-<div class="paragraph"><p>This callback is expected to behave like a middleware and to
+<div class="paragraph"><p>These callbacks are expected to behave like middlewares and to
return an updated environment and Req object.</p></div>
<div class="paragraph"><p>Sub protocols are expected to call the <code>cowboy_handler:terminate/4</code>
function when they terminate. This function will make sure that
diff --git a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc index 011aa314..2c38b87b 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc @@ -60,13 +60,13 @@ be: init(Req, State) -> case cowboy_req:parse_header(<<"sec-websocket-protocol">>, Req) of undefined -> - {ok, Req, State}; + {cowboy_websocket, Req, State}; Subprotocols -> case lists:keymember(<<"mqtt">>, 1, Subprotocols) of true -> Req2 = cowboy_req:set_resp_header(<<"sec-websocket-protocol">>, <<"mqtt">>, Req), - {ok, Req2, State}; + {cowboy_websocket, Req2, State}; false -> {stop, Req, State} end @@ -210,12 +210,13 @@ than needed. The `init/2` callback can set the timeout to be used for the connection. For example, this would make Cowboy -close connections idle for more than 60 seconds: +close connections idle for more than 30 seconds: [source,erlang] ---- init(Req, State) -> - {cowboy_websocket, Req, State, 60000}. + {cowboy_websocket, Req, State, #{ + idle_timeout => 30000}}. ---- This value cannot be changed once it is set. It defaults to diff --git a/docs/en/cowboy/2.0/guide/ws_handlers/index.html b/docs/en/cowboy/2.0/guide/ws_handlers/index.html index 61352974..f6175498 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/ws_handlers/index.html @@ -127,13 +127,13 @@ http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
<span style="color: #000080">undefined</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>};
<span style="color: #009900">Subprotocols</span> <span style="color: #990000">-></span>
<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">lists:keymember</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Subprotocols</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
<span style="color: #000080">true</span> <span style="color: #990000">-></span>
<span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>,
<span style="color: #990000"><<</span><span style="color: #FF0000">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>};
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req2</span>, <span style="color: #009900">State</span>};
<span style="color: #000080">false</span> <span style="color: #990000">-></span>
{<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
@@ -275,14 +275,15 @@ a timeout here, to avoid having processes linger longer than needed.</p></div>
<div class="paragraph"><p>The <code>init/2</code> callback can set the timeout to be used
for the connection. For example, this would make Cowboy
-close connections idle for more than 60 seconds:</p></div>
+close connections idle for more than 30 seconds:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #993399">60000</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, #{
+ <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="color: #993399">30000</span>}}<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>This value cannot be changed once it is set. It defaults to
<code>infinity</code>.</p></div>
</div>
diff --git a/docs/en/cowboy/2.0/guide/ws_protocol.asciidoc b/docs/en/cowboy/2.0/guide/ws_protocol.asciidoc index 127c829c..8fa0673d 100644 --- a/docs/en/cowboy/2.0/guide/ws_protocol.asciidoc +++ b/docs/en/cowboy/2.0/guide/ws_protocol.asciidoc @@ -65,6 +65,5 @@ Cowboy's Websocket implementation also includes the permessage-deflate and x-webkit-deflate-frame compression extensions. -Cowboy will automatically use compression as long as the -`websocket_compress` protocol option is set when starting -the listener. +Cowboy will automatically use compression when the +`compress` option is returned from the `init/2` function. diff --git a/docs/en/cowboy/2.0/guide/ws_protocol/index.html b/docs/en/cowboy/2.0/guide/ws_protocol/index.html index fe390c12..b026430a 100644 --- a/docs/en/cowboy/2.0/guide/ws_protocol/index.html +++ b/docs/en/cowboy/2.0/guide/ws_protocol/index.html @@ -129,9 +129,8 @@ suite with 100% success, including all optional tests.</p></div> <div class="paragraph"><p>Cowboy’s Websocket implementation also includes the
permessage-deflate and x-webkit-deflate-frame compression
extensions.</p></div>
-<div class="paragraph"><p>Cowboy will automatically use compression as long as the
-<code>websocket_compress</code> protocol option is set when starting
-the listener.</p></div>
+<div class="paragraph"><p>Cowboy will automatically use compression when the
+<code>compress</code> option is returned from the <code>init/2</code> function.</p></div>
</div>
</div>
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 51b1dbf2..2696bf83 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html @@ -111,8 +111,6 @@ 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>}
@@ -124,7 +122,7 @@ http://www.gnu.org/software/src-highlite --> <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: #009900">Reason</span> <span style="color: #990000">::</span> <span style="color: #FF6600">stop</span>
| {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch
to the loop behavior, it must return <code>cowboy_loop</code> as the
@@ -148,16 +146,6 @@ stop </p>
</dd>
<dt class="hdlist1">
-timeout
-</dt>
-<dd>
-<p>
- The connection has been closed due to inactivity. The timeout
- value can be configured from <code>init/2</code>. The response sent when
- this happens is a <code>204 No Content</code>.
-</p>
-</dd>
-<dt class="hdlist1">
{crash, Class, Reason}
</dt>
<dd>
@@ -177,7 +165,7 @@ timeout <div class="ulist"><ul>
<li>
<p>
-<strong>2.0</strong>: Cowboy temporarily no longer checks the socket for data with HTTP/1.1.
+<strong>2.0</strong>: Loop handlers no longer need to handle overflow/timeouts.
</p>
</li>
<li>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html index bcc63705..6e67fa0d 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html @@ -83,8 +83,8 @@ by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">bindings</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span> <span style="color: #990000">::</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>()}]</tt></pre></div></div>
-<div class="paragraph"><p>Return all bindings as a list of key/value pairs.</p></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">bindings</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:bindings</span></span>()</tt></pre></div></div>
+<div class="paragraph"><p>Return a map containing all bindings.</p></div>
</div>
</div>
<div class="sect1">
@@ -116,7 +116,7 @@ automatically converting numbers to integer).</p></div> <div class="ulist"><ul>
<li>
<p>
-<strong>2.0</strong>: Only the values are returned, it is no longer wrapped in a tuple.
+<strong>2.0</strong>: Only the values are returned, they are no longer wrapped in a tuple.
</p>
</li>
<li>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html index b4009df9..6791fb3c 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html @@ -86,10 +86,10 @@ http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
<span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, [], <span style="color: #009900">Req</span>)
-<span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Opts</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="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
<span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
+<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_cookie:cookie_opts</span></span>()</tt></pre></div></div>
<div class="paragraph"><p>Set a cookie to be sent with the response.</p></div>
@@ -117,19 +117,19 @@ Cookie value. </p>
</dd>
<dt class="hdlist1">
-Opts
+Req
</dt>
<dd>
<p>
-Optional cookie options.
+The Req object.
</p>
</dd>
<dt class="hdlist1">
-Req
+Opts
</dt>
<dd>
<p>
-The Req object.
+Cookie options.
</p>
</dd>
</dl></div>
@@ -154,6 +154,11 @@ otherwise the cookie will not be sent in the response.</p></div> </li>
<li>
<p>
+<strong>2.0</strong>: The first argument type is now <code>binary()</code> instead of <code>iodata()</code>.
+</p>
+</li>
+<li>
+<p>
<strong>1.0</strong>: Function introduced.
</p>
</li>
@@ -177,28 +182,24 @@ http://www.gnu.org/software/src-highlite --> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"fr-FR"</span><span style="color: #990000">>></span>, [
- {<span style="color: #FF6600">max_age</span>, <span style="color: #993399">3600</span>}
-], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"fr-FR"</span><span style="color: #990000">>></span>,
+ <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="listingblock">
<div class="title">Delete a cookie</div>
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<>></span>, [
- {<span style="color: #FF6600">max_age</span>, <span style="color: #993399">0</span>}
-], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<>></span>,
+ <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="listingblock">
<div class="title">Set a cookie for a specific domain and path</div>
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, [
- {<span style="color: #FF6600">domain</span>, <span style="color: #FF0000">"my.example.org"</span>},
- {<span style="color: #FF6600">path</span>, <span style="color: #FF0000">"/account"</span>}
-], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>,
+ <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="listingblock">
<div class="title">Restrict a cookie to HTTPS</div>
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
@@ -206,9 +207,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, [
- {<span style="color: #FF6600">secure</span>, <span style="color: #000080">true</span>}
-], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</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:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
+ <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
<div class="listingblock">
<div class="title">Restrict a cookie to HTTP</div>
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
@@ -216,9 +216,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, [
- {<span style="color: #FF6600">http_only</span>, <span style="color: #000080">true</span>}
-], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</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:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
+ <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
</div>
</div>
<div class="sect1">
diff --git a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html index 5f3f05c5..06e5363b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html @@ -96,9 +96,6 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
<span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">cowboy_rest</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">cowboy_rest</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_rest</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="color: #009900">Callback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
<span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
diff --git a/docs/en/cowboy/2.0/manual/cowboy_router/index.html b/docs/en/cowboy/2.0/manual/cowboy_router/index.html index 87ff24d1..23e0a8ea 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_router/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_router/index.html @@ -115,7 +115,7 @@ a 404 response otherwise.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">bindings</span></span>() <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">bindings</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
<div class="paragraph"><p>Bindings found during routing.</p></div>
</div>
<div class="sect2">
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 8a772db5..1f31291b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html @@ -84,38 +84,6 @@ for handling Websocket connections.</p></div> </div>
</div>
<div class="sect1">
-<h2 id="_options">Options</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #FF6600">websocket_compress</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-}</tt></pre></div></div>
-<div class="paragraph"><p>Configuration for the Websocket protocol.</p></div>
-<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners
-using <code>cowboy:start_clear/4</code> or <code>cowboy:start_tls/4</code> functions.</p></div>
-<div class="paragraph"><p>It can be updated without restarting listeners using the
-Ranch functions <code>ranch:get_protocol_options/1</code> and
-<code>ranch:set_protocol_options/2</code>.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-websocket_compress (false)
-</dt>
-<dd>
-<p>
- Whether to enable the Websocket frame compression
- extension. Frames will only be compressed for the
- clients that support this extension.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
<h2 id="_callbacks">Callbacks</h2>
<div class="sectionbody">
<div class="paragraph"><p>Websocket handlers must implement the following callback
@@ -127,9 +95,7 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
<span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">cowboy_websocket</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_websocket</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="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}
<span style="font-weight: bold"><span style="color: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">InFrame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span>
@@ -139,6 +105,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
+<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_websocket:opts</span></span>()
<span style="color: #009900">InFrame</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span> | <span style="font-weight: bold"><span style="color: #000080">binary</span></span> | <span style="color: #FF6600">ping</span> | <span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
<span style="color: #009900">OutFrame</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_ws:frame</span></span>()
<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
@@ -279,6 +246,57 @@ timeout </div>
</div>
<div class="sect1">
+<h2 id="_types">Types</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_opts">opts()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">opts</span></span>() <span style="color: #990000">::</span> #{
+ <span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(),
+ <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()
+}</tt></pre></div></div>
+<div class="paragraph"><p>Websocket handler options.</p></div>
+<div class="paragraph"><p>This configuration is passed to Cowboy from the <code>init/2</code>
+function:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
+ <span style="color: #009900">Opts</span> <span style="color: #990000">=</span> #{<span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>},
+ {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The default value is given next to the option name:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+compress (false)
+</dt>
+<dd>
+<p>
+ Whether to enable the Websocket frame compression
+ extension. Frames will only be compressed for the
+ clients that support this extension.
+</p>
+</dd>
+<dt class="hdlist1">
+idle_timeout (60000)
+</dt>
+<dd>
+<p>
+ Time in milliseconds that Cowboy will keep the
+ connection open without receiving anything from
+ the client.
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</div>
+<div class="sect1">
<h2 id="_changelog">Changelog</h2>
<div class="sectionbody">
<div class="ulist"><ul>
diff --git a/docs/en/erlang.mk/1/guide/installation.asciidoc b/docs/en/erlang.mk/1/guide/installation.asciidoc index f3a52cf4..a1e5fd33 100644 --- a/docs/en/erlang.mk/1/guide/installation.asciidoc +++ b/docs/en/erlang.mk/1/guide/installation.asciidoc @@ -22,7 +22,7 @@ The commands to install packages vary between distributions: .Arch Linux [source,bash] -$ pacman -Sy erlang git make +$ pacman -S erlang git make ==== FreeBSD diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html index f9e33c18..c5d017cb 100644 --- a/docs/en/erlang.mk/1/guide/installation/index.html +++ b/docs/en/erlang.mk/1/guide/installation/index.html @@ -90,7 +90,7 @@ have further requirements depending on your needs.</p></div> by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ pacman -Sy erlang git make</tt></pre></div></div>
+<pre><tt>$ pacman -S erlang git make</tt></pre></div></div>
</div>
<div class="sect3">
<h4 id="_freebsd">FreeBSD</h4>
|