Update docs

1 files changed, 209 insertions, 167 deletions

diff --git a/docs/index.xml b/docs/index.xml
index 09ef6b82..edeafd2e 100644
--- a/docs/index.xml
+++ b/docs/index.xml
@@ -210,8 +210,6 @@ environment configuration parameters.</p></div>
 <a href="getting_started/">Getting started</a>

 </p>

 </li>

-</ul></div>

-<div class="ulist"><ul>

 <li>

 <p>

 <a href="flow_diagram/">Flow diagram</a>

@@ -231,11 +229,6 @@ environment configuration parameters.</p></div>
 </li>

 <li>

 <p>

-<a href="streams/">Streams</a>

-</p>

-</li>

-<li>

-<p>

 <a href="routing/">Routing</a>

 </p>

 </li>

@@ -339,45 +332,68 @@ environment configuration parameters.</p></div>
 </li>

 <li>

 <p>

-<a href="ws_handlers/">Handling Websocket connections</a>

+<a href="ws_handlers/">Websocket handlers</a>

 </p>

 </li>

 </ul></div>

 </div>

 </div>

 <div class="sect1">

-<h2 id="_internals">Internals</h2>

+<h2 id="_advanced">Advanced</h2>

 <div class="sectionbody">

 <div class="ulist"><ul>

 <li>

 <p>

-<a href="architecture/">Architecture</a>

+<a href="streams/">Streams</a>

+</p>

+</li>

+<li>

+<p>

+<a href="middlewares/">Middlewares</a>

 </p>

 </li>

 </ul></div>

 <div class="ulist"><ul>

 <li>

 <p>

-<a href="broken_clients/">Dealing with broken clients</a>

+<a href="sub_protocols/">Sub protocols</a>

 </p>

 </li>

+</ul></div>

+</div>

+</div>

+<div class="sect1">

+<h2 id="_deprecated_chapters">Deprecated chapters</h2>

+<div class="sectionbody">

+</div>

+</div>

+<div class="sect1">

+<h2 id="_about_the_deprecated_chapters">About the deprecated chapters</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>The following chapters were relevant in Cowboy 1.0. They have

+not been updated for Cowboy 2.0 yet. The information in these

+chapters may or may not be useful.</p></div>

+<div class="ulist"><ul>

 <li>

 <p>

-<a href="middlewares/">Middlewares</a>

+<a href="architecture/">Architecture</a>

 </p>

 </li>

 <li>

 <p>

-<a href="sub_protocols/">Sub protocols</a>

+<a href="broken_clients/">Dealing with broken clients</a>

 </p>

 </li>

-</ul></div>

-<div class="ulist"><ul>

 <li>

 <p>

 <a href="hooks/">Hooks</a>

 </p>

 </li>

+<li>

+<p>

+<a href="overview/">Overview</a>

+</p>

+</li>

 </ul></div>

 </div>

 </div>

@@ -1081,158 +1097,6 @@ client and the connection is closed.</p></div>
     </item>
     
     <item>
-      <title>Request overview</title>
-      <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/overview/</link>
-      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-      
-      <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/overview/</guid>
-      <description>&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This chapter explains the different steps a request

-goes through until a response is sent, along with

-details of the Cowboy implementation.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;sect1&#34;&gt;

-&lt;h2 id=&#34;_request_response&#34;&gt;Request/response&lt;/h2&gt;

-&lt;div class=&#34;sectionbody&#34;&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;As you already know, HTTP clients connect to the server and

-send a request for a resource; the server then sends a

-response containing the resource if it could obtain it.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Before the server can send the resource, however, it

-needs to perform many different operations to read the

-request, find the resource, prepare the response being

-sent and often other related operations the user can

-add like writing logs.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Requests take the following route in Cowboy:&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;imageblock&#34;&gt;

-&lt;div class=&#34;content&#34;&gt;

-&lt;img src=&#34;../http_req_resp.png&#34; alt=&#34;HTTP request/response flowchart&#34; /&gt;

-&lt;/div&gt;

-&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This shows the default middlewares, but they may be

-configured differently in your setup. The dark green

-indicates the points where you can hook your own code,

-the light green is the Cowboy code that you can of

-course configure as needed.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The &lt;code&gt;acceptor&lt;/code&gt; is the part of the server that accepts

-the connection and create an Erlang process to handle

-it. The &lt;code&gt;parser&lt;/code&gt; then starts reading from the socket

-and handling requests as they come until the socket

-is closed.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;A response may be sent at many different points in the

-life of the request. If Cowboy can&amp;#8217;t parse the request,

-it gives up with an error response. If the router can&amp;#8217;t

