From 8459bebceb9533948193774371cbd9fd571b78ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 16 Oct 2019 09:48:31 +0200 Subject: Cowboy 2.7.0 --- .../ranch/2.0/guide/connection_draining/index.html | 8 ++-- docs/en/ranch/2.0/guide/embedded/index.html | 2 +- docs/en/ranch/2.0/guide/internals/index.html | 2 +- docs/en/ranch/2.0/guide/listeners.asciidoc | 4 +- docs/en/ranch/2.0/guide/listeners/index.html | 46 +++++++++++----------- .../en/ranch/2.0/guide/migrating_from_1.7.asciidoc | 15 +++++++ .../ranch/2.0/guide/migrating_from_1.7/index.html | 10 ++++- docs/en/ranch/2.0/guide/parsers/index.html | 6 +-- docs/en/ranch/2.0/guide/protocols.asciidoc | 2 +- docs/en/ranch/2.0/guide/protocols/index.html | 8 ++-- docs/en/ranch/2.0/guide/ssl_auth/index.html | 6 +-- docs/en/ranch/2.0/guide/transports/index.html | 16 ++++---- 12 files changed, 74 insertions(+), 51 deletions(-) (limited to 'docs/en/ranch/2.0/guide') diff --git a/docs/en/ranch/2.0/guide/connection_draining/index.html b/docs/en/ranch/2.0/guide/connection_draining/index.html index ba3e7112..75b17eb4 100644 --- a/docs/en/ranch/2.0/guide/connection_draining/index.html +++ b/docs/en/ranch/2.0/guide/connection_draining/index.html @@ -65,7 +65,7 @@

Stopping a Ranch listener via ranch:stop_listener/1 will invariably kill all connection processes the listener hosts. However, you may want to stop a listener in a graceful fashion, ie by not accepting any new connections, but allowing the existing connection processes to exit by themselves instead of being killed.

For this purpose, you should first suspend the listener you wish to stop gracefully, and then wait for its connection count to drop to zero.

Draining a single listener
-
@@ -75,7 +75,7 @@ http://www.gnu.org/software/src-highlite -->

If you want to drain more than just one listener, it may be important to first suspend them all before beginning to wait for their connection counts to reach zero. Otherwise, the not yet suspended listeners will still be accepting connections while you wait for the suspended ones to be drained.

Draining multiple listeners
-
@@ -95,7 +95,7 @@ http://www.gnu.org/software/src-highlite -->

If you have long-running connection processes hosted by the listener you want to stop gracefully, draining may take a long time, possibly forever. If you just want to give the connection processes a chance to finish, but are not willing to wait for infinity, the waiting part could be handled in a separate process.

Draining a listener with a timeout
-
@@ -116,7 +116,7 @@ http://www.gnu.org/software/src-highlite -->

To drain listeners automatically as part of your application shutdown routine, use the prep_stop/1 function of your application module.

Draining listeners automatically on application shutdown
-
diff --git a/docs/en/ranch/2.0/guide/embedded/index.html b/docs/en/ranch/2.0/guide/embedded/index.html index 4bc2b5cd..b0ea7472 100644 --- a/docs/en/ranch/2.0/guide/embedded/index.html +++ b/docs/en/ranch/2.0/guide/embedded/index.html @@ -70,7 +70,7 @@

Ranch has a convenience function for getting the listeners child specs called ranch:child_spec/5, that works like ranch:start_listener/5, except that it doesn't start anything, it only returns child specs.

The following example adds one listener to another application's supervision tree.

Embed Ranch directly in your supervision tree
-
diff --git a/docs/en/ranch/2.0/guide/internals/index.html b/docs/en/ranch/2.0/guide/internals/index.html index 5b07e48b..2b3bb7dc 100644 --- a/docs/en/ranch/2.0/guide/internals/index.html +++ b/docs/en/ranch/2.0/guide/internals/index.html @@ -82,7 +82,7 @@

