From 535795ce51750412439e205b14779f107d81a5e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 30 Aug 2016 14:33:00 +0200 Subject: Update documentation --- docs/en/cowboy/2.0/guide/listeners.asciidoc | 115 ++++++++++++ docs/en/cowboy/2.0/guide/listeners/index.html | 245 ++++++++++++++++++++++++++ 2 files changed, 360 insertions(+) create mode 100644 docs/en/cowboy/2.0/guide/listeners.asciidoc create mode 100644 docs/en/cowboy/2.0/guide/listeners/index.html (limited to 'docs/en') diff --git a/docs/en/cowboy/2.0/guide/listeners.asciidoc b/docs/en/cowboy/2.0/guide/listeners.asciidoc new file mode 100644 index 00000000..577883be --- /dev/null +++ b/docs/en/cowboy/2.0/guide/listeners.asciidoc @@ -0,0 +1,115 @@ +[[listeners]] +== Listeners + +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. + +This chapter is specific to Cowboy. Please refer to the +http://ninenines.eu/docs/en/ranch/1.2/guide/listeners/[Ranch User Guide] +for more information about listeners. + +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. + +=== Clear TCP listener + +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. + +The following snippet starts listening for connections +on port 8080: + +[source,erlang] +---- +start(_Type, _Args) -> + Dispatch = cowboy_router:compile([ + {'_', [{"/", hello_handler, []}]} + ]), + {ok, _} = cowboy:start_clear(my_http_listener, 100, + [{port, 8080}], + #{env => #{dispatch => Dispatch}} + ), + hello_erlang_sup:start_link(). +---- + +The xref:getting_started[Getting Started] chapter uses a +clear TCP listener. + +Clients connecting to Cowboy on the clear listener port are +expected to use either HTTP/1.1 or HTTP/2. + +Cowboy supports both methods of initiating a clear +HTTP/2 connection: through the Upgrade mechanism +(https://tools.ietf.org/html/rfc7540#section-3.2[RFC 7540 3.2]) +or by sending the preface directly +(https://tools.ietf.org/html/rfc7540#section-3.4[RFC 7540 3.4]). + +Compatibility with HTTP/1.0 is provided by Cowboy's HTTP/1.1 +implementation. + +=== Secure TLS listener + +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. + +// @todo Make a complete list of restrictions. + +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. + +[source,erlang] +---- +start(_Type, _Args) -> + Dispatch = cowboy_router:compile([ + {'_', [{"/", hello_handler, []}]} + ]), + {ok, _} = cowboy:start_tls(my_http_listener, 100, + [ + {port, 8443}, + {certfile, "/path/to/certfile"}, + {keyfile, "/path/to/keyfile"} + ], + #{env => #{dispatch => Dispatch}} + ), + hello_erlang_sup:start_link(). +---- + +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. + +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. + +Compatibility with HTTP/1.0 is provided by Cowboy's HTTP/1.1 +implementation. + +=== Protocol configuration + +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. + +Cowboy doesn't separate the configuration for HTTP/1.1 and +HTTP/2. Everything goes into the same map. Many options are +shared. + +// @todo Describe good to know options for both protocols? +// Maybe do that in separate chapters? diff --git a/docs/en/cowboy/2.0/guide/listeners/index.html b/docs/en/cowboy/2.0/guide/listeners/index.html new file mode 100644 index 00000000..d0de7d74 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/listeners/index.html @@ -0,0 +1,245 @@ + + + + + + + + + + + + Nine Nines: Listeners + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Listeners

+ +

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.

+

This chapter is specific to Cowboy. Please refer to the +Ranch User Guide +for more information about listeners.

+

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.

+
+

Clear TCP listener

+
+

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.

+

The following snippet starts listening for connections +on port 8080:

+
+
+
start(_Type, _Args) ->
+        Dispatch = cowboy_router:compile([
+                {'_', [{"/", hello_handler, []}]}
+        ]),
+        {ok, _} = cowboy:start_clear(my_http_listener, 100,
+                [{port, 8080}],
+                #{env => #{dispatch => Dispatch}}
+        ),
+        hello_erlang_sup:start_link().
+

The Getting Started chapter uses a +clear TCP listener.

+

Clients connecting to Cowboy on the clear listener port are +expected to use either HTTP/1.1 or HTTP/2.

+

Cowboy supports both methods of initiating a clear +HTTP/2 connection: through the Upgrade mechanism +(RFC 7540 3.2) +or by sending the preface directly +(RFC 7540 3.4).

+

Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 +implementation.

+
+
+
+

Secure TLS listener

+
+

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.

+

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.

+
+
+
start(_Type, _Args) ->
+        Dispatch = cowboy_router:compile([
+                {'_', [{"/", hello_handler, []}]}
+        ]),
+        {ok, _} = cowboy:start_tls(my_http_listener, 100,
+                [
+                        {port, 8443},
+                        {certfile, "/path/to/certfile"},
+                        {keyfile, "/path/to/keyfile"}
+                ],
+                #{env => #{dispatch => Dispatch}}
+        ),
+        hello_erlang_sup:start_link().
+

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.

+

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.

+

Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 +implementation.

+
+
+
+

Protocol configuration

+
+

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.

+

Cowboy doesn’t separate the configuration for HTTP/1.1 and +HTTP/2. Everything goes into the same map. Many options are +shared.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + -- cgit v1.2.3