-find the resource, it sends a not found error. Your

-own code can of course send a response at any time.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;When a response is sent, you can optionally modify it

-or act upon it by enabling the &lt;code&gt;onresponse&lt;/code&gt; hook. By

-default the response is sent directly to the client.&lt;/p&gt;&lt;/div&gt;

-&lt;/div&gt;

-&lt;/div&gt;

-&lt;div class=&#34;sect1&#34;&gt;

-&lt;h2 id=&#34;_and_then&#34;&gt;And then?&lt;/h2&gt;

-&lt;div class=&#34;sectionbody&#34;&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Behavior depends on what protocol is in use.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/1.0 can only process one request per connection,

-so Cowboy will close the connection immediately after

-it sends the response.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/1.1 allows the client to request that the server

-keeps the connection alive. This mechanism is described

-in the next section.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/2 is designed to allow sending multiple requests

-asynchronously on the same connection. Details on what

-this means for your application is described in this

-chapter.&lt;/p&gt;&lt;/div&gt;

-&lt;/div&gt;

-&lt;/div&gt;

-&lt;div class=&#34;sect1&#34;&gt;

-&lt;h2 id=&#34;_keep_alive_http_1_1&#34;&gt;Keep-alive (HTTP/1.1)&lt;/h2&gt;

-&lt;div class=&#34;sectionbody&#34;&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;With HTTP/1.1, the connection may be left open for

-subsequent requests to come. This mechanism is called

-&lt;code&gt;keep-alive&lt;/code&gt;.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;When the client sends a request to the server, it includes

-a header indicating whether it would like to leave the

-socket open. The server may or may not accept, indicating

-its choice by sending the same header in the response.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Cowboy will include this header automatically in all

-responses to HTTP/1.1 requests. You can however force

-the closing of the socket if you want. When Cowboy sees

-you want to send a &lt;code&gt;connection: close&lt;/code&gt; header, it will

-not override it and will close the connection as soon

-as the reply is sent.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This snippet will force Cowboy to close the connection.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;listingblock&#34;&gt;

-&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8

-by Lorenzo Bettini

-http://www.lorenzobettini.it

-http://www.gnu.org/software/src-highlite --&gt;

-&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;color: #009900&#34;&gt;Req2&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy_req:reply&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #993399&#34;&gt;200&lt;/span&gt;, [

-    {&lt;span style=&#34;color: #990000&#34;&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;connection&#34;&lt;/span&gt;&lt;span style=&#34;color: #990000&#34;&gt;&amp;gt;&amp;gt;&lt;/span&gt;, &lt;span style=&#34;color: #990000&#34;&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;close&#34;&lt;/span&gt;&lt;span style=&#34;color: #990000&#34;&gt;&amp;gt;&amp;gt;&lt;/span&gt;},

-], &lt;span style=&#34;color: #990000&#34;&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;Closing the socket in 3.. 2.. 1..&#34;&lt;/span&gt;&lt;span style=&#34;color: #990000&#34;&gt;&amp;gt;&amp;gt;&lt;/span&gt;, &lt;span style=&#34;color: #009900&#34;&gt;Req&lt;/span&gt;)&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Cowboy will only accept a certain number of new requests

-on the same connection. By default it will run up to 100

-requests. This number can be changed by setting the

-&lt;code&gt;max_keepalive&lt;/code&gt; configuration value when starting an

-HTTP listener.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;listingblock&#34;&gt;

-&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8

-by Lorenzo Bettini

-http://www.lorenzobettini.it

-http://www.gnu.org/software/src-highlite --&gt;

-&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy:start_http&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #FF6600&#34;&gt;my_http_listener&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;100&lt;/span&gt;, [{&lt;span style=&#34;color: #FF6600&#34;&gt;port&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;8080&lt;/span&gt;}], [

-        {&lt;span style=&#34;color: #FF6600&#34;&gt;env&lt;/span&gt;, [{&lt;span style=&#34;color: #FF6600&#34;&gt;dispatch&lt;/span&gt;, &lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt;}]},

-        {&lt;span style=&#34;color: #FF6600&#34;&gt;max_keepalive&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;5&lt;/span&gt;}

-])&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Cowboy implements the keep-alive mechanism by reusing

-the same process for all requests. This allows Cowboy

-to save memory. This works well because most code will

-not have any side effect impacting subsequent requests.

-But it also means you need to clean up if you do have

-code with side effects. The &lt;code&gt;terminate/3&lt;/code&gt; function can

-be used for this purpose.&lt;/p&gt;&lt;/div&gt;

-&lt;/div&gt;

-&lt;/div&gt;