This is especially useful if you expect many connections to be mostly idle, perhaps part of a connection pool. They can be handled by the kernel directly until they send any real data, instead of allocating resources to idle connections.

To enable this mechanism, the following option can be used.

Using raw transport options
-
diff --git a/docs/en/ranch/2.0/guide/listeners.asciidoc b/docs/en/ranch/2.0/guide/listeners.asciidoc index fd988f1c..6e2dd197 100644 --- a/docs/en/ranch/2.0/guide/listeners.asciidoc +++ b/docs/en/ranch/2.0/guide/listeners.asciidoc @@ -239,8 +239,8 @@ with the name of the listener as the only argument. [source,erlang] ranch:remove_connection(Ref). -As seen in the chapter covering protocols, this pid is received as the -first argument of the protocol's `start_link/4` callback. +As seen in the chapter covering protocols, this reference is received +as the first argument of the protocol's `start_link/3` callback. You can modify the `max_connections` value on a running listener by using the `ranch:set_max_connections/2` function, with the name of the diff --git a/docs/en/ranch/2.0/guide/listeners/index.html b/docs/en/ranch/2.0/guide/listeners/index.html index 9b654b4b..247b3810 100644 --- a/docs/en/ranch/2.0/guide/listeners/index.html +++ b/docs/en/ranch/2.0/guide/listeners/index.html @@ -80,7 +80,7 @@

Ranch includes both TCP and SSL transport handlers, respectively ranch_tcp and ranch_ssl.

A listener can be started by calling the ranch:start_listener/5 function. Before doing so however, you must ensure that the ranch application is started.

Starting the Ranch application
-
@@ -88,7 +88,7 @@ http://www.gnu.org/software/src-highlite -->

You are then ready to start a listener. Let's call it tcp_echo. It will have a pool of 100 acceptors, use a TCP transport and forward connections to the echo_protocol handler.

Starting a listener for TCP connections on port 5555
-
@@ -99,7 +99,7 @@ http://www.gnu.org/software/src-highlite -->

You can try this out by compiling and running the tcp_echo example in the examples directory. To do so, open a shell in the examples/tcp_echo/ directory and run the following command:

Building and starting a Ranch example
-
@@ -107,7 +107,7 @@ http://www.gnu.org/software/src-highlite -->

You can then connect to it using telnet and see the echo server reply everything you send to it. Then when you're done testing, you can use the Ctrl+] key to escape to the telnet command line and type quit to exit.

Connecting to the example listener with telnet
-
@@ -127,7 +127,7 @@ Connection closed.

Stopping a listener

All you need to stop a Ranch listener is to call the ranch:stop_listener/1 function with the listener's name as argument. In the previous section we started the listener named tcp_echo. We can now stop it.

Stopping a listener
-
@@ -137,7 +137,7 @@ http://www.gnu.org/software/src-highlite -->

Listeners can be suspended and resumed by calling ranch:suspend_listener/1 and ranch:resume_listener/1, respectively, with the name of the listener as argument.

Suspending a listener will cause it to stop listening and not accept new connections, but existing connection processes will not be stopped.

Suspending a listener
-
@@ -145,7 +145,7 @@ http://www.gnu.org/software/src-highlite -->

Resuming a listener will cause it to start listening and accept new connections again. It is worth mentioning, however, that if the listener is configured to listen on a random port, it will listen on a different port than before it was suspended.

Resuming a listener
-
@@ -159,7 +159,7 @@ http://www.gnu.org/software/src-highlite -->

You do not have to specify a specific port to listen on. If you give the port number 0, or if you omit the port number entirely, Ranch will start listening on a random port.

You can retrieve this port number by calling ranch:get_port/1. The argument is the name of the listener you gave in ranch:start_listener/5.

Starting a listener for TCP connections on a random port
-
@@ -176,7 +176,7 @@ http://www.gnu.org/software/src-highlite -->

Listening on a UNIX Domain socket

