diff options
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_http/index.html | 313 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_http2/index.html (renamed from docs/en/cowboy/2.0/manual/cowboy_protocol/index.html) | 128 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html | 3 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html | 3 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html | 3 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html | 3 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html | 225 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_router/index.html | 147 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_websocket/index.html | 239 | ||||
| -rw-r--r-- | docs/en/cowboy/2.0/manual/index.html | 16 | ||||
| -rw-r--r-- | docs/index.xml | 16 | ||||
| -rw-r--r-- | donate/index.html | 4 | ||||
| -rw-r--r-- | index.html | 4 | ||||
| -rw-r--r-- | services/index.html | 4 | ||||
| -rw-r--r-- | sitemap.xml | 14 |
15 files changed, 839 insertions, 283 deletions
diff --git a/docs/en/cowboy/2.0/manual/cowboy_http/index.html b/docs/en/cowboy/2.0/manual/cowboy_http/index.html new file mode 100644 index 00000000..80347684 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_http/index.html @@ -0,0 +1,313 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.17" /> + + <title>Nine Nines: cowboy_http(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>cowboy_http(3)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>cowboy_http - HTTP/1.1</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">Description</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The module <code>cowboy_http</code> implements HTTP/1.1 and HTTP/1.0
+as a Ranch protocol.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_options">Options</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">opts</span></span>() <span style="color: #990000">::</span> #{
+ <span style="color: #FF6600">env</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(),
+ <span style="color: #FF6600">max_empty_lines</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
+ <span style="color: #FF6600">max_header_name_length</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
+ <span style="color: #FF6600">max_header_value_length</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
+ <span style="color: #FF6600">max_headers</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
+ <span style="color: #FF6600">max_keepalive</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
+ <span style="color: #FF6600">max_method_length</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
+ <span style="color: #FF6600">max_request_line_length</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
+ <span style="color: #FF6600">middlewares</span> <span style="color: #990000">:=</span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()],
+ <span style="color: #FF6600">request_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>Configuration for the HTTP/1.1 protocol.</p></div>
+<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners
+using <code>cowboy:start_clear/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">
+env (#{})
+</dt>
+<dd>
+<p>
+ Middleware environment.
+</p>
+</dd>
+<dt class="hdlist1">
+max_empty_lines (5)
+</dt>
+<dd>
+<p>
+ Maximum number of empty lines before a request.
+</p>
+</dd>
+<dt class="hdlist1">
+max_header_name_length (64)
+</dt>
+<dd>
+<p>
+ Maximum length of header names.
+</p>
+</dd>
+<dt class="hdlist1">
+max_header_value_length (4096)
+</dt>
+<dd>
+<p>
+ Maximum length of header values.
+</p>
+</dd>
+<dt class="hdlist1">
+max_headers (100)
+</dt>
+<dd>
+<p>
+ Maximum number of headers allowed per request.
+</p>
+</dd>
+<dt class="hdlist1">
+max_keepalive (100)
+</dt>
+<dd>
+<p>
+ Maximum number of requests allowed per connection.
+</p>
+</dd>
+<dt class="hdlist1">
+max_request_line_length (8000)
+</dt>
+<dd>
+<p>
+ Maximum length of the request line.
+</p>
+</dd>
+<dt class="hdlist1">
+max_method_length (32)
+</dt>
+<dd>
+<p>
+ Maximum length of the method.
+</p>
+</dd>
+<dt class="hdlist1">
+middlewares ([cowboy_router, cowboy_handler])
+</dt>
+<dd>
+<p>
+ Middlewares to run for every request.
+</p>
+</dd>
+<dt class="hdlist1">
+request_timeout (5000)
+</dt>
+<dd>
+<p>
+ Time in ms with no requests before Cowboy closes the connection.
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_changelog">Changelog</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
+<p>
+<strong>2.0</strong>: The <code>max_method_length</code> option was added.
+</p>
+</li>
+<li>
+<p>
+<strong>2.0</strong>: The <code>env</code> option is now a map instead of a proplist.
+</p>
+</li>
+<li>
+<p>
+<strong>2.0</strong>: The <code>max_header_request_line_length</code> default was increased from 4096 to 8000.
+</p>
+</li>
+<li>
+<p>
+<strong>2.0</strong>: The <code>compress</code> option was temporarily removed.
+</p>
+</li>
+<li>
+<p>
+<strong>2.0</strong>: Options are now a map instead of a proplist.
+</p>
+</li>
+<li>
+<p>
+<strong>2.0</strong>: Protocol introduced. Replaces <code>cowboy_protocol</code>.
+</p>
+</li>
+</ul></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_see_also">See also</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><a href="../cowboy_app">cowboy(7)</a>,
+<a href="../cowboy_http">cowboy_http2(3)</a>,
+<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div>
+</div>
+</div>
+ + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/cowboy/2.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/cowboy/2.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/cowboy/1.0/manual">1.0</a></li> + + <li><a href="/docs/en/cowboy/2.0/manual">2.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_protocol/index.html b/docs/en/cowboy/2.0/manual/cowboy_http2/index.html index e934d308..3824a0ff 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_protocol/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_http2/index.html @@ -9,7 +9,7 @@ <meta name="generator" content="Hugo 0.17" /> - <title>Nine Nines: cowboy_protocol(3)</title> + <title>Nine Nines: cowboy_http2(3)</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -67,115 +67,48 @@ <div class="row"> <div id="docs" class="span9 maincol"> -<h1 class="lined-header"><span>cowboy_protocol(3)</span></h1> +<h1 class="lined-header"><span>cowboy_http2(3)</span></h1> <div class="sect1">
<h2 id="_name">Name</h2>
<div class="sectionbody">
-<div class="paragraph"><p>cowboy_protocol - HTTP protocol</p></div>
+<div class="paragraph"><p>cowboy_http2 - HTTP/2</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">Description</h2>
<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_protocol</code> module implements HTTP/1.1 and HTTP/1.0
+<div class="paragraph"><p>The module <code>cowboy_http2</code> implements HTTP/2
as a Ranch protocol.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_types">Types</h2>
+<h2 id="_options">Options</h2>
<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opts_option">opts() = [Option]</h3>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Option</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">compress</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">env</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>()}
- | {<span style="color: #FF6600">max_empty_lines</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">max_header_name_length</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">max_header_value_length</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">max_headers</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">max_keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">max_request_line_length</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">middlewares</span>, [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()]}
- | {<span style="color: #FF6600">onresponse</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:onresponse_fun</span></span>()}
- | {<span style="color: #FF6600">timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Configuration for the HTTP protocol handler.</p></div>
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">opts</span></span>() <span style="color: #990000">::</span> #{
+ <span style="color: #FF6600">env</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(),
+ <span style="color: #FF6600">middlewares</span> <span style="color: #990000">:=</span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()],
+ <span style="color: #FF6600">preface_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>Configuration for the HTTP/2 protocol.</p></div>
<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners
-using <code>cowboy:start_http/4</code> or <code>cowboy:start_https/4</code> functions.</p></div>
+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>
-<div class="sect2">
-<h3 id="_option_descriptions">Option descriptions</h3>
-<div class="paragraph"><p>The default value is given next to the option name.</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">
-compress (false)
-</dt>
-<dd>
-<p>
- When enabled, Cowboy will attempt to compress the response body.
-</p>
-</dd>
-<dt class="hdlist1">
-env ([{listener, Ref}])
-</dt>
-<dd>
-<p>
- Initial middleware environment.
-</p>
-</dd>
-<dt class="hdlist1">
-max_empty_lines (5)
-</dt>
-<dd>
-<p>
- Maximum number of empty lines before a request.
-</p>
-</dd>
-<dt class="hdlist1">
-max_header_name_length (64)
-</dt>
-<dd>
-<p>
- Maximum length of header names.
-</p>
-</dd>
-<dt class="hdlist1">
-max_header_value_length (4096)
-</dt>
-<dd>
-<p>
- Maximum length of header values.
-</p>
-</dd>
-<dt class="hdlist1">
-max_headers (100)
-</dt>
-<dd>
-<p>
- Maximum number of headers allowed per request.
-</p>
-</dd>
-<dt class="hdlist1">
-max_keepalive (100)
-</dt>
-<dd>
-<p>
- Maximum number of requests allowed per connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_request_line_length (4096)
+env (#{})
</dt>
<dd>
<p>
- Maximum length of the request line.
+ Middleware environment.
</p>
</dd>
<dt class="hdlist1">
@@ -183,28 +116,39 @@ middlewares ([cowboy_router, cowboy_handler]) </dt>
<dd>
<p>
- List of middlewares to execute for every requests.
+ Middlewares to run for every request.
</p>
</dd>
<dt class="hdlist1">
-onresponse (undefined)
+preface_timeout (5000)
</dt>
<dd>
<p>
- Fun called every time a response is sent.
+ Time in ms Cowboy is willing to wait for the connection preface.
</p>
</dd>
-<dt class="hdlist1">
-timeout (5000)
-</dt>
-<dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_changelog">Changelog</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
<p>
- Time in ms with no requests before Cowboy closes the connection.
+<strong>2.0</strong>: Protocol introduced.
</p>
-</dd>
-</dl></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_http">cowboy_http(3)</a>,
+<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div>
+</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html index 948f8133..e16db302 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html @@ -175,7 +175,8 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
+<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
+<a href="../cowboy_router">cowboy_router(3)</a></p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html index 65c3435a..e563c4b3 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 @@ -145,7 +145,8 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
+<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
+<a href="../cowboy_router">cowboy_router(3)</a></p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html index 3b4ceb51..c19270e5 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html @@ -146,7 +146,8 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
+<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
+<a href="../cowboy_router">cowboy_router(3)</a></p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html index d136a852..2836bff4 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html @@ -146,7 +146,8 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a></p></div>
+<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
+<a href="../cowboy_router">cowboy_router(3)</a></p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html b/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html new file mode 100644 index 00000000..57f2c171 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html @@ -0,0 +1,225 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.17" /> + + <title>Nine Nines: cowboy_router:compile(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>cowboy_router:compile(3)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>cowboy_router:compile - Compile routes to the resources</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">Description</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">compile</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_router:routes</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:dispatch_rules</span></span>()</tt></pre></div></div>
+<div class="paragraph"><p>Compile routes to the resources.</p></div>
+<div class="paragraph"><p>Takes a human readable list of routes and transforms it
+into a form more efficient to process.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_arguments">Arguments</h2>
+<div class="sectionbody">
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Routes
+</dt>
+<dd>
+<p>
+Human readable list of routes.
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_return_value">Return value</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>An opaque dispatch rules value is returned. This value
+must be given to Cowboy as a middleware environment value.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_changelog">Changelog</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
+<p>
+<strong>1.0</strong>: Function introduced.
+</p>
+</li>
+</ul></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_examples">Examples</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="title">Compile routes and start a listener</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
+ {<span style="color: #FF6600">'_'</span>, [
+ {<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">toppage_h</span>, []},
+ {<span style="color: #FF0000">"/[...], cowboy_static, {priv_dir, my_example_app, ""}}</span>
+<span style="color: #FF0000"> ]}</span>
+<span style="color: #FF0000">]),</span>
+
+<span style="color: #FF0000">{ok, _} = cowboy:start_clear(example, 100, [{port, 8080}], #{</span>
+<span style="color: #FF0000"> env => #{dispatch => Dispatch}</span>
+<span style="color: #FF0000">}).</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_see_also">See also</h2>
+<div class="sectionbody">
+<div class="paragraph"><p><a href="../cowboy_router">cowboy_router(3)</a></p></div>
+</div>
+</div>
+ + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/cowboy/2.0/guide">User Guide</a></li> + + + <li><a href="/docs/en/cowboy/2.0/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/cowboy/1.0/manual">1.0</a></li> + + <li><a href="/docs/en/cowboy/2.0/manual">2.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + 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 2f4186f3..415b178f 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_router/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_router/index.html @@ -72,106 +72,105 @@ <div class="sect1">
<h2 id="_name">Name</h2>
<div class="sectionbody">
-<div class="paragraph"><p>cowboy_router - router middleware</p></div>
+<div class="paragraph"><p>cowboy_router - Router middleware</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">Description</h2>
<div class="sectionbody">
<div class="paragraph"><p>The <code>cowboy_router</code> middleware maps the requested host and
-path to the handler to be used for processing the request.
-It uses the dispatch rules compiled from the routes given
-to the <code>compile/1</code> function for this purpose. It adds the
-handler name and options to the environment as the values
-<code>handler</code> and <code>handler_opts</code> respectively.</p></div>
-<div class="sect2">
-<h3 id="_environment_input">Environment input</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-dispatch = dispatch_rules()
-</dt>
-<dd>
-<p>
-Dispatch table.
-</p>
-</dd>
-</dl></div>
+path to the handler to be used for processing the request.</p></div>
+<div class="paragraph"><p>The router takes the <code>dispatch</code> rules as input from the
+middleware environment. Dispatch rules are generated by
+calling the
+<a href="../cowboy_router.compile">cowboy_router:compile(3)</a>
+function.</p></div>
+<div class="paragraph"><p>When a route matches, the router sets the <code>handler</code> and
+<code>handler_opts</code> middleware environment values containing
+the handler module and initial state, respectively.</p></div>
+<div class="paragraph"><p>The router will stop execution when no route matches.
+It will send a 400 response if no host was found, and
+a 404 response otherwise.</p></div>
</div>
-<div class="sect2">
-<h3 id="_environment_output">Environment output</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-handler = module()
-</dt>
-<dd>
-<p>
-Handler module.
-</p>
-</dd>
-<dt class="hdlist1">
-handler_opts = any()
-</dt>
-<dd>
+</div>
+<div class="sect1">
+<h2 id="_exports">Exports</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
<p>
-Handler options.
+<a href="../cowboy_router.compile">cowboy_router:compile(3)</a> - Compile routes to the resources
</p>
-</dd>
-</dl></div>
-</div>
+</li>
+</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_types">Types</h2>
<div class="sectionbody">
<div class="sect2">
-<h3 id="_bindings_atom_binary">bindings() = [{atom(), binary()}]</h3>
-<div class="paragraph"><p>List of bindings found during routing.</p></div>
+<h3 id="_bindings">bindings()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">bindings</span></span>() <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div>
+<div class="paragraph"><p>Bindings found during routing.</p></div>
</div>
<div class="sect2">
-<h3 id="_dispatch_rules_opaque_to_the_user">dispatch_rules() - opaque to the user</h3>
-<div class="paragraph"><p>Rules for dispatching request used by Cowboy.</p></div>
+<h3 id="_dispatch_rules">dispatch_rules()</h3>
+<div class="paragraph"><p>Opaque type containing the compiled routes.</p></div>
</div>
<div class="sect2">
-<h3 id="_routes_host_paths_host_cowboy_fields_paths">routes() = [{Host, Paths} | {Host, cowboy:fields(), Paths}]</h3>
-<div class="paragraph"><p>With types:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Host = Path = <em>_</em> | iodata()
-</p>
-</li>
-<li>
-<p>
-Paths = [{Path, Handler, Opts} | {Path, cowboy:fields(), Handler, HandlerOpts}]
-</p>
-</li>
-<li>
-<p>
-Handler = module()
-</p>
-</li>
-<li>
-<p>
-HandlerOpts = any()
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Human readable list of routes mapping hosts and paths to handlers.</p></div>
-<div class="paragraph"><p>The syntax for routes is defined in the user guide.</p></div>
+<h3 id="_routes">routes()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">routes</span></span>() <span style="color: #990000">=</span> [
+ {<span style="color: #009900">Host</span>, <span style="color: #009900">PathList</span>} |
+ {<span style="color: #009900">Host</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">PathList</span>}
+]
+
+<span style="color: #009900">PathList</span> <span style="color: #990000">::</span> [
+ {<span style="color: #009900">Path</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>} |
+ {<span style="color: #009900">Path</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}
+]
+
+<span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
+<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
+<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>()
+<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>()
+<span style="color: #009900">InitialState</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
+<div class="paragraph"><p>Human readable list of routes to handlers.</p></div>
+<div class="paragraph"><p>Cowboy uses this list to map hosts and paths, optionally
+augmented with constraints applied to the bindings, to
+handler modules.</p></div>
+<div class="paragraph"><p>The syntax for routes is currently defined in the user guide.</p></div>
</div>
<div class="sect2">
-<h3 id="_tokens_binary">tokens() = [binary()]</h3>
-<div class="paragraph"><p>List of host_info and path_info tokens found during routing.</p></div>
+<h3 id="_tokens">tokens()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">tokens</span></span>() <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]</tt></pre></div></div>
+<div class="paragraph"><p>List of <code>host_info</code> and <code>path_info</code> tokens that were found
+using the <code>...</code> syntax.</p></div>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="_exports">Exports</h2>
+<h2 id="_see_also">See also</h2>
<div class="sectionbody">
-<div class="sect2">
-<h3 id="_compile_routes_8594_dispatch_rules">compile(routes()) → dispatch_rules()</h3>
-<div class="paragraph"><p>Compile the routes for use by Cowboy.</p></div>
-</div>
+<div class="paragraph"><p><a href="../cowboy_app">cowboy(7)</a>,
+<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
+<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
+<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
+<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html index 8274fbf8..2ca978a3 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html @@ -72,68 +72,126 @@ <div class="sect1">
<h2 id="_name">Name</h2>
<div class="sectionbody">
-<div class="paragraph"><p>cowboy_websocket - Websocket protocol</p></div>
+<div class="paragraph"><p>cowboy_websocket - Websocket</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">Description</h2>
<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_websocket</code> module implements the Websocket protocol.</p></div>
-<div class="paragraph"><p>This module is a sub protocol that defines four 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>websocket_handle/2</code> and <code>websocket_info/2</code> callbacks are
-specific to Websocket handlers and will be called as many times
-as necessary until the Websocket connection is closed.</p></div>
-<div class="paragraph"><p>The <code>init/2</code> callback can be used to negotiate Websocket protocol
-extensions with the client. It is highly recommended to return a
-timeout value from this 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>Cowboy will terminate the process right after closing the
-Websocket connection. This means that there is no real need to
-perform any cleanup in the optional <code>terminate/3</code> callback.</p></div>
+<div class="paragraph"><p>The module <code>cowboy_websocket</code> implements Websocket
+as a Ranch protocol. It also defines a callback interface
+for handling Websocket connections.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_meta_values">Meta values</h2>
+<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 = boolean()
-</dt>
-<dd>
-<p>
- Whether a websocket compression extension in in use.
-</p>
-</dd>
-<dt class="hdlist1">
-websocket_version = 7 | 8 | 13
+websocket_compress (false)
</dt>
<dd>
<p>
- The version of the Websocket protocol being used.
+ 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="_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>Websocket handlers must implement the following callback
+interface:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
+ <span style="color: #990000">-></span> {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
+ | {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #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="font-weight: bold"><span style="color: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
+<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">InFrame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span>
+<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span>
+
+<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #000080">undefined</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></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">InFrame</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span> | <span style="font-weight: bold"><span style="color: #000080">binary</span></span> | <span style="color: #FF6600">ping</span> | <span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
+<span style="color: #009900">OutFrame</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_ws:frame</span></span>()
+<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
+
+<span style="color: #009900">CallResult</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}
+ | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
+ | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>}
+ | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
+ | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}
+
+<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> | <span style="color: #FF6600">stop</span> | <span style="color: #FF6600">timeout</span>
+ | <span style="color: #FF6600">remote</span> | {<span style="color: #FF6600">remote</span>, <span style="font-weight: bold"><span style="color: #000000">cow_ws:close_code</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
+ | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">badencoding</span> | <span style="color: #FF6600">badframe</span> | <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}
+ | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
+<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To upgrade
+the connection to Websocket, it must return <code>cowboy_websocket</code>
+as the first element of the tuple.</p></div>
+<div class="paragraph"><p>Any operation requiring the HTTP request must be done in the
+<code>init/2</code> function, as the Req object will not be available
+after it returns. Websocket sub-protocol selection should
+therefore be done in this function.</p></div>
+<div class="paragraph"><p>The optional <code>websocket_init/1</code> callback will be called once
+the connection has been upgraded to Websocket. It can be used
+to perform any required initialization of the handler.</p></div>
+<div class="paragraph"><p>Note that the <code>init/2</code> function does not run in the same
+process as the Websocket callbacks. Any Websocket-specific
+initialization must be done in <code>websocket_init/1</code>.</p></div>
+<div class="paragraph"><p>The <code>websocket_handle/2</code> callback will be called for every
+frame received. The <code>websocket_info/2</code> callback will be
+called for every Erlang message received.</p></div>
+<div class="paragraph"><p>All three Websocket callbacks may send one or more frames
+back to the client (by returning a <code>reply</code> tuple) or terminate
+the connection (by sending a <code>close</code> frame or returning a <code>stop</code>
+tuple).</p></div>
+<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
+with the reason for the termination of the connection. This
+callback is common to all handlers. Note that Websocket has
+no concept of requests so it sets the second argument to
+undefined.</p></div>
+<div class="paragraph"><p>Cowboy will terminate the process right after closing the
+Websocket connection. This means that there is no need to
+perform any cleanup in the <code>terminate/3</code> callback.</p></div>
+<div class="paragraph"><p>The following terminate reasons are defined for Websocket
+connections:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
normal
</dt>
<dd>
<p>
- The connection was closed normally before establishing a Websocket
- connection. This typically happens if an <code>ok</code> tuple is returned
- from the <code>init/2</code> callback.
+ The connection was closed normally before establishing a Websocket
+ connection. This typically happens if an <code>ok</code> tuple is returned
+ from the <code>init/2</code> callback.
</p>
</dd>
<dt class="hdlist1">
@@ -141,8 +199,8 @@ remote </dt>
<dd>
<p>
- The remote endpoint closed the connection without giving any
- further details.
+ The remote endpoint closed the connection without giving any
+ further details.
</p>
</dd>
<dt class="hdlist1">
@@ -150,8 +208,8 @@ remote </dt>
<dd>
<p>
- The remote endpoint closed the connection with the given
- <code>Code</code> and <code>Payload</code> as the reason.
+ The remote endpoint closed the connection with the given
+ <code>Code</code> and <code>Payload</code> as the reason.
</p>
</dd>
<dt class="hdlist1">
@@ -159,8 +217,8 @@ stop </dt>
<dd>
<p>
- The handler requested to close the connection, either by returning
- a <code>stop</code> tuple or by sending a <code>close</code> frame.
+ The handler requested to close the connection, either by returning
+ a <code>stop</code> tuple or by sending a <code>close</code> frame.
</p>
</dd>
<dt class="hdlist1">
@@ -168,8 +226,8 @@ timeout </dt>
<dd>
<p>
- The connection has been closed due to inactivity. The timeout
- value can be configured from <code>init/2</code>.
+ The connection has been closed due to inactivity. The timeout
+ value can be configured from <code>init/2</code>.
</p>
</dd>
<dt class="hdlist1">
@@ -177,10 +235,10 @@ 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.
+ 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">
@@ -188,8 +246,8 @@ timeout </dt>
<dd>
<p>
- A text frame was sent by the client with invalid encoding. All
- text frames must be valid UTF-8.
+ A text frame was sent by the client with invalid encoding. All
+ text frames must be valid UTF-8.
</p>
</dd>
<dt class="hdlist1">
@@ -197,7 +255,7 @@ timeout </dt>
<dd>
<p>
- A protocol error has been detected.
+ A protocol error has been detected.
</p>
</dd>
<dt class="hdlist1">
@@ -205,8 +263,8 @@ timeout </dt>
<dd>
<p>
- The socket has been closed brutally without a close frame being
- received first.
+ The socket has been closed brutally without a close frame being
+ received first.
</p>
</dd>
<dt class="hdlist1">
@@ -214,67 +272,40 @@ timeout </dt>
<dd>
<p>
- A socket error ocurred.
+ A socket error ocurred.
</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="_websocket_handle_inframe_state_8594_ret">websocket_handle(InFrame, State) → Ret</h3>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Ret</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">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">State</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">any</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>()</tt></pre></div></div>
-<div class="paragraph"><p>Handle the data received from the Websocket connection.</p></div>
-<div class="paragraph"><p>This function will be called every time data is received
-from the Websocket connection.</p></div>
-<div class="paragraph"><p>The <code>stop</code> return value can be used to close the
-connection. A close reply will also result in the connection
-being closed.</p></div>
-<div class="paragraph"><p>The <code>hibernate</code> option will hibernate the process until
-it receives new data from the Websocket connection or an
-Erlang message.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<strong>2.0</strong>: The Req object is no longer passed to Websocket callbacks.
+</p>
+</li>
+<li>
+<p>
+<strong>2.0</strong>: The callback <code>websocket_terminate/3</code> was removed in favor of <code>terminate/3</code>.
+</p>
+</li>
+<li>
+<p>
+<strong>1.0</strong>: Protocol introduced.
+</p>
+</li>
+</ul></div>
</div>
-<div class="sect2">
-<h3 id="_websocket_info_info_state_8594_ret">websocket_info(Info, State) → Ret</h3>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Ret</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Info</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">any</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">OutFrame</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cow_ws:frame</span></span>()</tt></pre></div></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 close the
-connection. A close reply will also result in the connection
-being closed.</p></div>
-<div class="paragraph"><p>The <code>hibernate</code> option will hibernate the process until
-it receives another message or new data from the Websocket
-connection.</p></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_http">cowboy_http(3)</a>,
+<a href="../cowboy_http">cowboy_http2(3)</a></p></div>
</div>
</div>
diff --git a/docs/en/cowboy/2.0/manual/index.html b/docs/en/cowboy/2.0/manual/index.html index af3f9c18..2a31a74a 100644 --- a/docs/en/cowboy/2.0/manual/index.html +++ b/docs/en/cowboy/2.0/manual/index.html @@ -87,17 +87,22 @@ </li>
<li>
<p>
-<a href="cowboy_loop">cowboy_loop(3)</a>
+<a href="cowboy_http2">cowboy_http2(3)</a>
</p>
</li>
<li>
<p>
-<a href="cowboy_middleware">cowboy_middleware(3)</a>
+<a href="cowboy_http">cowboy_http(3)</a>
+</p>
+</li>
+<li>
+<p>
+<a href="cowboy_loop">cowboy_loop(3)</a>
</p>
</li>
<li>
<p>
-<a href="cowboy_protocol">cowboy_protocol(3)</a>
+<a href="cowboy_middleware">cowboy_middleware(3)</a>
</p>
</li>
<li>
@@ -297,6 +302,11 @@ </li>
<li>
<p>
+<a href="cowboy_router.compile">cowboy_router:compile(3)</a>
+</p>
+</li>
+<li>
+<p>
<a href="cowboy.set_env">cowboy:set_env(3)</a>
</p>
</li>
diff --git a/docs/index.xml b/docs/index.xml index 9d1270bd..8e2294c6 100644 --- a/docs/index.xml +++ b/docs/index.xml @@ -32,17 +32,22 @@ </li>
<li>
<p>
-<a href="cowboy_loop">cowboy_loop(3)</a>
+<a href="cowboy_http2">cowboy_http2(3)</a>
</p>
</li>
<li>
<p>
-<a href="cowboy_middleware">cowboy_middleware(3)</a>
+<a href="cowboy_http">cowboy_http(3)</a>
+</p>
+</li>
+<li>
+<p>
+<a href="cowboy_loop">cowboy_loop(3)</a>
</p>
</li>
<li>
<p>
-<a href="cowboy_protocol">cowboy_protocol(3)</a>
+<a href="cowboy_middleware">cowboy_middleware(3)</a>
</p>
</li>
<li>
@@ -242,6 +247,11 @@ </li>
<li>
<p>
+<a href="cowboy_router.compile">cowboy_router:compile(3)</a>
+</p>
+</li>
+<li>
+<p>
<a href="cowboy.set_env">cowboy:set_env(3)</a>
</p>
</li>
diff --git a/donate/index.html b/donate/index.html index 1e809dc8..59f9aa78 100644 --- a/donate/index.html +++ b/donate/index.html @@ -462,6 +462,10 @@ work on open source software including Cowboy and Erlang.mk.</p></div> + + + + </div> </div> </div> @@ -602,6 +602,10 @@ + + + + </div> </div> diff --git a/services/index.html b/services/index.html index 633b9c0d..63253252 100644 --- a/services/index.html +++ b/services/index.html @@ -547,6 +547,10 @@ work on open source software including Cowboy and Erlang.mk.</p></div> + + + + </div> </div> </div> diff --git a/sitemap.xml b/sitemap.xml index 7b0d320d..1907c869 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -204,15 +204,19 @@ </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http2/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_protocol/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</loc> </url> <url> @@ -372,6 +376,10 @@ </url> <url> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router.compile/</loc> + </url> + + <url> <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_static/</loc> </url> |