-&lt;div class=&#34;sect1&#34;&gt;

-&lt;h2 id=&#34;_pipelining_http_1_1&#34;&gt;Pipelining (HTTP/1.1)&lt;/h2&gt;

-&lt;div class=&#34;sectionbody&#34;&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;While HTTP is designed as a sequential protocol, with

-the client sending a request and then waiting for the

-response from the server, nothing prevents the client

-from sending more requests to the server without waiting

-for the response, due to how sockets work. The server

-still handles the requests sequentially and sends the

-responses in the same order.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This mechanism is called pipelining. It allows reducing

-latency when a client needs to request many resources

-at the same time. This is used by browsers when requesting

-static files for example.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This is handled automatically by the server.&lt;/p&gt;&lt;/div&gt;

-&lt;/div&gt;

-&lt;/div&gt;

-&lt;div class=&#34;sect1&#34;&gt;

-&lt;h2 id=&#34;_asynchronous_requests_http_2&#34;&gt;Asynchronous requests (HTTP/2)&lt;/h2&gt;

-&lt;div class=&#34;sectionbody&#34;&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;In HTTP/2, the client can send a request at any time.

-And the server can send a response at any time too.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This means for example that the client does not need

-to wait for a request to be fully sent to send another,

-it is possible to interleave a request with the request

-body of another request. The same is true with responses.

-Responses may also be sent in a different order.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Because requests and responses are fully asynchronous,

-Cowboy creates a new process for each request, and these

-processes are managed by another process that handles the

-connection itself.&lt;/p&gt;&lt;/div&gt;

-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/2 servers may also decide to send resources to the

-client before the client requests them. This is especially

-useful for sending static files associated with the HTML

-page requested, as this reduces the latency of the overall

-response. Cowboy does not support this particular mechanism

-at this point, however.&lt;/p&gt;&lt;/div&gt;

-&lt;/div&gt;

-&lt;/div&gt;

-</description>
-    </item>
-    
-    <item>
       <title>cowboy(3)</title>
       <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/</link>
       <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
@@ -1825,5 +1689,183 @@ http://www.gnu.org/software/src-highlite --&gt;
 </description>
     </item>
     
+    <item>
+      <title>cowboy:start_tls(3)</title>
+      <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</link>
+      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+      
+      <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</guid>
+      <description>&lt;div class=&#34;sect1&#34;&gt;

+&lt;h2 id=&#34;_name&#34;&gt;Name&lt;/h2&gt;

+&lt;div class=&#34;sectionbody&#34;&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;cowboy:start_tls - Listen for connections using TLS&lt;/p&gt;&lt;/div&gt;

+&lt;/div&gt;

+&lt;/div&gt;

+&lt;div class=&#34;sect1&#34;&gt;

+&lt;h2 id=&#34;_description&#34;&gt;Description&lt;/h2&gt;

+&lt;div class=&#34;sectionbody&#34;&gt;

+&lt;div class=&#34;listingblock&#34;&gt;

+&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8

+by Lorenzo Bettini

+http://www.lorenzobettini.it

+http://www.gnu.org/software/src-highlite --&gt;

+&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;start_tls&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt;          &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;ranch:ref&lt;/span&gt;&lt;/span&gt;(),

+          &lt;span style=&#34;color: #009900&#34;&gt;NumAcceptors&lt;/span&gt;  &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;non_neg_integer&lt;/span&gt;&lt;/span&gt;(),

+          &lt;span style=&#34;color: #009900&#34;&gt;TransportOpts&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;ranch_ssl:opts&lt;/span&gt;&lt;/span&gt;(),

+          &lt;span style=&#34;color: #009900&#34;&gt;ProtocolOpts&lt;/span&gt;  &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;opts&lt;/span&gt;&lt;/span&gt;())

+    &lt;span style=&#34;color: #990000&#34;&gt;-&amp;gt;&lt;/span&gt; {&lt;span style=&#34;color: #FF6600&#34;&gt;ok&lt;/span&gt;, &lt;span style=&#34;color: #009900&#34;&gt;ListenerPid&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000080&#34;&gt;pid&lt;/span&gt;&lt;/span&gt;()}