On UNIX systems, it is also possible to use Ranch to listen on a UNIX domain socket by specifying {local, SocketFile} for the ip socket option. In this case, the port must be set to 0 or omitted. The given file must not exist: Ranch must be able to create it.

Starting a listener for TCP connections on a UNIX Domain socket
-
@@ -193,7 +193,7 @@ http://www.gnu.org/software/src-highlite -->

Limiting the number of concurrent connections

The max_connections transport option allows you to limit the number of concurrent connections per connection supervisor (see below). It defaults to 1024. Its purpose is to prevent your system from being overloaded and ensuring all the connections are handled optimally.

Customizing the maximum number of concurrent connections
-
@@ -204,7 +204,7 @@ http://www.gnu.org/software/src-highlite -->

You can disable this limit by setting its value to the atom infinity.

Disabling the limit for the number of connections
-
@@ -218,16 +218,16 @@ http://www.gnu.org/software/src-highlite -->

You may not always want connections to be counted when checking for max_connections. For example you might have a protocol where both short-lived and long-lived connections are possible. If the long-lived connections are mostly waiting for messages, then they don't consume much resources and can safely be removed from the count.

To remove the connection from the count, you must call the ranch:remove_connection/1 from within the connection process, with the name of the listener as the only argument.

Removing a connection from the count of connections
-
ranch:remove_connection(Ref).
-

As seen in the chapter covering protocols, this pid is received as the first argument of the protocol's start_link/4 callback.

+

As seen in the chapter covering protocols, this reference is received as the first argument of the protocol's start_link/3 callback.

You can modify the max_connections value on a running listener by using the ranch:set_max_connections/2 function, with the name of the listener as first argument and the new value as the second.

Upgrading the maximum number of connections
-
@@ -238,7 +238,7 @@ http://www.gnu.org/software/src-highlite -->

By default Ranch will use 10 acceptor processes. Their role is to accept connections and spawn a connection process for every new connection.

This number can be tweaked to improve performance. A good number is typically between 10 or 100 acceptors. You must measure to find the best value for your application.

Specifying a custom number of acceptor processes
-
@@ -251,7 +251,7 @@ http://www.gnu.org/software/src-highlite -->

By default Ranch will use one connection supervisor for each acceptor process (but not vice versa). Their task is to supervise the connection processes started by an acceptor. The number of connection supervisors can be tweaked.

Note that the association between the individual acceptors and connection supervisors is fixed, meaning that acceptors will always use the same connection supervisor to start connection processes.

Specifying a custom number of connection supervisors
-
@@ -274,7 +274,7 @@ Ranch acceptor reducing accept rate: out of file descriptors

Ranch allows you to upgrade the protocol options. This takes effect immediately and for all subsequent connections.

To upgrade the protocol options, call ranch:set_protocol_options/2 with the name of the listener as first argument and the new options as the second.

Upgrading the protocol options
-
@@ -283,7 +283,7 @@ http://www.gnu.org/software/src-highlite -->

All future connections will use the new options.

You can also retrieve the current options similarly by calling ranch:get_protocol_options/1.

Retrieving the current protocol options
-
@@ -292,7 +292,7 @@ http://www.gnu.org/software/src-highlite -->

Changing transport options

Ranch allows you to change the transport options of a listener with the ranch:set_transport_options/2 function, for example to change the number of acceptors or to make it listen on a different port.

Changing the transport options
-
@@ -300,7 +300,7 @@ http://www.gnu.org/software/src-highlite -->

You can retrieve the current transport options by calling ranch:get_transport_options/1.

Retrieving the current transport options
-
@@ -310,7 +310,7 @@ http://www.gnu.org/software/src-highlite -->

Ranch provides two functions for retrieving information about the listeners, for reporting and diagnostic purposes.

The ranch:info/0 function will return detailed information about all listeners.

Retrieving detailed information
-
@@ -318,14 +318,14 @@ http://www.gnu.org/software/src-highlite -->

The ranch:procs/2 function will return all acceptor or listener processes for a given listener.

