diff options
Diffstat (limited to 'docs/en/cowboy/2.3/guide/listeners/index.html')
-rw-r--r-- | docs/en/cowboy/2.3/guide/listeners/index.html | 128 |
1 files changed, 40 insertions, 88 deletions
diff --git a/docs/en/cowboy/2.3/guide/listeners/index.html b/docs/en/cowboy/2.3/guide/listeners/index.html index 0990f98c..743c25fb 100644 --- a/docs/en/cowboy/2.3/guide/listeners/index.html +++ b/docs/en/cowboy/2.3/guide/listeners/index.html @@ -62,109 +62,61 @@ <h1 class="lined-header"><span>Listeners</span></h1> -<div class="paragraph"><p>A listener is a set of processes that listens on a port for -new connections. Incoming connections get handled by Cowboy. -Depending on the connection handshake, one or another protocol -may be used.</p></div> -<div class="paragraph"><p>This chapter is specific to Cowboy. Please refer to the -<a href="https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/">Ranch User Guide</a> -for more information about listeners.</p></div> -<div class="paragraph"><p>Cowboy provides two types of listeners: one listening for -clear TCP connections, and one listening for secure TLS -connections. Both of them support the HTTP/1.1 and HTTP/2 -protocols.</p></div> -<div class="sect1"> +<p>A listener is a set of processes that listens on a port for new connections. Incoming connections get handled by Cowboy. Depending on the connection handshake, one or another protocol may be used.</p> +<p>This chapter is specific to Cowboy. Please refer to the <a href="https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/">Ranch User Guide</a> for more information about listeners.</p> +<p>Cowboy provides two types of listeners: one listening for clear TCP connections, and one listening for secure TLS connections. Both of them support the HTTP/1.1 and HTTP/2 protocols.</p> <h2 id="_clear_tcp_listener">Clear TCP listener</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The clear TCP listener will accept connections on the -given port. A typical HTTP server would listen on port 80. -Port 80 requires special permissions on most platforms -however so a common alternative is port 8080.</p></div> -<div class="paragraph"><p>The following snippet starts listening for connections -on port 8080:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>The clear TCP listener will accept connections on the given port. A typical HTTP server would listen on port 80. Port 80 requires special permissions on most platforms however so a common alternative is port 8080.</p> +<p>The following snippet starts listening for connections on port 8080:</p> +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> - <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">hello_handler</span>, []}]} +<pre><tt><b><font color="#000000">start</font></b>(<font color="#009900">_Type</font>, <font color="#009900">_Args</font>) <font color="#990000">-></font> + <font color="#009900">Dispatch</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_router:compile</font></b>([ + {<font color="#FF6600">'_'</font>, [{<font color="#FF0000">"/"</font>, <font color="#FF6600">hello_handler</font>, []}]} ]), - {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>, - [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], - #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}} + {<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy:start_clear</font></b>(<font color="#FF6600">my_http_listener</font>, + [{<font color="#FF6600">port</font>, <font color="#993399">8080</font>}], + #{<font color="#0000FF">env</font> <font color="#990000">=></font> #{<font color="#0000FF">dispatch</font> <font color="#990000">=></font> <font color="#009900">Dispatch</font>}} ), - <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>The <a href="../getting_started">Getting Started</a> chapter uses a -clear TCP listener.</p></div> -<div class="paragraph"><p>Clients connecting to Cowboy on the clear listener port are -expected to use either HTTP/1.1 or HTTP/2.</p></div> -<div class="paragraph"><p>Cowboy supports both methods of initiating a clear -HTTP/2 connection: through the Upgrade mechanism -(<a href="https://tools.ietf.org/html/rfc7540#section-3.2">RFC 7540 3.2</a>) -or by sending the preface directly -(<a href="https://tools.ietf.org/html/rfc7540#section-3.4">RFC 7540 3.4</a>).</p></div> -<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 -implementation.</p></div> -</div> -</div> -<div class="sect1"> + <b><font color="#000000">hello_erlang_sup:start_link</font></b>()<font color="#990000">.</font></tt></pre> +</div></div> +<p>The <a href="../getting_started">Getting Started</a> chapter uses a clear TCP listener.</p> +<p>Clients connecting to Cowboy on the clear listener port are expected to use either HTTP/1.1 or HTTP/2.</p> +<p>Cowboy supports both methods of initiating a clear HTTP/2 connection: through the Upgrade mechanism (<a href="https://tools.ietf.org/html/rfc7540#section-3.2">RFC 7540 3.2</a>) or by sending the preface directly (<a href="https://tools.ietf.org/html/rfc7540#section-3.4">RFC 7540 3.4</a>).</p> +<p>Compatibility with HTTP/1.0 is provided by Cowboy's HTTP/1.1 implementation.</p> <h2 id="_secure_tls_listener">Secure TLS listener</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The secure TLS listener will accept connections on the -given port. A typical HTTPS server would listen on port 443. -Port 443 requires special permissions on most platforms -however so a common alternative is port 8443.</p></div> -<div class="paragraph"><p>The function provided by Cowboy will ensure that the TLS -options given are following the HTTP/2 RFC with regards -to security. For example some TLS extensions or ciphers -may be disabled. This also applies to HTTP/1.1 connections -on this listener. If this is not desirable, Ranch can be -used directly to setup a custom listener.</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>The secure TLS listener will accept connections on the given port. A typical HTTPS server would listen on port 443. Port 443 requires special permissions on most platforms however so a common alternative is port 8443.</p> +<!-- @todo Make a complete list of restrictions.--> +<p>The function provided by Cowboy will ensure that the TLS options given are following the HTTP/2 RFC with regards to security. For example some TLS extensions or ciphers may be disabled. This also applies to HTTP/1.1 connections on this listener. If this is not desirable, Ranch can be used directly to setup a custom listener.</p> +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> - <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">hello_handler</span>, []}]} +<pre><tt><b><font color="#000000">start</font></b>(<font color="#009900">_Type</font>, <font color="#009900">_Args</font>) <font color="#990000">-></font> + <font color="#009900">Dispatch</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_router:compile</font></b>([ + {<font color="#FF6600">'_'</font>, [{<font color="#FF0000">"/"</font>, <font color="#FF6600">hello_handler</font>, []}]} ]), - {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:start_tls</span></span>(<span style="color: #FF6600">my_http_listener</span>, + {<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy:start_tls</font></b>(<font color="#FF6600">my_http_listener</font>, [ - {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>}, - {<span style="color: #FF6600">certfile</span>, <span style="color: #FF0000">"/path/to/certfile"</span>}, - {<span style="color: #FF6600">keyfile</span>, <span style="color: #FF0000">"/path/to/keyfile"</span>} + {<font color="#FF6600">port</font>, <font color="#993399">8443</font>}, + {<font color="#FF6600">certfile</font>, <font color="#FF0000">"/path/to/certfile"</font>}, + {<font color="#FF6600">keyfile</font>, <font color="#FF0000">"/path/to/keyfile"</font>} ], - #{<span style="color: #0000FF">env</span> <span style="color: #990000">=></span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=></span> <span style="color: #009900">Dispatch</span>}} + #{<font color="#0000FF">env</font> <font color="#990000">=></font> #{<font color="#0000FF">dispatch</font> <font color="#990000">=></font> <font color="#009900">Dispatch</font>}} ), - <span style="font-weight: bold"><span style="color: #000000">hello_erlang_sup:start_link</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Clients connecting to Cowboy on the secure listener are -expected to use the ALPN TLS extension to indicate what -protocols they understand. Cowboy always prefers HTTP/2 -over HTTP/1.1 when both are supported. When neither are -supported by the client, or when the ALPN extension was -missing, Cowboy expects HTTP/1.1 to be used.</p></div> -<div class="paragraph"><p>Cowboy also advertises HTTP/2 support through the older -NPN TLS extension for compatibility. Note however that -this support will likely not be enabled by default when -Cowboy 2.0 gets released.</p></div> -<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 -implementation.</p></div> -</div> -</div> -<div class="sect1"> + <b><font color="#000000">hello_erlang_sup:start_link</font></b>()<font color="#990000">.</font></tt></pre> +</div></div> +<p>Clients connecting to Cowboy on the secure listener are expected to use the ALPN TLS extension to indicate what protocols they understand. Cowboy always prefers HTTP/2 over HTTP/1.1 when both are supported. When neither are supported by the client, or when the ALPN extension was missing, Cowboy expects HTTP/1.1 to be used.</p> +<p>Cowboy also advertises HTTP/2 support through the older NPN TLS extension for compatibility. Note however that this support will likely not be enabled by default when Cowboy 2.0 gets released.</p> +<p>Compatibility with HTTP/1.0 is provided by Cowboy's HTTP/1.1 implementation.</p> <h2 id="_protocol_configuration">Protocol configuration</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The HTTP/1.1 and HTTP/2 protocols share the same semantics; -only their framing differs. The first is a text protocol and -the second a binary protocol.</p></div> -<div class="paragraph"><p>Cowboy doesn’t separate the configuration for HTTP/1.1 and -HTTP/2. Everything goes into the same map. Many options are -shared.</p></div> -</div> -</div> +<p>The HTTP/1.1 and HTTP/2 protocols share the same semantics; only their framing differs. The first is a text protocol and the second a binary protocol.</p> +<p>Cowboy doesn't separate the configuration for HTTP/1.1 and HTTP/2. Everything goes into the same map. Many options are shared.</p> +<!-- @todo Describe good to know options for both protocols?--> +<!-- Maybe do that in separate chapters?--> + |