+     | {&lt;span style=&#34;color: #FF6600&#34;&gt;error&lt;/span&gt;, &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;any&lt;/span&gt;&lt;/span&gt;()}&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Start listening for connections over a secure TLS channel.&lt;/p&gt;&lt;/div&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Both HTTP/1.1 and HTTP/2 are supported on this listener.

+The ALPN TLS extension must be used to initiate an HTTP/2

+connection.&lt;/p&gt;&lt;/div&gt;

+&lt;/div&gt;

+&lt;/div&gt;

+&lt;div class=&#34;sect1&#34;&gt;

+&lt;h2 id=&#34;_arguments&#34;&gt;Arguments&lt;/h2&gt;

+&lt;div class=&#34;sectionbody&#34;&gt;

+&lt;div class=&#34;dlist&#34;&gt;&lt;dl&gt;

+&lt;dt class=&#34;hdlist1&#34;&gt;

+Name

+&lt;/dt&gt;

+&lt;dd&gt;

+&lt;p&gt;

+The listener name is used to refer to this listener in

+future calls, for example when stopping it or when

+updating the routes defined.

+&lt;/p&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;It can be any Erlang term. An atom is generally good enough,

+for example &lt;code&gt;api&lt;/code&gt;, &lt;code&gt;my_app_clear&lt;/code&gt; or &lt;code&gt;my_app_tls&lt;/code&gt;.&lt;/p&gt;&lt;/div&gt;

+&lt;/dd&gt;

+&lt;dt class=&#34;hdlist1&#34;&gt;

+NumAcceptors

+&lt;/dt&gt;

+&lt;dd&gt;

+&lt;p&gt;

+The number of acceptors is the number of processes that

+will accept connections. Tweak this value to improve the

+accept rate for incoming connections.

+&lt;/p&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The ideal value is between 10 and 100 on most systems.

+Larger values may have the opposite effect and reduce the

+accept rate. It&amp;#8217;s generally safe to start with a value of

+100 (or 10 on low memory systems). Then, when accept rates

+become a concern, measure the performance and update the

+value accordingly.&lt;/p&gt;&lt;/div&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This value is unrelated to the maximum number of concurrent

+connections.&lt;/p&gt;&lt;/div&gt;

+&lt;/dd&gt;

+&lt;dt class=&#34;hdlist1&#34;&gt;

+TransportOpts

+&lt;/dt&gt;

+&lt;dd&gt;

+&lt;p&gt;

+The transport options are where the TCP options, including

+the listener&amp;#8217;s port number, are defined. They also contain

+the TLS options, like the server&amp;#8217;s certificate. Transport options

+are provided as a list of keys and values, for example

+&lt;code&gt;[{port, 8443}, {certfile, &#34;path/to/cert.pem&#34;}]&lt;/code&gt;.

+&lt;/p&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The available options are documented in the

+&lt;a href=&#34;../ranch_ssl&#34;&gt;ranch_ssl(3)&lt;/a&gt; manual.&lt;/p&gt;&lt;/div&gt;

+&lt;/dd&gt;

+&lt;dt class=&#34;hdlist1&#34;&gt;

+ProtocolOpts

+&lt;/dt&gt;

+&lt;dd&gt;

+&lt;p&gt;

+The protocol options are in a map containing all the options for

+the different protocols that may be involved when connecting

+to the listener, including HTTP/1.1 and HTTP/2 but also

+subprotocols like Websocket.

+&lt;/p&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The HTTP/1.1 options are documented in the

+&lt;a href=&#34;../cowboy_http&#34;&gt;cowboy_http(3)&lt;/a&gt; manual;

+the HTTP/2 options in

+&lt;a href=&#34;../cowboy_http2&#34;&gt;cowboy_http2(3)&lt;/a&gt;;

+and the Websocket options in

+&lt;a href=&#34;../cowboy_websocket&#34;&gt;cowboy_websocket(3)&lt;/a&gt;.&lt;/p&gt;&lt;/div&gt;

+&lt;/dd&gt;

+&lt;/dl&gt;&lt;/div&gt;

+&lt;/div&gt;

+&lt;/div&gt;

+&lt;div class=&#34;sect1&#34;&gt;

+&lt;h2 id=&#34;_return_value&#34;&gt;Return value&lt;/h2&gt;

+&lt;div class=&#34;sectionbody&#34;&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;An ok tuple is returned on success. It contains the pid of

+the top-level supervisor for the listener.&lt;/p&gt;&lt;/div&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;An error tuple is returned on error. The error reason may

+be any Erlang term.&lt;/p&gt;&lt;/div&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;A common error is &lt;code&gt;eaddrinuse&lt;/code&gt;. It indicates that the port

+configured for Cowboy is already in use.&lt;/p&gt;&lt;/div&gt;

+&lt;/div&gt;

+&lt;/div&gt;

+&lt;div class=&#34;sect1&#34;&gt;

+&lt;h2 id=&#34;_changelog&#34;&gt;Changelog&lt;/h2&gt;

+&lt;div class=&#34;sectionbody&#34;&gt;

+&lt;div class=&#34;ulist&#34;&gt;&lt;ul&gt;

+&lt;li&gt;

+&lt;p&gt;

+&lt;strong&gt;2.0&lt;/strong&gt;: HTTP/2 support added.

+&lt;/p&gt;

+&lt;/li&gt;

+&lt;li&gt;

+&lt;p&gt;

+&lt;strong&gt;2.0&lt;/strong&gt;: Function introduced. Replaces &lt;code&gt;cowboy:start_https/4&lt;/code&gt;.

+&lt;/p&gt;

+&lt;/li&gt;

+&lt;/ul&gt;&lt;/div&gt;

+&lt;/div&gt;

+&lt;/div&gt;

+&lt;div class=&#34;sect1&#34;&gt;

+&lt;h2 id=&#34;_examples&#34;&gt;Examples&lt;/h2&gt;

+&lt;div class=&#34;sectionbody&#34;&gt;

+&lt;div class=&#34;listingblock&#34;&gt;

+&lt;div class=&#34;title&#34;&gt;Start a listener&lt;/div&gt;

+&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8

+by Lorenzo Bettini

+http://www.lorenzobettini.it

+http://www.gnu.org/software/src-highlite --&gt;

+&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy_router:compile&lt;/span&gt;&lt;/span&gt;([

+    {&lt;span style=&#34;color: #FF6600&#34;&gt;&#39;_&#39;&lt;/span&gt;, [

+        {&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;/&#34;&lt;/span&gt;, &lt;span style=&#34;color: #FF6600&#34;&gt;toppage_h&lt;/span&gt;, []}

+    ]}

+]),

+

+{&lt;span style=&#34;color: #FF6600&#34;&gt;ok&lt;/span&gt;, &lt;span style=&#34;color: #990000&#34;&gt;_&lt;/span&gt;} &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy:start_tls&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #FF6600&#34;&gt;example&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;100&lt;/span&gt;, [

+    {&lt;span style=&#34;color: #FF6600&#34;&gt;port&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;8443&lt;/span&gt;},

+    {&lt;span style=&#34;color: #FF6600&#34;&gt;cert&lt;/span&gt;, &lt;span style=&#34;color: #FF0000&#34;&gt;&#34;path/to/cert.pem&#34;&lt;/span&gt;}

+], #{

+    &lt;span style=&#34;color: #0000FF&#34;&gt;env&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; #{&lt;span style=&#34;color: #0000FF&#34;&gt;dispatch&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; &lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt;}

+})&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

+&lt;div class=&#34;listingblock&#34;&gt;

+&lt;div class=&#34;title&#34;&gt;Start a listener on a random port&lt;/div&gt;

+&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8

+by Lorenzo Bettini

+http://www.lorenzobettini.it

+http://www.gnu.org/software/src-highlite --&gt;

+&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #FF6600&#34;&gt;example&lt;/span&gt;,

+

+{&lt;span style=&#34;color: #FF6600&#34;&gt;ok&lt;/span&gt;, &lt;span style=&#34;color: #990000&#34;&gt;_&lt;/span&gt;} &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy:start_tls&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;100&lt;/span&gt;, [

+    {&lt;span style=&#34;color: #FF6600&#34;&gt;cert&lt;/span&gt;, &lt;span style=&#34;color: #FF0000&#34;&gt;&#34;path/to/cert.pem&#34;&lt;/span&gt;}

+], #{

+    &lt;span style=&#34;color: #0000FF&#34;&gt;env&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; #{&lt;span style=&#34;color: #0000FF&#34;&gt;dispatch&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; &lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt;}

+}),

+

+&lt;span style=&#34;color: #009900&#34;&gt;Port&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;ranch:get_port&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt;)&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

+&lt;/div&gt;

+&lt;/div&gt;

+&lt;div class=&#34;sect1&#34;&gt;

+&lt;h2 id=&#34;_see_also&#34;&gt;See also&lt;/h2&gt;

+&lt;div class=&#34;sectionbody&#34;&gt;

+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;&lt;a href=&#34;../cowboy&#34;&gt;cowboy(3)&lt;/a&gt;,

+&lt;a href=&#34;../cowboy.start_clear&#34;&gt;cowboy:start_clear(3)&lt;/a&gt;,

+&lt;a href=&#34;../cowboy.stop_listener&#34;&gt;cowboy:stop_listener(3)&lt;/a&gt;,

+&lt;a href=&#34;../ranch&#34;&gt;ranch(3)&lt;/a&gt;&lt;/p&gt;&lt;/div&gt;

+&lt;/div&gt;

+&lt;/div&gt;

+</description>
+    </item>
+    
   </channel>
 </rss>
\ No newline at end of file