Get all acceptor processes
-
ranch:procs(tcp_echo, acceptors).
Get all connection processes
-
diff --git a/docs/en/ranch/2.0/guide/migrating_from_1.7.asciidoc b/docs/en/ranch/2.0/guide/migrating_from_1.7.asciidoc index f63c3467..92470aaa 100644 --- a/docs/en/ranch/2.0/guide/migrating_from_1.7.asciidoc +++ b/docs/en/ranch/2.0/guide/migrating_from_1.7.asciidoc @@ -42,6 +42,11 @@ for Erlang/OTP 19 and 20 has been removed. is now to just start Ranch normally when using embedded listeners. +* Two steps handshake is now supported. This allows + obtaining TLS extensions and updating options before + resuming the handshake. The handshake can also be + canceled. + === Experimental features added * The experimental `num_listen_sockets` option has been @@ -71,6 +76,13 @@ for Erlang/OTP 19 and 20 has been removed. * The `Socket` argument was removed from `Protocol:start_link/3`. The socket must now be obtained by calling `ranch:handshake/1,2`. +=== Added functions + +* The functions `ranch:handshake_continue/1,2` and + `ranch:handshake_cancel/1` can be used to perform + a two steps handshake. These functions may not be + supported by all transports. + === Changed functions * The `NumAcceptors` argument was removed from `ranch:start_listener/5` @@ -101,6 +113,9 @@ for Erlang/OTP 19 and 20 has been removed. === Bugs fixed +* Calling `ranch:remove_connection/1` will now resume a sleeping + acceptor process when applicable. + * Repeatedly calling `ranch:remove_connection/1` from a connection process would crash the respective connection supervisor. This has now been fixed. diff --git a/docs/en/ranch/2.0/guide/migrating_from_1.7/index.html b/docs/en/ranch/2.0/guide/migrating_from_1.7/index.html index c3875f16..822643db 100644 --- a/docs/en/ranch/2.0/guide/migrating_from_1.7/index.html +++ b/docs/en/ranch/2.0/guide/migrating_from_1.7/index.html @@ -78,6 +78,8 @@
  • Embedded listeners are now failing in a predictable manner when ranch_server goes down. It is no longer necessary to embed ranch_sup and the recommendation is now to just start Ranch normally when using embedded listeners.
    • +
  • Two steps handshake is now supported. This allows obtaining TLS extensions and updating options before resuming the handshake. The handshake can also be canceled. +

    • Experimental features added

    • The experimental num_listen_sockets option has been added. It allows opening more than one listening socket per listener. It can only be used alongside the Linux SO_REUSEPORT socket option or equivalent. It allows working around a bottleneck in the kernel and maximizes resource usage, leading to increased rates for accepting new connections. @@ -95,6 +97,10 @@
    • The Socket argument was removed from Protocol:start_link/3. The socket must now be obtained by calling ranch:handshake/1,2.
    +

    Added functions

    +
    • The functions ranch:handshake_continue/1,2 and ranch:handshake_cancel/1 can be used to perform a two steps handshake. These functions may not be supported by all transports. +
      • +

    Changed functions

    • The NumAcceptors argument was removed from ranch:start_listener/5 and ranch:child_spec/5 and moved to the transport options.
      • @@ -110,7 +116,9 @@

    Bugs fixed

    -
    • Repeatedly calling ranch:remove_connection/1 from a connection process would crash the respective connection supervisor. This has now been fixed. +
      • Calling ranch:remove_connection/1 will now resume a sleeping acceptor process when applicable. +
        • +
      • Repeatedly calling ranch:remove_connection/1 from a connection process would crash the respective connection supervisor. This has now been fixed.
      • When a connection process was failing to start, the socket was not closed and this lead to leaking sockets. This is now corrected.
        • diff --git a/docs/en/ranch/2.0/guide/parsers/index.html b/docs/en/ranch/2.0/guide/parsers/index.html index 95c0deec..3629ddbd 100644 --- a/docs/en/ranch/2.0/guide/parsers/index.html +++ b/docs/en/ranch/2.0/guide/parsers/index.html @@ -76,7 +76,7 @@

        Text protocols are generally line based. This means that we can't do anything with them until we receive the full line.

        A simple way to get a full line is to use binary:split/2,3.

        Using binary:split/2 to get a line of input
        -
        @@ -90,7 +90,7 @@ http://www.gnu.org/software/src-highlite -->

        In the above example, we can have two results. Either there was a line break in the buffer and we get it split into two parts, the line and the rest of the buffer; or there was no line break in the buffer and we need to get more data from the socket.

        Next, we need to parse the line. The simplest way is to again split, here on space. The difference is that we want to split on all spaces character, as we want to tokenize the whole string.

        Using binary:split/3 to split text
        -
        @@ -111,7 +111,7 @@ http://www.gnu.org/software/src-highlite -->

        Sometimes the size of the frame includes the first four bytes, sometimes not. Other times this size is encoded over two bytes. And even other times little-endian is used instead of big-endian.

        The general idea stays the same though.

        Using binary pattern matching to split frames
        -
        diff --git a/docs/en/ranch/2.0/guide/protocols.asciidoc b/docs/en/ranch/2.0/guide/protocols.asciidoc index 89360ef3..b455143e 100644 --- a/docs/en/ranch/2.0/guide/protocols.asciidoc +++ b/docs/en/ranch/2.0/guide/protocols.asciidoc @@ -6,7 +6,7 @@ protocol logic executed in this process. === Writing a protocol handler All protocol handlers must implement the `ranch_protocol` behavior -which defines a single callback, `start_link/4`. This callback is +which defines a single callback, `start_link/3`. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in diff --git a/docs/en/ranch/2.0/guide/protocols/index.html b/docs/en/ranch/2.0/guide/protocols/index.html index 0422912f..33d3093e 100644 --- a/docs/en/ranch/2.0/guide/protocols/index.html +++ b/docs/en/ranch/2.0/guide/protocols/index.html @@ -64,10 +64,10 @@

        A protocol handler starts a connection process and defines the protocol logic executed in this process.

        Writing a protocol handler

        -

        All protocol handlers must implement the ranch_protocol behavior which defines a single callback, start_link/4. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in the call to ranch:start_listener/5. This callback must return {ok, Pid}, with Pid the pid of the new process.

        +

        All protocol handlers must implement the ranch_protocol behavior which defines a single callback, start_link/3. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in the call to ranch:start_listener/5. This callback must return {ok, Pid}, with Pid the pid of the new process.

        The newly started process can then freely initialize itself. However, it must call ranch:handshake/1,2 before doing any socket operation. This will ensure the connection process is the owner of the socket. It expects the listener's name as argument.

        Perform the socket handshake
        -
        @@ -76,7 +76,7 @@ http://www.gnu.org/software/src-highlite -->

        If your protocol code requires specific socket options, you should set them while initializing your connection process, after calling ranch:handshake/1,2. You can use Transport:setopts/2 for that purpose.

        Following is the complete protocol code for the example found in examples/tcp_echo/.

        Protocol module that echoes everything it receives
        -
        @@ -107,7 +107,7 @@ http://www.gnu.org/software/src-highlite -->

        Special processes like the ones that use the gen_statem or gen_server behaviours have the particularity of having their start_link call not return until the init function returns. This is problematic, because you won't be able to call ranch:handshake/1,2 from the init callback as this would cause a deadlock to happen.

        Use the gen_statem:enter_loop/4 function. It allows you to start your process normally (although it must be started with proc_lib like all special processes), then perform any needed operations before falling back into the normal gen_statem execution loop.

        Use a gen_statem for protocol handling
        -
        diff --git a/docs/en/ranch/2.0/guide/ssl_auth/index.html b/docs/en/ranch/2.0/guide/ssl_auth/index.html index 575949b7..a24b53ea 100644 --- a/docs/en/ranch/2.0/guide/ssl_auth/index.html +++ b/docs/en/ranch/2.0/guide/ssl_auth/index.html @@ -90,7 +90,7 @@

        Transport configuration

        The SSL transport does not request a client certificate by default. You need to specify the {verify, verify_peer} option when starting the listener to enable this behavior.

        Configure a listener for SSL authentication
        -
        @@ -109,7 +109,7 @@ http://www.gnu.org/software/src-highlite -->

        Authentication

        To authenticate users, you must first save the certificate information required. If you have your users' certificate files, you can simply load the certificate and retrieve the information directly.

        Retrieve the issuer ID from a certificate
        -
        @@ -123,7 +123,7 @@ http://www.gnu.org/software/src-highlite -->

        To retrieve the IssuerID from a running connection, you need to first retrieve the client certificate and then extract this information from it. Ranch does not provide a function to retrieve the client certificate. Instead you can use the ssl:peercert/1 function. Once you have the certificate, you can again use the public_key:pkix_issuer_id/2 to extract the IssuerID value.

        The following function returns the IssuerID or false if no client certificate was found. This snippet is intended to be used from your protocol code.

        Retrieve the issuer ID from the certificate for the current connection
        -
        diff --git a/docs/en/ranch/2.0/guide/transports/index.html b/docs/en/ranch/2.0/guide/transports/index.html index c483b24f..8b1a14fd 100644 --- a/docs/en/ranch/2.0/guide/transports/index.html +++ b/docs/en/ranch/2.0/guide/transports/index.html @@ -74,7 +74,7 @@

        This section assumes that Transport is a valid transport handler (like ranch_tcp or ranch_ssl) and Socket is a connected socket obtained through the listener.

        You can send data to a socket by calling the Transport:send/2 function. The data can be given as iodata(), which is defined as binary() | iolist(). All the following calls will work:

        Sending data to the socket
        -
        @@ -88,7 +88,7 @@ http://www.gnu.org/software/src-highlite -->

        Receiving data using passive mode requires a single function call. The first argument is the socket, and the third argument is a timeout duration before the call returns with {error, timeout}.

        The second argument is the amount of data in bytes that we want to receive. The function will wait for data until it has received exactly this amount. If you are not expecting a precise size, you can specify 0 which will make this call return as soon as data was read, regardless of its size.

        Receiving data from the socket in passive mode
        -
        @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite -->

      The value of OK, Closed and Error can be different depending on the transport being used. To be able to properly match on them you must first call the Transport:messages/0 function.

      Retrieving the transport's active message identifiers
      -
      @@ -114,7 +114,7 @@ http://www.gnu.org/software/src-highlite -->

      To start receiving messages you will need to call the Transport:setopts/2 function, and do so every time you want to receive data.

      Receiving messages from the socket in active mode
      -
      @@ -134,7 +134,7 @@ http://www.gnu.org/software/src-highlite -->

      As in the previous section it is assumed Transport is a valid transport handler and Socket is a connected socket obtained through the listener.

      To send a whole file, with name Filename, over a socket:

      Sending a file by filename
      -
      @@ -142,7 +142,7 @@ http://www.gnu.org/software/src-highlite -->

      Or part of a file, with Offset greater than or equal to 0, Bytes number of bytes and chunks of size ChunkSize:

      Sending part of a file by filename in chunks
      -
      @@ -151,7 +151,7 @@ http://www.gnu.org/software/src-highlite -->

      To improve efficiency when sending multiple parts of the same file it is also possible to use a file descriptor opened in raw mode:

      Sending a file opened in raw mode
      -
      @@ -161,7 +161,7 @@ http://www.gnu.org/software/src-highlite -->

      Upgrading a TCP socket to SSL

      A connected TCP socket can be upgraded to a SSL socket via the function ranch_ssl:handshake/3. The socket must be in {active, false} mode before telling the client that the server is ready to upgrade in order to avoid race conditions.

      Performing a TLS handshake on a TCP socket
      -
      -- cgit v1.2.3