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 --- docs/en/ranch/1.4/guide/embedded/index.html | 2 +- docs/en/ranch/1.4/guide/internals/index.html | 2 +- docs/en/ranch/1.4/guide/listeners/index.html | 32 ++-- docs/en/ranch/1.4/guide/parsers/index.html | 6 +- docs/en/ranch/1.4/guide/protocols/index.html | 6 +- docs/en/ranch/1.4/guide/ssl_auth/index.html | 6 +- docs/en/ranch/1.4/guide/transports/index.html | 14 +- docs/en/ranch/1.4/manual/ranch/index.html | 2 +- docs/en/ranch/1.4/manual/ranch_ssl/index.html | 2 +- docs/en/ranch/1.4/manual/ranch_tcp/index.html | 2 +- docs/en/ranch/1.5/guide/embedded/index.html | 2 +- docs/en/ranch/1.5/guide/internals/index.html | 2 +- docs/en/ranch/1.5/guide/listeners/index.html | 32 ++-- docs/en/ranch/1.5/guide/parsers/index.html | 6 +- docs/en/ranch/1.5/guide/protocols/index.html | 6 +- docs/en/ranch/1.5/guide/ssl_auth/index.html | 6 +- docs/en/ranch/1.5/guide/transports/index.html | 14 +- docs/en/ranch/1.5/manual/ranch/index.html | 2 +- docs/en/ranch/1.5/manual/ranch_ssl/index.html | 2 +- docs/en/ranch/1.5/manual/ranch_tcp/index.html | 2 +- docs/en/ranch/1.6/guide/embedded/index.html | 2 +- docs/en/ranch/1.6/guide/internals/index.html | 2 +- docs/en/ranch/1.6/guide/listeners/index.html | 40 ++-- docs/en/ranch/1.6/guide/parsers/index.html | 6 +- docs/en/ranch/1.6/guide/protocols/index.html | 6 +- docs/en/ranch/1.6/guide/ssl_auth/index.html | 6 +- docs/en/ranch/1.6/guide/transports/index.html | 16 +- docs/en/ranch/1.6/manual/index.html | 2 +- .../ranch/1.6/manual/ranch.child_spec/index.html | 4 +- docs/en/ranch/1.6/manual/ranch.get_addr/index.html | 4 +- .../manual/ranch.get_max_connections/index.html | 4 +- docs/en/ranch/1.6/manual/ranch.get_port/index.html | 4 +- .../manual/ranch.get_protocol_options/index.html | 4 +- .../ranch/1.6/manual/ranch.get_status/index.html | 4 +- .../manual/ranch.get_transport_options/index.html | 4 +- .../en/ranch/1.6/manual/ranch.handshake/index.html | 4 +- docs/en/ranch/1.6/manual/ranch.info/index.html | 6 +- docs/en/ranch/1.6/manual/ranch.procs/index.html | 6 +- .../1.6/manual/ranch.remove_connection/index.html | 4 +- .../1.6/manual/ranch.resume_listener/index.html | 4 +- .../manual/ranch.set_max_connections/index.html | 4 +- .../manual/ranch.set_protocol_options/index.html | 4 +- .../manual/ranch.set_transport_options/index.html | 4 +- .../1.6/manual/ranch.start_listener/index.html | 8 +- .../1.6/manual/ranch.stop_listener/index.html | 4 +- .../1.6/manual/ranch.suspend_listener/index.html | 4 +- .../manual/ranch.wait_for_connections/index.html | 6 +- docs/en/ranch/1.6/manual/ranch/index.html | 8 +- docs/en/ranch/1.6/manual/ranch_app/index.html | 2 +- docs/en/ranch/1.6/manual/ranch_protocol/index.html | 2 +- docs/en/ranch/1.6/manual/ranch_ssl/index.html | 6 +- docs/en/ranch/1.6/manual/ranch_tcp/index.html | 4 +- .../1.6/manual/ranch_transport.sendfile/index.html | 4 +- .../en/ranch/1.6/manual/ranch_transport/index.html | 40 ++-- docs/en/ranch/1.7/guide/embedded/index.html | 2 +- docs/en/ranch/1.7/guide/internals/index.html | 2 +- docs/en/ranch/1.7/guide/listeners/index.html | 40 ++-- docs/en/ranch/1.7/guide/parsers/index.html | 6 +- docs/en/ranch/1.7/guide/protocols/index.html | 6 +- docs/en/ranch/1.7/guide/ssl_auth/index.html | 6 +- docs/en/ranch/1.7/guide/transports/index.html | 16 +- docs/en/ranch/1.7/manual/index.html | 2 +- .../ranch/1.7/manual/ranch.child_spec/index.html | 4 +- docs/en/ranch/1.7/manual/ranch.get_addr/index.html | 4 +- .../manual/ranch.get_max_connections/index.html | 4 +- docs/en/ranch/1.7/manual/ranch.get_port/index.html | 4 +- .../manual/ranch.get_protocol_options/index.html | 4 +- .../ranch/1.7/manual/ranch.get_status/index.html | 4 +- .../manual/ranch.get_transport_options/index.html | 4 +- .../en/ranch/1.7/manual/ranch.handshake/index.html | 4 +- docs/en/ranch/1.7/manual/ranch.info/index.html | 6 +- docs/en/ranch/1.7/manual/ranch.procs/index.html | 6 +- .../1.7/manual/ranch.recv_proxy_header/index.html | 4 +- .../1.7/manual/ranch.remove_connection/index.html | 4 +- .../1.7/manual/ranch.resume_listener/index.html | 4 +- .../manual/ranch.set_max_connections/index.html | 4 +- .../manual/ranch.set_protocol_options/index.html | 4 +- .../manual/ranch.set_transport_options/index.html | 4 +- .../1.7/manual/ranch.start_listener/index.html | 8 +- .../1.7/manual/ranch.stop_listener/index.html | 4 +- .../1.7/manual/ranch.suspend_listener/index.html | 4 +- .../manual/ranch.wait_for_connections/index.html | 6 +- docs/en/ranch/1.7/manual/ranch/index.html | 8 +- docs/en/ranch/1.7/manual/ranch_app/index.html | 2 +- docs/en/ranch/1.7/manual/ranch_protocol/index.html | 2 +- .../manual/ranch_proxy_header.header/index.html | 6 +- .../1.7/manual/ranch_proxy_header.parse/index.html | 4 +- .../ranch/1.7/manual/ranch_proxy_header/index.html | 2 +- docs/en/ranch/1.7/manual/ranch_ssl/index.html | 6 +- docs/en/ranch/1.7/manual/ranch_tcp/index.html | 4 +- .../1.7/manual/ranch_transport.sendfile/index.html | 4 +- .../en/ranch/1.7/manual/ranch_transport/index.html | 40 ++-- .../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 +- docs/en/ranch/2.0/manual/index.html | 2 +- .../ranch/2.0/manual/ranch.child_spec/index.html | 4 +- docs/en/ranch/2.0/manual/ranch.get_addr/index.html | 6 +- .../manual/ranch.get_max_connections/index.html | 4 +- docs/en/ranch/2.0/manual/ranch.get_port/index.html | 4 +- .../manual/ranch.get_protocol_options/index.html | 4 +- .../ranch/2.0/manual/ranch.get_status/index.html | 4 +- .../manual/ranch.get_transport_options/index.html | 4 +- .../en/ranch/2.0/manual/ranch.handshake/index.html | 22 ++- .../2.0/manual/ranch.handshake_cancel/index.html | 198 ++++++++++++++++++++ .../2.0/manual/ranch.handshake_continue/index.html | 208 +++++++++++++++++++++ docs/en/ranch/2.0/manual/ranch.info/index.html | 6 +- docs/en/ranch/2.0/manual/ranch.procs/index.html | 6 +- .../2.0/manual/ranch.recv_proxy_header/index.html | 6 +- .../2.0/manual/ranch.remove_connection/index.html | 4 +- .../2.0/manual/ranch.resume_listener/index.html | 4 +- .../manual/ranch.set_max_connections/index.html | 4 +- .../manual/ranch.set_protocol_options/index.html | 4 +- .../manual/ranch.set_transport_options/index.html | 4 +- .../2.0/manual/ranch.start_listener/index.html | 8 +- .../2.0/manual/ranch.stop_listener/index.html | 4 +- .../2.0/manual/ranch.suspend_listener/index.html | 4 +- .../manual/ranch.wait_for_connections/index.html | 6 +- docs/en/ranch/2.0/manual/ranch/index.html | 12 +- docs/en/ranch/2.0/manual/ranch_app/index.html | 2 +- docs/en/ranch/2.0/manual/ranch_protocol/index.html | 2 +- .../manual/ranch_proxy_header.header/index.html | 6 +- .../2.0/manual/ranch_proxy_header.parse/index.html | 4 +- .../ranch/2.0/manual/ranch_proxy_header/index.html | 2 +- docs/en/ranch/2.0/manual/ranch_ssl/index.html | 11 +- docs/en/ranch/2.0/manual/ranch_tcp/index.html | 4 +- .../2.0/manual/ranch_transport.sendfile/index.html | 4 +- .../en/ranch/2.0/manual/ranch_transport/index.html | 79 +++++--- 137 files changed, 938 insertions(+), 461 deletions(-) create mode 100644 docs/en/ranch/2.0/manual/ranch.handshake_cancel/index.html create mode 100644 docs/en/ranch/2.0/manual/ranch.handshake_continue/index.html (limited to 'docs/en/ranch') diff --git a/docs/en/ranch/1.4/guide/embedded/index.html b/docs/en/ranch/1.4/guide/embedded/index.html index b5898308..cf6a3c3b 100644 --- a/docs/en/ranch/1.4/guide/embedded/index.html +++ b/docs/en/ranch/1.4/guide/embedded/index.html @@ -70,7 +70,7 @@

As for ranch_sup, the child spec is simple enough to not require a convenience function.

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

Embed Ranch directly in your supervision tree
-
diff --git a/docs/en/ranch/1.4/guide/internals/index.html b/docs/en/ranch/1.4/guide/internals/index.html index b32cec50..17d9bd06 100644 --- a/docs/en/ranch/1.4/guide/internals/index.html +++ b/docs/en/ranch/1.4/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/1.4/guide/listeners/index.html b/docs/en/ranch/1.4/guide/listeners/index.html index e83d3a83..ef326582 100644 --- a/docs/en/ranch/1.4/guide/listeners/index.html +++ b/docs/en/ranch/1.4/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
-
@@ -140,7 +140,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
-
@@ -160,7 +160,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. 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
-
@@ -171,7 +171,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
-
@@ -185,7 +185,7 @@ 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
-
@@ -194,7 +194,7 @@ http://www.gnu.org/software/src-highlite -->

As seen in the chapter covering protocols, this pid is received as the first argument of the protocol's start_link/4 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
-
@@ -205,7 +205,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
-
@@ -228,7 +228,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
-
@@ -237,7 +237,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
-
@@ -247,7 +247,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
-
@@ -255,14 +255,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/1.4/guide/parsers/index.html b/docs/en/ranch/1.4/guide/parsers/index.html index dd0c494e..2ee0d2cf 100644 --- a/docs/en/ranch/1.4/guide/parsers/index.html +++ b/docs/en/ranch/1.4/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/1.4/guide/protocols/index.html b/docs/en/ranch/1.4/guide/protocols/index.html index 334ded82..8a326e0a 100644 --- a/docs/en/ranch/1.4/guide/protocols/index.html +++ b/docs/en/ranch/1.4/guide/protocols/index.html @@ -67,7 +67,7 @@

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.

The newly started process can then freely initialize itself. However, it must call ranch:accept_ack/1 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.

Acknowledge accepting the socket
-
@@ -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:accept_ack/1. 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_server or gen_fsm 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:accept_ack/1 from the init callback as this would cause a deadlock to happen.

Use the gen_server:enter_loop/3 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_server execution loop.

Use a gen_server for protocol handling
-
diff --git a/docs/en/ranch/1.4/guide/ssl_auth/index.html b/docs/en/ranch/1.4/guide/ssl_auth/index.html index 85364c3b..8098acfc 100644 --- a/docs/en/ranch/1.4/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.4/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/1.4/guide/transports/index.html b/docs/en/ranch/1.4/guide/transports/index.html index 38913468..cb4937b9 100644 --- a/docs/en/ranch/1.4/guide/transports/index.html +++ b/docs/en/ranch/1.4/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
-
diff --git a/docs/en/ranch/1.4/manual/ranch/index.html b/docs/en/ranch/1.4/manual/ranch/index.html index 504986af..a41d0d18 100644 --- a/docs/en/ranch/1.4/manual/ranch/index.html +++ b/docs/en/ranch/1.4/manual/ranch/index.html @@ -71,7 +71,7 @@

Maximum number of connections allowed on this listener.

This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.

opt()

-
diff --git a/docs/en/ranch/1.4/manual/ranch_ssl/index.html b/docs/en/ranch/1.4/manual/ranch_ssl/index.html index 0321329b..78da233d 100644 --- a/docs/en/ranch/1.4/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.4/manual/ranch_ssl/index.html @@ -68,7 +68,7 @@

The ranch_ssl module implements an SSL Ranch transport.

Types

ssl_opt()

-
diff --git a/docs/en/ranch/1.4/manual/ranch_tcp/index.html b/docs/en/ranch/1.4/manual/ranch_tcp/index.html index aeadec0f..1d6e1471 100644 --- a/docs/en/ranch/1.4/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.4/manual/ranch_tcp/index.html @@ -69,7 +69,7 @@

Note that due to bugs in OTP up to at least R16B02, it is recommended to disable async threads when using the sendfile function of this transport, as it can make the threads stuck indefinitely.

Types

opt()

-
diff --git a/docs/en/ranch/1.5/guide/embedded/index.html b/docs/en/ranch/1.5/guide/embedded/index.html index 8b1bea1e..e5345218 100644 --- a/docs/en/ranch/1.5/guide/embedded/index.html +++ b/docs/en/ranch/1.5/guide/embedded/index.html @@ -70,7 +70,7 @@

As for ranch_sup, the child spec is simple enough to not require a convenience function.

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

Embed Ranch directly in your supervision tree
-
diff --git a/docs/en/ranch/1.5/guide/internals/index.html b/docs/en/ranch/1.5/guide/internals/index.html index 518ade76..d2053e6d 100644 --- a/docs/en/ranch/1.5/guide/internals/index.html +++ b/docs/en/ranch/1.5/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/1.5/guide/listeners/index.html b/docs/en/ranch/1.5/guide/listeners/index.html index 9348d735..b656d8f7 100644 --- a/docs/en/ranch/1.5/guide/listeners/index.html +++ b/docs/en/ranch/1.5/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
-
@@ -140,7 +140,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
-
@@ -160,7 +160,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. 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
-
@@ -171,7 +171,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
-
@@ -185,7 +185,7 @@ 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
-
@@ -194,7 +194,7 @@ http://www.gnu.org/software/src-highlite -->

As seen in the chapter covering protocols, this pid is received as the first argument of the protocol's start_link/4 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
-
@@ -205,7 +205,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
-
@@ -228,7 +228,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
-
@@ -237,7 +237,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
-
@@ -247,7 +247,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
-
@@ -255,14 +255,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/1.5/guide/parsers/index.html b/docs/en/ranch/1.5/guide/parsers/index.html index 3ab7d9b3..b5d2ddcf 100644 --- a/docs/en/ranch/1.5/guide/parsers/index.html +++ b/docs/en/ranch/1.5/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/1.5/guide/protocols/index.html b/docs/en/ranch/1.5/guide/protocols/index.html index a0d11047..124feaa0 100644 --- a/docs/en/ranch/1.5/guide/protocols/index.html +++ b/docs/en/ranch/1.5/guide/protocols/index.html @@ -67,7 +67,7 @@

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.

The newly started process can then freely initialize itself. However, it must call ranch:accept_ack/1 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.

Acknowledge accepting the socket
-
@@ -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:accept_ack/1. 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_server or gen_fsm 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:accept_ack/1 from the init callback as this would cause a deadlock to happen.

Use the gen_server:enter_loop/3 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_server execution loop.

Use a gen_server for protocol handling
-
diff --git a/docs/en/ranch/1.5/guide/ssl_auth/index.html b/docs/en/ranch/1.5/guide/ssl_auth/index.html index 7156d7fb..de300619 100644 --- a/docs/en/ranch/1.5/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.5/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/1.5/guide/transports/index.html b/docs/en/ranch/1.5/guide/transports/index.html index 651a814f..7542918b 100644 --- a/docs/en/ranch/1.5/guide/transports/index.html +++ b/docs/en/ranch/1.5/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
-
diff --git a/docs/en/ranch/1.5/manual/ranch/index.html b/docs/en/ranch/1.5/manual/ranch/index.html index a7d2b4da..a6a40239 100644 --- a/docs/en/ranch/1.5/manual/ranch/index.html +++ b/docs/en/ranch/1.5/manual/ranch/index.html @@ -71,7 +71,7 @@

Maximum number of connections allowed on this listener.

This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.

opt()

-
diff --git a/docs/en/ranch/1.5/manual/ranch_ssl/index.html b/docs/en/ranch/1.5/manual/ranch_ssl/index.html index 905dc0ca..3a394cf0 100644 --- a/docs/en/ranch/1.5/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.5/manual/ranch_ssl/index.html @@ -68,7 +68,7 @@

The ranch_ssl module implements an SSL Ranch transport.

Types

ssl_opt()

-
diff --git a/docs/en/ranch/1.5/manual/ranch_tcp/index.html b/docs/en/ranch/1.5/manual/ranch_tcp/index.html index b33dc42e..06c62941 100644 --- a/docs/en/ranch/1.5/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.5/manual/ranch_tcp/index.html @@ -69,7 +69,7 @@

Note that due to bugs in OTP up to at least R16B02, it is recommended to disable async threads when using the sendfile function of this transport, as it can make the threads stuck indefinitely.

Types

opt()

-
diff --git a/docs/en/ranch/1.6/guide/embedded/index.html b/docs/en/ranch/1.6/guide/embedded/index.html index d16d7a15..37b45e4b 100644 --- a/docs/en/ranch/1.6/guide/embedded/index.html +++ b/docs/en/ranch/1.6/guide/embedded/index.html @@ -70,7 +70,7 @@

As for ranch_sup, the child spec is simple enough to not require a convenience function.

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

Embed Ranch directly in your supervision tree
-
diff --git a/docs/en/ranch/1.6/guide/internals/index.html b/docs/en/ranch/1.6/guide/internals/index.html index a6ab295c..2ed24798 100644 --- a/docs/en/ranch/1.6/guide/internals/index.html +++ b/docs/en/ranch/1.6/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/1.6/guide/listeners/index.html b/docs/en/ranch/1.6/guide/listeners/index.html index 3a5bba45..5cde8f8f 100644 --- a/docs/en/ranch/1.6/guide/listeners/index.html +++ b/docs/en/ranch/1.6/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
-
@@ -178,7 +178,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. 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
-
@@ -189,7 +189,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
-
@@ -203,7 +203,7 @@ 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
-
@@ -212,7 +212,7 @@ http://www.gnu.org/software/src-highlite -->

As seen in the chapter covering protocols, this pid is received as the first argument of the protocol's start_link/4 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
-
@@ -223,7 +223,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
-
@@ -246,7 +246,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
-
@@ -255,7 +255,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
-
@@ -265,7 +265,7 @@ http://www.gnu.org/software/src-highlite -->

Ranch allows you to change the transport options of a listener, for example to make it listen on a different port.

To change transport options, the listener has to be suspended first. Then you are allowed to change the transport options by calling ranch:set_transport_options/2 with the listener name and the new transport options as arguments. After that, you can resume the listener.

Changing the transport options
-
@@ -273,7 +273,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
-
@@ -283,7 +283,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
-
@@ -291,14 +291,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/1.6/guide/parsers/index.html b/docs/en/ranch/1.6/guide/parsers/index.html index f5c5f8ee..b7b96715 100644 --- a/docs/en/ranch/1.6/guide/parsers/index.html +++ b/docs/en/ranch/1.6/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/1.6/guide/protocols/index.html b/docs/en/ranch/1.6/guide/protocols/index.html index f002909d..97b47dc2 100644 --- a/docs/en/ranch/1.6/guide/protocols/index.html +++ b/docs/en/ranch/1.6/guide/protocols/index.html @@ -67,7 +67,7 @@

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.

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/1.6/guide/ssl_auth/index.html b/docs/en/ranch/1.6/guide/ssl_auth/index.html index 9c4208ea..7c5e2aec 100644 --- a/docs/en/ranch/1.6/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.6/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/1.6/guide/transports/index.html b/docs/en/ranch/1.6/guide/transports/index.html index 8cdf4217..5aa88de5 100644 --- a/docs/en/ranch/1.6/guide/transports/index.html +++ b/docs/en/ranch/1.6/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
-
diff --git a/docs/en/ranch/1.6/manual/index.html b/docs/en/ranch/1.6/manual/index.html index c0ffae17..0d82e78e 100644 --- a/docs/en/ranch/1.6/manual/index.html +++ b/docs/en/ranch/1.6/manual/index.html @@ -89,7 +89,7 @@

All these applications must be started before the ranch application. To start Ranch and all dependencies at once:

-
diff --git a/docs/en/ranch/1.6/manual/ranch.child_spec/index.html b/docs/en/ranch/1.6/manual/ranch.child_spec/index.html index 009b863a..dcaee508 100644 --- a/docs/en/ranch/1.6/manual/ranch.child_spec/index.html +++ b/docs/en/ranch/1.6/manual/ranch.child_spec/index.html @@ -65,7 +65,7 @@

Name

ranch:child_spec - Build child specifications for a new listener

Description

-
@@ -108,7 +108,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Embed a listener
-
diff --git a/docs/en/ranch/1.6/manual/ranch.get_addr/index.html b/docs/en/ranch/1.6/manual/ranch.get_addr/index.html index a916ff19..ce4c27b1 100644 --- a/docs/en/ranch/1.6/manual/ranch.get_addr/index.html +++ b/docs/en/ranch/1.6/manual/ranch.get_addr/index.html @@ -65,7 +65,7 @@

Name

ranch:get_addr - Get the listening port and IP

Description

-
@@ -84,7 +84,7 @@ http://www.gnu.org/software/src-highlite -->

The IP address is the IP of the network interface the socket is bound to.

Examples

Get the listening port and IP
-
diff --git a/docs/en/ranch/1.6/manual/ranch.get_max_connections/index.html b/docs/en/ranch/1.6/manual/ranch.get_max_connections/index.html index d9f60f1e..56ad924c 100644 --- a/docs/en/ranch/1.6/manual/ranch.get_max_connections/index.html +++ b/docs/en/ranch/1.6/manual/ranch.get_max_connections/index.html @@ -65,7 +65,7 @@

Name

ranch:get_max_connections - Get the max number of connections

Description

-
@@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

The maximum number of connections is returned.

Examples

Get the max number of connections
-
diff --git a/docs/en/ranch/1.6/manual/ranch.get_port/index.html b/docs/en/ranch/1.6/manual/ranch.get_port/index.html index 854d4047..2b820d96 100644 --- a/docs/en/ranch/1.6/manual/ranch.get_port/index.html +++ b/docs/en/ranch/1.6/manual/ranch.get_port/index.html @@ -65,7 +65,7 @@

Name

ranch:get_port - Get the listening port

Description

-
@@ -83,7 +83,7 @@ http://www.gnu.org/software/src-highlite -->

The listening port is returned.

Examples

Get the listening port
-
diff --git a/docs/en/ranch/1.6/manual/ranch.get_protocol_options/index.html b/docs/en/ranch/1.6/manual/ranch.get_protocol_options/index.html index 53dae5f1..0bdf9e28 100644 --- a/docs/en/ranch/1.6/manual/ranch.get_protocol_options/index.html +++ b/docs/en/ranch/1.6/manual/ranch.get_protocol_options/index.html @@ -65,7 +65,7 @@

Name

ranch:get_protocol_options - Get the current protocol options

Description

-
@@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

The current protocol options are returned.

Examples

Get the current protocol options
-
diff --git a/docs/en/ranch/1.6/manual/ranch.get_status/index.html b/docs/en/ranch/1.6/manual/ranch.get_status/index.html index b574ad68..76d528e2 100644 --- a/docs/en/ranch/1.6/manual/ranch.get_status/index.html +++ b/docs/en/ranch/1.6/manual/ranch.get_status/index.html @@ -65,7 +65,7 @@

Name

ranch:get_status - Get a listener's running state

Description

-
@@ -85,7 +85,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Get a listener's running state
-
diff --git a/docs/en/ranch/1.6/manual/ranch.get_transport_options/index.html b/docs/en/ranch/1.6/manual/ranch.get_transport_options/index.html index 1636a606..3bff73a2 100644 --- a/docs/en/ranch/1.6/manual/ranch.get_transport_options/index.html +++ b/docs/en/ranch/1.6/manual/ranch.get_transport_options/index.html @@ -65,7 +65,7 @@

Name

ranch:get_transport_options - Get the current transport options

Description

-
@@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

The current transport options are returned.

Examples

Get the current transport options
-
diff --git a/docs/en/ranch/1.6/manual/ranch.handshake/index.html b/docs/en/ranch/1.6/manual/ranch.handshake/index.html index 2df2cd9c..9c58fd51 100644 --- a/docs/en/ranch/1.6/manual/ranch.handshake/index.html +++ b/docs/en/ranch/1.6/manual/ranch.handshake/index.html @@ -65,7 +65,7 @@

Name

ranch:handshake - Perform the transport handshake

Description

-
@@ -97,7 +97,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Initialize the connection process
-
diff --git a/docs/en/ranch/1.6/manual/ranch.info/index.html b/docs/en/ranch/1.6/manual/ranch.info/index.html index 4649e058..ee44d1d8 100644 --- a/docs/en/ranch/1.6/manual/ranch.info/index.html +++ b/docs/en/ranch/1.6/manual/ranch.info/index.html @@ -65,7 +65,7 @@

Name

ranch:info - Overview of Ranch listeners

Description

-
@@ -123,14 +123,14 @@ http://www.gnu.org/software/src-highlite -->

Examples

Get information about all listeners
-
AllInfo = ranch:info().
Get information about a specific listener
-
diff --git a/docs/en/ranch/1.6/manual/ranch.procs/index.html b/docs/en/ranch/1.6/manual/ranch.procs/index.html index 7a6a25a6..48f343f7 100644 --- a/docs/en/ranch/1.6/manual/ranch.procs/index.html +++ b/docs/en/ranch/1.6/manual/ranch.procs/index.html @@ -65,7 +65,7 @@

Name

ranch:procs - Retrieve pids from a listener

Description

-
@@ -86,14 +86,14 @@ http://www.gnu.org/software/src-highlite -->

A list of pids is returned.

Examples

Get the pids of the acceptor processes
-
Pids = ranch:procs(acceptors).
Get the pids of the connection processes
-
diff --git a/docs/en/ranch/1.6/manual/ranch.remove_connection/index.html b/docs/en/ranch/1.6/manual/ranch.remove_connection/index.html index ca7b5151..80e0d603 100644 --- a/docs/en/ranch/1.6/manual/ranch.remove_connection/index.html +++ b/docs/en/ranch/1.6/manual/ranch.remove_connection/index.html @@ -65,7 +65,7 @@

Name

ranch:remove_connection - Remove connection from the count

Description

-
@@ -83,7 +83,7 @@ http://www.gnu.org/software/src-highlite -->

The atom ok is always returned. It can be safely ignored.

Examples

Remove the connection process from the count
-
diff --git a/docs/en/ranch/1.6/manual/ranch.resume_listener/index.html b/docs/en/ranch/1.6/manual/ranch.resume_listener/index.html index 73a35d69..41e1712d 100644 --- a/docs/en/ranch/1.6/manual/ranch.resume_listener/index.html +++ b/docs/en/ranch/1.6/manual/ranch.resume_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:resume_listener - Resume a suspended listener

Description

-
@@ -89,7 +89,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Resume a listener
-
diff --git a/docs/en/ranch/1.6/manual/ranch.set_max_connections/index.html b/docs/en/ranch/1.6/manual/ranch.set_max_connections/index.html index c45c3d87..b8e41cf5 100644 --- a/docs/en/ranch/1.6/manual/ranch.set_max_connections/index.html +++ b/docs/en/ranch/1.6/manual/ranch.set_max_connections/index.html @@ -65,7 +65,7 @@

Name

ranch:set_max_connections - Set the max number of connections

Description

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

The atom ok is always returned. It can be safely ignored.

Examples

Set the max number of connections
-
diff --git a/docs/en/ranch/1.6/manual/ranch.set_protocol_options/index.html b/docs/en/ranch/1.6/manual/ranch.set_protocol_options/index.html index abe43fa4..17d8e29c 100644 --- a/docs/en/ranch/1.6/manual/ranch.set_protocol_options/index.html +++ b/docs/en/ranch/1.6/manual/ranch.set_protocol_options/index.html @@ -65,7 +65,7 @@

Name

ranch:set_protocol_options - Set the protocol options

Description

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

The atom ok is always returned. It can be safely ignored.

Examples

Set the protocol options
-
diff --git a/docs/en/ranch/1.6/manual/ranch.set_transport_options/index.html b/docs/en/ranch/1.6/manual/ranch.set_transport_options/index.html index 2993d22b..50f579e8 100644 --- a/docs/en/ranch/1.6/manual/ranch.set_transport_options/index.html +++ b/docs/en/ranch/1.6/manual/ranch.set_transport_options/index.html @@ -65,7 +65,7 @@

Name

ranch:set_transport_options - Set the transport options

Description

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

The atom ok is always returned. It can be safely ignored.

Examples

Set the transport options
-
diff --git a/docs/en/ranch/1.6/manual/ranch.start_listener/index.html b/docs/en/ranch/1.6/manual/ranch.start_listener/index.html index bacd4518..621f99b8 100644 --- a/docs/en/ranch/1.6/manual/ranch.start_listener/index.html +++ b/docs/en/ranch/1.6/manual/ranch.start_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:start_listener - Start a listener

Description

-
@@ -111,7 +111,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Start a listener
-
@@ -121,7 +121,7 @@ http://www.gnu.org/software/src-highlite --> ).
Start a listener with Ranch-specific options
-
@@ -134,7 +134,7 @@ http://www.gnu.org/software/src-highlite --> ).
Start a listener on a random port
-
diff --git a/docs/en/ranch/1.6/manual/ranch.stop_listener/index.html b/docs/en/ranch/1.6/manual/ranch.stop_listener/index.html index 5445c788..cef0e4f0 100644 --- a/docs/en/ranch/1.6/manual/ranch.stop_listener/index.html +++ b/docs/en/ranch/1.6/manual/ranch.stop_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:stop_listener - Stop a listener

Description

-
@@ -86,7 +86,7 @@ http://www.gnu.org/software/src-highlite -->

An error tuple is returned when the listener is not found.

Examples

Stop a listener
-
diff --git a/docs/en/ranch/1.6/manual/ranch.suspend_listener/index.html b/docs/en/ranch/1.6/manual/ranch.suspend_listener/index.html index d390e417..54ceb0c1 100644 --- a/docs/en/ranch/1.6/manual/ranch.suspend_listener/index.html +++ b/docs/en/ranch/1.6/manual/ranch.suspend_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:suspend_listener - Suspend a running listener

Description

-
@@ -90,7 +90,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Suspend a listener
-
diff --git a/docs/en/ranch/1.6/manual/ranch.wait_for_connections/index.html b/docs/en/ranch/1.6/manual/ranch.wait_for_connections/index.html index 69bf5ac8..b41f5695 100644 --- a/docs/en/ranch/1.6/manual/ranch.wait_for_connections/index.html +++ b/docs/en/ranch/1.6/manual/ranch.wait_for_connections/index.html @@ -65,7 +65,7 @@

Name

ranch:wait_for_connections - Wait for a specific number of connections

Description

-
@@ -99,14 +99,14 @@ http://www.gnu.org/software/src-highlite -->

Examples

Wait for at least 100 connections
-
ranch:wait_for_connections(example, '>=', 100).
Gracefully shutdown a listener
-
diff --git a/docs/en/ranch/1.6/manual/ranch/index.html b/docs/en/ranch/1.6/manual/ranch/index.html index e05d4dcb..566cbd31 100644 --- a/docs/en/ranch/1.6/manual/ranch/index.html +++ b/docs/en/ranch/1.6/manual/ranch/index.html @@ -119,7 +119,7 @@

Types

max_conns()

-
@@ -128,7 +128,7 @@ http://www.gnu.org/software/src-highlite -->

Maximum number of connections allowed on this listener.

This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.

opt()

-
@@ -142,7 +142,7 @@ http://www.gnu.org/software/src-highlite -->

Deprecated form for Ranch-specific options.

Please use the opts() type when you need to provide Ranch-specific transport options. Socket options will remain separate from the Ranch-specific options.

opts()

-
@@ -186,7 +186,7 @@ http://www.gnu.org/software/src-highlite -->

ref()

-
diff --git a/docs/en/ranch/1.6/manual/ranch_app/index.html b/docs/en/ranch/1.6/manual/ranch_app/index.html index fa0fbbab..ca419503 100644 --- a/docs/en/ranch/1.6/manual/ranch_app/index.html +++ b/docs/en/ranch/1.6/manual/ranch_app/index.html @@ -89,7 +89,7 @@

All these applications must be started before the ranch application. To start Ranch and all dependencies at once:

-
diff --git a/docs/en/ranch/1.6/manual/ranch_protocol/index.html b/docs/en/ranch/1.6/manual/ranch_protocol/index.html index 5351ee5c..f676182e 100644 --- a/docs/en/ranch/1.6/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.6/manual/ranch_protocol/index.html @@ -68,7 +68,7 @@

The module ranch_protocol defines the interface used by Ranch protocols.

Callbacks

Ranch protocols implement the following interface:

-
diff --git a/docs/en/ranch/1.6/manual/ranch_ssl/index.html b/docs/en/ranch/1.6/manual/ranch_ssl/index.html index 0ecca4f7..05d3af7d 100644 --- a/docs/en/ranch/1.6/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.6/manual/ranch_ssl/index.html @@ -70,7 +70,7 @@

The module ranch_ssl implements the interface defined by ranch_transport(3).

Types

opt()

-
@@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite -->

Listen options.

The TCP options are defined in ranch_tcp(3).

opts()

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

List of listen options.

ssl_opt()

-
diff --git a/docs/en/ranch/1.6/manual/ranch_tcp/index.html b/docs/en/ranch/1.6/manual/ranch_tcp/index.html index 605d27a7..0b9b9fc5 100644 --- a/docs/en/ranch/1.6/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.6/manual/ranch_tcp/index.html @@ -71,7 +71,7 @@

The module ranch_tcp implements the interface defined by ranch_transport(3).

Types

opt()

-
@@ -180,7 +180,7 @@ http://www.gnu.org/software/src-highlite -->

In addition, the raw option can be used to set system-specific options by specifying the protocol level, the option number and the actual option value specified as a binary. This option is not portable. Use with caution.

opts()

-
diff --git a/docs/en/ranch/1.6/manual/ranch_transport.sendfile/index.html b/docs/en/ranch/1.6/manual/ranch_transport.sendfile/index.html index fbdf5a80..d8151896 100644 --- a/docs/en/ranch/1.6/manual/ranch_transport.sendfile/index.html +++ b/docs/en/ranch/1.6/manual/ranch_transport.sendfile/index.html @@ -65,7 +65,7 @@

Name

ranch_transport:sendfile - Send a file on the socket

Description

-
@@ -109,7 +109,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Implement Transport:sendfile using the fallback
-
diff --git a/docs/en/ranch/1.6/manual/ranch_transport/index.html b/docs/en/ranch/1.6/manual/ranch_transport/index.html index 6e108243..493849df 100644 --- a/docs/en/ranch/1.6/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.6/manual/ranch_transport/index.html @@ -69,7 +69,7 @@

Callbacks

Ranch transports implement the following interface:

accept

-
@@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite -->

Use the listening socket returned by listen/1 to accept a new connection. The timeout is specified in milliseconds.

close

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

Close the socket.

controlling_process

-
@@ -96,7 +96,7 @@ http://www.gnu.org/software/src-highlite -->

Assign a new controlling process to the socket. The controlling process is the process that is linked to and receives messages from the socket.

getopts

-
@@ -105,7 +105,7 @@ http://www.gnu.org/software/src-highlite -->

Get one or more options for the socket.

getstat

-
@@ -113,7 +113,7 @@ http://www.gnu.org/software/src-highlite --> -> {ok, SockStatValues :: any()} | {error, atom()}

Get all statistics for the socket.

-
@@ -122,7 +122,7 @@ http://www.gnu.org/software/src-highlite -->

Get one or more statistic options for the socket.

handshake

-
@@ -135,7 +135,7 @@ http://www.gnu.org/software/src-highlite -->

This function will be called by connection processes before performing any socket operation. It allows transports that require extra initialization to perform their task and return a socket that is ready to use.

This function may also be used to upgrade a connection from a transport to another depending on the capabilities of the transports. For example a ranch_tcp socket may be upgraded to a ranch_ssl one using this function.

listen

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

Create a socket that listens on the given port.

The port may not be specified or may be set to 0, which means a random available port number will be chosen.

messages

-
@@ -156,7 +156,7 @@ http://www.gnu.org/software/src-highlite -->

Return the tuple keys for the messages sent by the socket.

name

-
@@ -164,7 +164,7 @@ http://www.gnu.org/software/src-highlite -->

Return the name of the transport.

peername

-
@@ -174,7 +174,7 @@ http://www.gnu.org/software/src-highlite -->

Return the address and port number for the other end of the connection.

recv

-
@@ -189,7 +189,7 @@ http://www.gnu.org/software/src-highlite -->

A length of 0 will return the data available on the socket as soon as possible, regardless of length.

While it is possible to use the timeout value infinity, it is highly discouraged as it could cause your process to get stuck waiting for data that will never come. This may happen when a socket becomes half-open due to a crash of the remote endpoint. Wi-Fi going down is another common culprit.

secure

-
@@ -197,7 +197,7 @@ http://www.gnu.org/software/src-highlite -->

Return whether the transport can be used for secure connections.

send

-
@@ -206,7 +206,7 @@ http://www.gnu.org/software/src-highlite -->

Send a packet on the socket.

sendfile

-
@@ -227,7 +227,7 @@ http://www.gnu.org/software/src-highlite -->

The file may be sent full or in parts, and may be specified by its filename or by an already open file descriptor.

Transports that manipulate TCP directly may use the file:sendfile/2,4,5 function, which calls the sendfile syscall where applicable (on Linux, for example). Other transports can use the sendfile/6 function exported from this module.

setopts

-
@@ -236,7 +236,7 @@ http://www.gnu.org/software/src-highlite -->

Set one or more options for the socket.

shutdown

-
@@ -246,7 +246,7 @@ http://www.gnu.org/software/src-highlite -->

Close the socket for reading and/or writing.

sockname

-
@@ -262,7 +262,7 @@ http://www.gnu.org/software/src-highlite -->

Types

sendfile_opts()

-
@@ -274,7 +274,7 @@ http://www.gnu.org/software/src-highlite -->

socket()

-
diff --git a/docs/en/ranch/1.7/guide/embedded/index.html b/docs/en/ranch/1.7/guide/embedded/index.html index 22791d31..918de887 100644 --- a/docs/en/ranch/1.7/guide/embedded/index.html +++ b/docs/en/ranch/1.7/guide/embedded/index.html @@ -70,7 +70,7 @@

As for ranch_sup, the child spec is simple enough to not require a convenience function.

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

Embed Ranch directly in your supervision tree
-
diff --git a/docs/en/ranch/1.7/guide/internals/index.html b/docs/en/ranch/1.7/guide/internals/index.html index 41f4403a..c69eef95 100644 --- a/docs/en/ranch/1.7/guide/internals/index.html +++ b/docs/en/ranch/1.7/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/1.7/guide/listeners/index.html b/docs/en/ranch/1.7/guide/listeners/index.html index 584ec224..5c64e2c7 100644 --- a/docs/en/ranch/1.7/guide/listeners/index.html +++ b/docs/en/ranch/1.7/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
-
@@ -178,7 +178,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. 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
-
@@ -189,7 +189,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
-
@@ -203,7 +203,7 @@ 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
-
@@ -212,7 +212,7 @@ http://www.gnu.org/software/src-highlite -->

As seen in the chapter covering protocols, this pid is received as the first argument of the protocol's start_link/4 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
-
@@ -223,7 +223,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
-
@@ -246,7 +246,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
-
@@ -255,7 +255,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
-
@@ -265,7 +265,7 @@ http://www.gnu.org/software/src-highlite -->

Ranch allows you to change the transport options of a listener, for example to make it listen on a different port.

To change transport options, the listener has to be suspended first. Then you are allowed to change the transport options by calling ranch:set_transport_options/2 with the listener name and the new transport options as arguments. After that, you can resume the listener.

Changing the transport options
-
@@ -273,7 +273,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
-
@@ -283,7 +283,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
-
@@ -291,14 +291,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/1.7/guide/parsers/index.html b/docs/en/ranch/1.7/guide/parsers/index.html index 0eb94a03..bb2f8e0e 100644 --- a/docs/en/ranch/1.7/guide/parsers/index.html +++ b/docs/en/ranch/1.7/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/1.7/guide/protocols/index.html b/docs/en/ranch/1.7/guide/protocols/index.html index dd1b8bb3..5828dd93 100644 --- a/docs/en/ranch/1.7/guide/protocols/index.html +++ b/docs/en/ranch/1.7/guide/protocols/index.html @@ -67,7 +67,7 @@

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.

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/1.7/guide/ssl_auth/index.html b/docs/en/ranch/1.7/guide/ssl_auth/index.html index 20e35715..ce1891bc 100644 --- a/docs/en/ranch/1.7/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.7/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/1.7/guide/transports/index.html b/docs/en/ranch/1.7/guide/transports/index.html index f7af0741..f3c97489 100644 --- a/docs/en/ranch/1.7/guide/transports/index.html +++ b/docs/en/ranch/1.7/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
-
diff --git a/docs/en/ranch/1.7/manual/index.html b/docs/en/ranch/1.7/manual/index.html index c1069688..17b6a287 100644 --- a/docs/en/ranch/1.7/manual/index.html +++ b/docs/en/ranch/1.7/manual/index.html @@ -91,7 +91,7 @@

All these applications must be started before the ranch application. To start Ranch and all dependencies at once:

-
diff --git a/docs/en/ranch/1.7/manual/ranch.child_spec/index.html b/docs/en/ranch/1.7/manual/ranch.child_spec/index.html index 78a31698..42ef604a 100644 --- a/docs/en/ranch/1.7/manual/ranch.child_spec/index.html +++ b/docs/en/ranch/1.7/manual/ranch.child_spec/index.html @@ -65,7 +65,7 @@

Name

ranch:child_spec - Build child specifications for a new listener

Description

-
@@ -108,7 +108,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Embed a listener
-
diff --git a/docs/en/ranch/1.7/manual/ranch.get_addr/index.html b/docs/en/ranch/1.7/manual/ranch.get_addr/index.html index 3f752903..a8ed1dd6 100644 --- a/docs/en/ranch/1.7/manual/ranch.get_addr/index.html +++ b/docs/en/ranch/1.7/manual/ranch.get_addr/index.html @@ -65,7 +65,7 @@

Name

ranch:get_addr - Get the listening port and IP

Description

-
@@ -84,7 +84,7 @@ http://www.gnu.org/software/src-highlite -->

The IP address is the IP of the network interface the socket is bound to.

Examples

Get the listening port and IP
-
diff --git a/docs/en/ranch/1.7/manual/ranch.get_max_connections/index.html b/docs/en/ranch/1.7/manual/ranch.get_max_connections/index.html index 45905c48..51ba800d 100644 --- a/docs/en/ranch/1.7/manual/ranch.get_max_connections/index.html +++ b/docs/en/ranch/1.7/manual/ranch.get_max_connections/index.html @@ -65,7 +65,7 @@

Name

ranch:get_max_connections - Get the max number of connections

Description

-
@@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

The maximum number of connections is returned.

Examples

Get the max number of connections
-
diff --git a/docs/en/ranch/1.7/manual/ranch.get_port/index.html b/docs/en/ranch/1.7/manual/ranch.get_port/index.html index b826aeb3..d9076ffd 100644 --- a/docs/en/ranch/1.7/manual/ranch.get_port/index.html +++ b/docs/en/ranch/1.7/manual/ranch.get_port/index.html @@ -65,7 +65,7 @@

Name

ranch:get_port - Get the listening port

Description

-
@@ -83,7 +83,7 @@ http://www.gnu.org/software/src-highlite -->

The listening port is returned.

Examples

Get the listening port
-
diff --git a/docs/en/ranch/1.7/manual/ranch.get_protocol_options/index.html b/docs/en/ranch/1.7/manual/ranch.get_protocol_options/index.html index 9e8d7d88..65dbcf12 100644 --- a/docs/en/ranch/1.7/manual/ranch.get_protocol_options/index.html +++ b/docs/en/ranch/1.7/manual/ranch.get_protocol_options/index.html @@ -65,7 +65,7 @@

Name

ranch:get_protocol_options - Get the current protocol options

Description

-
@@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

The current protocol options are returned.

Examples

Get the current protocol options
-
diff --git a/docs/en/ranch/1.7/manual/ranch.get_status/index.html b/docs/en/ranch/1.7/manual/ranch.get_status/index.html index 40ec9176..49d3b336 100644 --- a/docs/en/ranch/1.7/manual/ranch.get_status/index.html +++ b/docs/en/ranch/1.7/manual/ranch.get_status/index.html @@ -65,7 +65,7 @@

Name

ranch:get_status - Get a listener's running state

Description

-
@@ -85,7 +85,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Get a listener's running state
-
diff --git a/docs/en/ranch/1.7/manual/ranch.get_transport_options/index.html b/docs/en/ranch/1.7/manual/ranch.get_transport_options/index.html index 25871700..9786a103 100644 --- a/docs/en/ranch/1.7/manual/ranch.get_transport_options/index.html +++ b/docs/en/ranch/1.7/manual/ranch.get_transport_options/index.html @@ -65,7 +65,7 @@

Name

ranch:get_transport_options - Get the current transport options

Description

-
@@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

The current transport options are returned.

Examples

Get the current transport options
-
diff --git a/docs/en/ranch/1.7/manual/ranch.handshake/index.html b/docs/en/ranch/1.7/manual/ranch.handshake/index.html index e4121a8a..06145f4a 100644 --- a/docs/en/ranch/1.7/manual/ranch.handshake/index.html +++ b/docs/en/ranch/1.7/manual/ranch.handshake/index.html @@ -65,7 +65,7 @@

Name

ranch:handshake - Perform the transport handshake

Description

-
@@ -97,7 +97,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Initialize the connection process
-
diff --git a/docs/en/ranch/1.7/manual/ranch.info/index.html b/docs/en/ranch/1.7/manual/ranch.info/index.html index 42c8ed58..f7506d46 100644 --- a/docs/en/ranch/1.7/manual/ranch.info/index.html +++ b/docs/en/ranch/1.7/manual/ranch.info/index.html @@ -65,7 +65,7 @@

Name

ranch:info - Overview of Ranch listeners

Description

-
@@ -123,14 +123,14 @@ http://www.gnu.org/software/src-highlite -->

Examples

Get information about all listeners
-
AllInfo = ranch:info().
Get information about a specific listener
-
diff --git a/docs/en/ranch/1.7/manual/ranch.procs/index.html b/docs/en/ranch/1.7/manual/ranch.procs/index.html index d306a1ff..2bce6c1d 100644 --- a/docs/en/ranch/1.7/manual/ranch.procs/index.html +++ b/docs/en/ranch/1.7/manual/ranch.procs/index.html @@ -65,7 +65,7 @@

Name

ranch:procs - Retrieve pids from a listener

Description

-
@@ -86,14 +86,14 @@ http://www.gnu.org/software/src-highlite -->

A list of pids is returned.

Examples

Get the pids of the acceptor processes
-
Pids = ranch:procs(acceptors).
Get the pids of the connection processes
-
diff --git a/docs/en/ranch/1.7/manual/ranch.recv_proxy_header/index.html b/docs/en/ranch/1.7/manual/ranch.recv_proxy_header/index.html index e652fac6..f0b05deb 100644 --- a/docs/en/ranch/1.7/manual/ranch.recv_proxy_header/index.html +++ b/docs/en/ranch/1.7/manual/ranch.recv_proxy_header/index.html @@ -65,7 +65,7 @@

Name

ranch:recv_proxy_header - Receive the PROXY protocol header

Description

-
@@ -94,7 +94,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Receive the PROXY protocol header
-
diff --git a/docs/en/ranch/1.7/manual/ranch.remove_connection/index.html b/docs/en/ranch/1.7/manual/ranch.remove_connection/index.html index df47d1d8..540ed9a9 100644 --- a/docs/en/ranch/1.7/manual/ranch.remove_connection/index.html +++ b/docs/en/ranch/1.7/manual/ranch.remove_connection/index.html @@ -65,7 +65,7 @@

Name

ranch:remove_connection - Remove connection from the count

Description

-
@@ -83,7 +83,7 @@ http://www.gnu.org/software/src-highlite -->

The atom ok is always returned. It can be safely ignored.

Examples

Remove the connection process from the count
-
diff --git a/docs/en/ranch/1.7/manual/ranch.resume_listener/index.html b/docs/en/ranch/1.7/manual/ranch.resume_listener/index.html index f702c4f0..9aabac54 100644 --- a/docs/en/ranch/1.7/manual/ranch.resume_listener/index.html +++ b/docs/en/ranch/1.7/manual/ranch.resume_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:resume_listener - Resume a suspended listener

Description

-
@@ -89,7 +89,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Resume a listener
-
diff --git a/docs/en/ranch/1.7/manual/ranch.set_max_connections/index.html b/docs/en/ranch/1.7/manual/ranch.set_max_connections/index.html index c25d3210..ab1c1caf 100644 --- a/docs/en/ranch/1.7/manual/ranch.set_max_connections/index.html +++ b/docs/en/ranch/1.7/manual/ranch.set_max_connections/index.html @@ -65,7 +65,7 @@

Name

ranch:set_max_connections - Set the max number of connections

Description

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

The atom ok is always returned. It can be safely ignored.

Examples

Set the max number of connections
-
diff --git a/docs/en/ranch/1.7/manual/ranch.set_protocol_options/index.html b/docs/en/ranch/1.7/manual/ranch.set_protocol_options/index.html index bfef32a3..e69e4e98 100644 --- a/docs/en/ranch/1.7/manual/ranch.set_protocol_options/index.html +++ b/docs/en/ranch/1.7/manual/ranch.set_protocol_options/index.html @@ -65,7 +65,7 @@

Name

ranch:set_protocol_options - Set the protocol options

Description

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

The atom ok is always returned. It can be safely ignored.

Examples

Set the protocol options
-
diff --git a/docs/en/ranch/1.7/manual/ranch.set_transport_options/index.html b/docs/en/ranch/1.7/manual/ranch.set_transport_options/index.html index 893b526f..f4b517a9 100644 --- a/docs/en/ranch/1.7/manual/ranch.set_transport_options/index.html +++ b/docs/en/ranch/1.7/manual/ranch.set_transport_options/index.html @@ -65,7 +65,7 @@

Name

ranch:set_transport_options - Set the transport options

Description

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

The atom ok is always returned. It can be safely ignored.

Examples

Set the transport options
-
diff --git a/docs/en/ranch/1.7/manual/ranch.start_listener/index.html b/docs/en/ranch/1.7/manual/ranch.start_listener/index.html index b5a5af72..cc06379d 100644 --- a/docs/en/ranch/1.7/manual/ranch.start_listener/index.html +++ b/docs/en/ranch/1.7/manual/ranch.start_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:start_listener - Start a listener

Description

-
@@ -111,7 +111,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Start a listener
-
@@ -121,7 +121,7 @@ http://www.gnu.org/software/src-highlite --> ).
Start a listener with Ranch-specific options
-
@@ -134,7 +134,7 @@ http://www.gnu.org/software/src-highlite --> ).
Start a listener on a random port
-
diff --git a/docs/en/ranch/1.7/manual/ranch.stop_listener/index.html b/docs/en/ranch/1.7/manual/ranch.stop_listener/index.html index 4df7bd03..d1086774 100644 --- a/docs/en/ranch/1.7/manual/ranch.stop_listener/index.html +++ b/docs/en/ranch/1.7/manual/ranch.stop_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:stop_listener - Stop a listener

Description

-
@@ -86,7 +86,7 @@ http://www.gnu.org/software/src-highlite -->

An error tuple is returned when the listener is not found.

Examples

Stop a listener
-
diff --git a/docs/en/ranch/1.7/manual/ranch.suspend_listener/index.html b/docs/en/ranch/1.7/manual/ranch.suspend_listener/index.html index 283e0645..7bf6deea 100644 --- a/docs/en/ranch/1.7/manual/ranch.suspend_listener/index.html +++ b/docs/en/ranch/1.7/manual/ranch.suspend_listener/index.html @@ -65,7 +65,7 @@

Name

ranch:suspend_listener - Suspend a running listener

Description

-
@@ -90,7 +90,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Suspend a listener
-
diff --git a/docs/en/ranch/1.7/manual/ranch.wait_for_connections/index.html b/docs/en/ranch/1.7/manual/ranch.wait_for_connections/index.html index 4ca0c580..ad0e9719 100644 --- a/docs/en/ranch/1.7/manual/ranch.wait_for_connections/index.html +++ b/docs/en/ranch/1.7/manual/ranch.wait_for_connections/index.html @@ -65,7 +65,7 @@

Name

ranch:wait_for_connections - Wait for a specific number of connections

Description

-
@@ -99,14 +99,14 @@ http://www.gnu.org/software/src-highlite -->

Examples

Wait for at least 100 connections
-
ranch:wait_for_connections(example, '>=', 100).
Gracefully shutdown a listener
-
diff --git a/docs/en/ranch/1.7/manual/ranch/index.html b/docs/en/ranch/1.7/manual/ranch/index.html index 0d572d49..160ccbcf 100644 --- a/docs/en/ranch/1.7/manual/ranch/index.html +++ b/docs/en/ranch/1.7/manual/ranch/index.html @@ -121,7 +121,7 @@

Types

max_conns()

-
@@ -130,7 +130,7 @@ http://www.gnu.org/software/src-highlite -->

Maximum number of connections allowed on this listener.

This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.

opt()

-
@@ -144,7 +144,7 @@ http://www.gnu.org/software/src-highlite -->

Deprecated form for Ranch-specific options.

Please use the opts() type when you need to provide Ranch-specific transport options. Socket options will remain separate from the Ranch-specific options.

opts()

-
@@ -188,7 +188,7 @@ http://www.gnu.org/software/src-highlite -->

ref()

-
diff --git a/docs/en/ranch/1.7/manual/ranch_app/index.html b/docs/en/ranch/1.7/manual/ranch_app/index.html index c9112ee6..8e59db21 100644 --- a/docs/en/ranch/1.7/manual/ranch_app/index.html +++ b/docs/en/ranch/1.7/manual/ranch_app/index.html @@ -91,7 +91,7 @@

All these applications must be started before the ranch application. To start Ranch and all dependencies at once:

-
diff --git a/docs/en/ranch/1.7/manual/ranch_protocol/index.html b/docs/en/ranch/1.7/manual/ranch_protocol/index.html index 491734f2..41d2faf9 100644 --- a/docs/en/ranch/1.7/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.7/manual/ranch_protocol/index.html @@ -68,7 +68,7 @@

The module ranch_protocol defines the interface used by Ranch protocols.

Callbacks

Ranch protocols implement the following interface:

-
diff --git a/docs/en/ranch/1.7/manual/ranch_proxy_header.header/index.html b/docs/en/ranch/1.7/manual/ranch_proxy_header.header/index.html index f11ccf2c..05689967 100644 --- a/docs/en/ranch/1.7/manual/ranch_proxy_header.header/index.html +++ b/docs/en/ranch/1.7/manual/ranch_proxy_header.header/index.html @@ -65,7 +65,7 @@

Name

ranch_proxy_header:header - Build a PROXY protocol header

Description

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

Examples

Build a PROXY protocol header
-
@@ -114,7 +114,7 @@ http://www.gnu.org/software/src-highlite --> Data = ranch_proxy_header:parse(ProxyInfo).
Build a PROXY protocol header with checksum and padding
-
diff --git a/docs/en/ranch/1.7/manual/ranch_proxy_header.parse/index.html b/docs/en/ranch/1.7/manual/ranch_proxy_header.parse/index.html index a71802d5..eea27d64 100644 --- a/docs/en/ranch/1.7/manual/ranch_proxy_header.parse/index.html +++ b/docs/en/ranch/1.7/manual/ranch_proxy_header.parse/index.html @@ -65,7 +65,7 @@

Name

ranch_proxy_header:parse - Parse a PROXY protocol header

Description

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

Examples

Parse the PROXY protocol header
-
diff --git a/docs/en/ranch/1.7/manual/ranch_proxy_header/index.html b/docs/en/ranch/1.7/manual/ranch_proxy_header/index.html index 38206908..c3be8e72 100644 --- a/docs/en/ranch/1.7/manual/ranch_proxy_header/index.html +++ b/docs/en/ranch/1.7/manual/ranch_proxy_header/index.html @@ -74,7 +74,7 @@

Types

proxy_info()

-
diff --git a/docs/en/ranch/1.7/manual/ranch_ssl/index.html b/docs/en/ranch/1.7/manual/ranch_ssl/index.html index e839491c..ca74fa16 100644 --- a/docs/en/ranch/1.7/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.7/manual/ranch_ssl/index.html @@ -70,7 +70,7 @@

The module ranch_ssl implements the interface defined by ranch_transport(3).

Types

opt()

-
@@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite -->

Listen options.

The TCP options are defined in ranch_tcp(3).

opts()

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

List of listen options.

ssl_opt()

-
diff --git a/docs/en/ranch/1.7/manual/ranch_tcp/index.html b/docs/en/ranch/1.7/manual/ranch_tcp/index.html index 5b566045..a64b104a 100644 --- a/docs/en/ranch/1.7/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.7/manual/ranch_tcp/index.html @@ -71,7 +71,7 @@

The module ranch_tcp implements the interface defined by ranch_transport(3).

Types

opt()

-
@@ -180,7 +180,7 @@ http://www.gnu.org/software/src-highlite -->

In addition, the raw option can be used to set system-specific options by specifying the protocol level, the option number and the actual option value specified as a binary. This option is not portable. Use with caution.

opts()

-
diff --git a/docs/en/ranch/1.7/manual/ranch_transport.sendfile/index.html b/docs/en/ranch/1.7/manual/ranch_transport.sendfile/index.html index d781788d..3d121d38 100644 --- a/docs/en/ranch/1.7/manual/ranch_transport.sendfile/index.html +++ b/docs/en/ranch/1.7/manual/ranch_transport.sendfile/index.html @@ -65,7 +65,7 @@

Name

ranch_transport:sendfile - Send a file on the socket

Description

-
@@ -109,7 +109,7 @@ http://www.gnu.org/software/src-highlite -->

Examples

Implement Transport:sendfile using the fallback
-
diff --git a/docs/en/ranch/1.7/manual/ranch_transport/index.html b/docs/en/ranch/1.7/manual/ranch_transport/index.html index 4573297e..fa7d682d 100644 --- a/docs/en/ranch/1.7/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.7/manual/ranch_transport/index.html @@ -69,7 +69,7 @@

Callbacks

Ranch transports implement the following interface:

accept

-
@@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite -->

Use the listening socket returned by listen/1 to accept a new connection. The timeout is specified in milliseconds.

close

-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

Close the socket.

controlling_process

-
@@ -96,7 +96,7 @@ http://www.gnu.org/software/src-highlite -->

Assign a new controlling process to the socket. The controlling process is the process that is linked to and receives messages from the socket.

getopts

-
@@ -105,7 +105,7 @@ http://www.gnu.org/software/src-highlite -->

Get one or more options for the socket.

getstat

-
@@ -113,7 +113,7 @@ http://www.gnu.org/software/src-highlite --> -> {ok, SockStatValues :: any()} | {error, atom()}

Get all statistics for the socket.

-
@@ -122,7 +122,7 @@ http://www.gnu.org/software/src-highlite -->

Get one or more statistic options for the socket.

handshake

-
@@ -135,7 +135,7 @@ http://www.gnu.org/software/src-highlite -->

This function will be called by connection processes before performing any socket operation. It allows transports that require extra initialization to perform their task and return a socket that is ready to use.

This function may also be used to upgrade a connection from a transport to another depending on the capabilities of the transports. For example a ranch_tcp socket may be upgraded to a ranch_ssl one using this function.

listen

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

Create a socket that listens on the given port.

The port may not be specified or may be set to 0, which means a random available port number will be chosen.

messages

-
@@ -156,7 +156,7 @@ http://www.gnu.org/software/src-highlite -->

Return the tuple keys for the messages sent by the socket.

name

-
@@ -164,7 +164,7 @@ http://www.gnu.org/software/src-highlite -->

Return the name of the transport.

peername

-
@@ -174,7 +174,7 @@ http://www.gnu.org/software/src-highlite -->

Return the address and port number for the other end of the connection.

recv

-
@@ -189,7 +189,7 @@ http://www.gnu.org/software/src-highlite -->

A length of 0 will return the data available on the socket as soon as possible, regardless of length.

While it is possible to use the timeout value infinity, it is highly discouraged as it could cause your process to get stuck waiting for data that will never come. This may happen when a socket becomes half-open due to a crash of the remote endpoint. Wi-Fi going down is another common culprit.

secure

-
@@ -197,7 +197,7 @@ http://www.gnu.org/software/src-highlite -->

Return whether the transport can be used for secure connections.

send

-
@@ -206,7 +206,7 @@ http://www.gnu.org/software/src-highlite -->

Send a packet on the socket.

sendfile

-
@@ -227,7 +227,7 @@ http://www.gnu.org/software/src-highlite -->

The file may be sent full or in parts, and may be specified by its filename or by an already open file descriptor.

Transports that manipulate TCP directly may use the file:sendfile/2,4,5 function, which calls the sendfile syscall where applicable (on Linux, for example). Other transports can use the sendfile/6 function exported from this module.

setopts

-
@@ -236,7 +236,7 @@ http://www.gnu.org/software/src-highlite -->

Set one or more options for the socket.

shutdown

-
@@ -246,7 +246,7 @@ http://www.gnu.org/software/src-highlite -->

Close the socket for reading and/or writing.

sockname

-
@@ -262,7 +262,7 @@ http://www.gnu.org/software/src-highlite -->

Types

sendfile_opts()

-
@@ -274,7 +274,7 @@ http://www.gnu.org/software/src-highlite -->

socket()

-
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
      -
      diff --git a/docs/en/ranch/2.0/manual/index.html b/docs/en/ranch/2.0/manual/index.html index 02b16f1a..d648116a 100644 --- a/docs/en/ranch/2.0/manual/index.html +++ b/docs/en/ranch/2.0/manual/index.html @@ -91,7 +91,7 @@

    All these applications must be started before the ranch application. To start Ranch and all dependencies at once:

    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.child_spec/index.html b/docs/en/ranch/2.0/manual/ranch.child_spec/index.html index b87bcf89..5e347085 100644 --- a/docs/en/ranch/2.0/manual/ranch.child_spec/index.html +++ b/docs/en/ranch/2.0/manual/ranch.child_spec/index.html @@ -65,7 +65,7 @@

    Name

    ranch:child_spec - Build child specifications for a new listener

    Description

    -
    @@ -112,7 +112,7 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Embed a listener
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.get_addr/index.html b/docs/en/ranch/2.0/manual/ranch.get_addr/index.html index 00941deb..56e1f14e 100644 --- a/docs/en/ranch/2.0/manual/ranch.get_addr/index.html +++ b/docs/en/ranch/2.0/manual/ranch.get_addr/index.html @@ -65,7 +65,7 @@

    Name

    ranch:get_addr - Get the listening address

    Description

    -
    @@ -87,14 +87,14 @@ http://www.gnu.org/software/src-highlite -->

    The socket file is the path of a file on your system the socket is bound to.

    Examples

    Get the listening port and IP
    -
    {IP, Port} = ranch:get_addr(example).
    Get the listening UNIX Domain socket file
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.get_max_connections/index.html b/docs/en/ranch/2.0/manual/ranch.get_max_connections/index.html index 1fa12d4b..ec0cfeae 100644 --- a/docs/en/ranch/2.0/manual/ranch.get_max_connections/index.html +++ b/docs/en/ranch/2.0/manual/ranch.get_max_connections/index.html @@ -65,7 +65,7 @@

    Name

    ranch:get_max_connections - Get the max number of connections per connection supervisor

    Description

    -
    @@ -86,7 +86,7 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Get the max number of connections per connection supervisor
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.get_port/index.html b/docs/en/ranch/2.0/manual/ranch.get_port/index.html index dcd851b9..b1552029 100644 --- a/docs/en/ranch/2.0/manual/ranch.get_port/index.html +++ b/docs/en/ranch/2.0/manual/ranch.get_port/index.html @@ -65,7 +65,7 @@

    Name

    ranch:get_port - Get the listening port

    Description

    -
    @@ -84,7 +84,7 @@ http://www.gnu.org/software/src-highlite -->

    When the listener is suspended or using a UNIX Domain socket instead of a network interface, undefined will be returned.

    Examples

    Get the listening port
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.get_protocol_options/index.html b/docs/en/ranch/2.0/manual/ranch.get_protocol_options/index.html index fd6dd4df..5b440f55 100644 --- a/docs/en/ranch/2.0/manual/ranch.get_protocol_options/index.html +++ b/docs/en/ranch/2.0/manual/ranch.get_protocol_options/index.html @@ -65,7 +65,7 @@

    Name

    ranch:get_protocol_options - Get the current protocol options

    Description

    -
    @@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

    The current protocol options are returned.

    Examples

    Get the current protocol options
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.get_status/index.html b/docs/en/ranch/2.0/manual/ranch.get_status/index.html index ff148989..7ddb43f3 100644 --- a/docs/en/ranch/2.0/manual/ranch.get_status/index.html +++ b/docs/en/ranch/2.0/manual/ranch.get_status/index.html @@ -65,7 +65,7 @@

    Name

    ranch:get_status - Get a listener's running state

    Description

    -
    @@ -85,7 +85,7 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Get a listener's running state
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.get_transport_options/index.html b/docs/en/ranch/2.0/manual/ranch.get_transport_options/index.html index 4d1502a7..6f2810e4 100644 --- a/docs/en/ranch/2.0/manual/ranch.get_transport_options/index.html +++ b/docs/en/ranch/2.0/manual/ranch.get_transport_options/index.html @@ -65,7 +65,7 @@

    Name

    ranch:get_transport_options - Get the current transport options

    Description

    -
    @@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

    The current transport options are returned.

    Examples

    Get the current transport options
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.handshake/index.html b/docs/en/ranch/2.0/manual/ranch.handshake/index.html index 12a93e43..c32fe543 100644 --- a/docs/en/ranch/2.0/manual/ranch.handshake/index.html +++ b/docs/en/ranch/2.0/manual/ranch.handshake/index.html @@ -65,16 +65,17 @@

    Name

    ranch:handshake - Perform the transport handshake

    Description

    -
    -
    handshake(Ref)       -> handshake(Ref, [])
-handshake(Ref, Opts) -> {ok, Socket}
+
    handshake(Ref)       -> {ok, Socket} | {continue, Info}
+handshake(Ref, Opts) -> {ok, Socket} | {continue, Info}
 
 Ref    :: ranch:ref()
 Opts   :: any()
-Socket :: any()
    
+Socket :: any()
+Info   :: any()

    Perform the transport handshake.

    This function must be called by the protocol process in order to retrieve the socket for the connection. Ranch performs the handshake necessary to give control of the socket to this process and also does the transport handshake, for example setting up the TLS connection.

    @@ -88,19 +89,22 @@ http://www.gnu.org/software/src-highlite -->

    Return value

    -

    An ok tuple is returned containing the socket for the connection.

    +

    An ok tuple is returned containing the socket for the connection by default.

    +

    Depending on configuration, a continue tuple can otherwise be returned when the handshake operation is paused. It contains data provided by the transport that can be used to inform further decisions before resuming the handshake, for example to provide new transport options. The handshake can be resumed using ranch:handshake_continue(3) or canceled using ranch:handshake_cancel(3).

    This function will trigger an exception when an error occurs.

    Changelog

    -
    • 1.6: Function introduced. Replaces ranch:accept_ack/1. +
      • 2.0: The continue tuple can now be returned. +
        • +
      • 1.6: Function introduced. Replaces ranch:accept_ack/1.

      Examples

      Initialize the connection process
      -
      -
      start_link(Ref, _, Transport, Opts) ->
+
      start_link(Ref, Transport, Opts) ->
     Pid = proc_lib:spawn_link(?MODULE, init,
         [Ref, Transport, Opts]),
     {ok, Pid}.
@@ -111,7 +115,7 @@ http://www.gnu.org/software/src-highlite -->
         transport=Transport, opts=Opts}).

      See also

      -

      ranch:start_listener(3), ranch:recv_proxy_header(3), ranch:remove_connection(3), ranch(3)

      +

      ranch:start_listener(3), ranch:handshake_continue(3), ranch:handshake_cancel(3), ranch:recv_proxy_header(3), ranch:remove_connection(3), ranch(3)

      diff --git a/docs/en/ranch/2.0/manual/ranch.handshake_cancel/index.html b/docs/en/ranch/2.0/manual/ranch.handshake_cancel/index.html new file mode 100644 index 00000000..bebe43b1 --- /dev/null +++ b/docs/en/ranch/2.0/manual/ranch.handshake_cancel/index.html @@ -0,0 +1,198 @@ + + + + + + + + + + Nine Nines: ranch:handshake_cancel(3) + + + + + + + + + + + + + + +
      +
      +
      +
      +

      99s

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

      ranch:handshake_cancel(3)

      + +

      Name

      +

      ranch:handshake_cancel - Cancel the paused transport handshake

      +

      Description

      +
      +
      handshake_cancel(Ref :: ranch:ref()) -> ok
      +
      +

      Cancel the paused transport handshake.

      +

      This function may be called by the protocol process to cancel a paused handshake.

      +

      Arguments

      +
      Ref
      +

      The listener name.

      +

      Allowed options depend on the transport module.

      +
      +
      +

      Return value

      +

      The return value depends on the transport module.

      +

      Changelog

      +
      • 2.0: Function introduced. +
        • +
      +

      Examples

      +
      Cancel a paused transport handshake
      +
      +
      start_link(Ref, Transport, Opts) ->
+    Pid = proc_lib:spawn_link(?MODULE, init,
+        [Ref, Transport, Opts]),
+    {ok, Pid}.
+
+init(Ref, Transport, Opts) ->
+    {continue, _Info} = ranch:handshake(Ref),
+    ranch:handshake_cancel(Ref),
+    exit(handshake_cancelled).
      +
      +

      See also

      +

      ranch:handshake(3), ranch:handshake_continue(3), ranch(3)

      + + + + + + +
      + +
      + + +

      + Ranch + 2.0 + Function Reference + +

      + + + +

      Navigation

      + +

      Version select

      + + +

      Like my work? Donate!

      +

      Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

      +
      + + + + + + + + + +

      Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

      + + + +
      +
      +
      +
      + + + + + + + + + diff --git a/docs/en/ranch/2.0/manual/ranch.handshake_continue/index.html b/docs/en/ranch/2.0/manual/ranch.handshake_continue/index.html new file mode 100644 index 00000000..2ee11955 --- /dev/null +++ b/docs/en/ranch/2.0/manual/ranch.handshake_continue/index.html @@ -0,0 +1,208 @@ + + + + + + + + + + Nine Nines: ranch:handshake_continue(3) + + + + + + + + + + + + + + +
      +
      +
      +
      +

      99s

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

      ranch:handshake_continue(3)

      + +

      Name

      +

      ranch:handshake_continue - Resume the paused transport handshake

      +

      Description

      +
      +
      handshake_continue(Ref)       -> {ok, Socket}
+handshake_continue(Ref, Opts) -> {ok, Socket}
+
+Ref    :: ranch:ref()
+Opts   :: any()
+Socket :: any()
      +
      +

      Resume the paused transport handshake.

      +

      This function must be called by the protocol process in order to resume a paused handshake.

      +

      Arguments

      +
      Ref
      +

      The listener name.

      +
      +
      Opts
      +

      Transport handshake options.

      +

      Allowed options depend on the transport module.

      +
      +
      +

      Return value

      +

      An ok tuple is returned containing the socket for the connection.

      +

      This function will trigger an exception when an error occurs.

      +

      Changelog

      +
      • 2.0: Function introduced. +
        • +
      +

      Examples

      +
      Continue a paused transport handshake
      +
      +
      start_link(Ref, Transport, Opts) ->
+    Pid = proc_lib:spawn_link(?MODULE, init,
+        [Ref, Transport, Opts]),
+    {ok, Pid}.
+
+init(Ref, Transport, Opts) ->
+    {continue, _Info} = ranch:handshake(Ref),
+    {ok, Socket} = ranch:handshake_continue(Ref),
+    loop(#state{ref=Ref, socket=Socket,
+        transport=Transport, opts=Opts}).
      +
      +

      See also

      +

      ranch:handshake(3), ranch:handshake_cancel(3), ranch(3)

      + + + + + + +
      + +
      + + +

      + Ranch + 2.0 + Function Reference + +

      + + + +

      Navigation

      + +

      Version select

      + + +

      Like my work? Donate!

      +

      Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

      +
      + + + + + + + + + +

      Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

      + + + +
      +
      +
      +
      + + + + + + + + + diff --git a/docs/en/ranch/2.0/manual/ranch.info/index.html b/docs/en/ranch/2.0/manual/ranch.info/index.html index 3248864d..81558097 100644 --- a/docs/en/ranch/2.0/manual/ranch.info/index.html +++ b/docs/en/ranch/2.0/manual/ranch.info/index.html @@ -65,7 +65,7 @@

      Name

      ranch:info - Overview of Ranch listeners

      Description

      -
      @@ -124,14 +124,14 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Get information about all listeners
    -
    AllInfo = ranch:info().
    Get information about a specific listener
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.procs/index.html b/docs/en/ranch/2.0/manual/ranch.procs/index.html index 32e0f2e8..3140a123 100644 --- a/docs/en/ranch/2.0/manual/ranch.procs/index.html +++ b/docs/en/ranch/2.0/manual/ranch.procs/index.html @@ -65,7 +65,7 @@

    Name

    ranch:procs - Retrieve pids from a listener

    Description

    -
    @@ -86,14 +86,14 @@ http://www.gnu.org/software/src-highlite -->

    A list of pids is returned.

    Examples

    Get the pids of the acceptor processes
    -
    Pids = ranch:procs(acceptors).
    Get the pids of the connection processes
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.recv_proxy_header/index.html b/docs/en/ranch/2.0/manual/ranch.recv_proxy_header/index.html index da04c826..e4cf5c00 100644 --- a/docs/en/ranch/2.0/manual/ranch.recv_proxy_header/index.html +++ b/docs/en/ranch/2.0/manual/ranch.recv_proxy_header/index.html @@ -65,7 +65,7 @@

    Name

    ranch:recv_proxy_header - Receive the PROXY protocol header

    Description

    -
    @@ -94,11 +94,11 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Receive the PROXY protocol header
    -
    -
    start_link(Ref, _, Transport, Opts) ->
+
    start_link(Ref, Transport, Opts) ->
     Pid = proc_lib:spawn_link(?MODULE, init,
         [Ref, Transport, Opts]),
     {ok, Pid}.
diff --git a/docs/en/ranch/2.0/manual/ranch.remove_connection/index.html b/docs/en/ranch/2.0/manual/ranch.remove_connection/index.html
index 0531fe78..7606e5a8 100644
--- a/docs/en/ranch/2.0/manual/ranch.remove_connection/index.html
+++ b/docs/en/ranch/2.0/manual/ranch.remove_connection/index.html
@@ -65,7 +65,7 @@
 
    Name
    
 
    ranch:remove_connection - Remove connection from the count
    
 
    Description
    
-
    
@@ -83,7 +83,7 @@ http://www.gnu.org/software/src-highlite -->
 
    The atom ok is always returned. It can be safely ignored.
    
 
    Examples
    
 
    Remove the connection process from the count
    
-
    
diff --git a/docs/en/ranch/2.0/manual/ranch.resume_listener/index.html b/docs/en/ranch/2.0/manual/ranch.resume_listener/index.html
index 47ea0568..eb589ce0 100644
--- a/docs/en/ranch/2.0/manual/ranch.resume_listener/index.html
+++ b/docs/en/ranch/2.0/manual/ranch.resume_listener/index.html
@@ -65,7 +65,7 @@
 
    Name
    
 
    ranch:resume_listener - Resume a suspended listener
    
 
    Description
    
-
    
@@ -89,7 +89,7 @@ http://www.gnu.org/software/src-highlite -->
 
 
    Examples
    
 
    Resume a listener
    
-
    
diff --git a/docs/en/ranch/2.0/manual/ranch.set_max_connections/index.html b/docs/en/ranch/2.0/manual/ranch.set_max_connections/index.html
index 4c46e938..a167e427 100644
--- a/docs/en/ranch/2.0/manual/ranch.set_max_connections/index.html
+++ b/docs/en/ranch/2.0/manual/ranch.set_max_connections/index.html
@@ -65,7 +65,7 @@
 
    Name
    
 
    ranch:set_max_connections - Set the max number of connections per connection supervisor
    
 
    Description
    
-
    
@@ -91,7 +91,7 @@ http://www.gnu.org/software/src-highlite -->
 
 
    Examples
    
 
    Set the max number of connections per connection supervisor
    
-
    
diff --git a/docs/en/ranch/2.0/manual/ranch.set_protocol_options/index.html b/docs/en/ranch/2.0/manual/ranch.set_protocol_options/index.html
index 02a8c170..56242651 100644
--- a/docs/en/ranch/2.0/manual/ranch.set_protocol_options/index.html
+++ b/docs/en/ranch/2.0/manual/ranch.set_protocol_options/index.html
@@ -65,7 +65,7 @@
 
    Name
    
 
    ranch:set_protocol_options - Set the protocol options
    
 
    Description
    
-
    
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->
 
    The atom ok is always returned. It can be safely ignored.
    
 
    Examples
    
 
    Set the protocol options
    
-
    
diff --git a/docs/en/ranch/2.0/manual/ranch.set_transport_options/index.html b/docs/en/ranch/2.0/manual/ranch.set_transport_options/index.html
index b031ef9f..ab3597da 100644
--- a/docs/en/ranch/2.0/manual/ranch.set_transport_options/index.html
+++ b/docs/en/ranch/2.0/manual/ranch.set_transport_options/index.html
@@ -65,7 +65,7 @@
 
    Name
    
 
    ranch:set_transport_options - Set the transport options
    
 
    Description
    
-
    
@@ -122,7 +122,7 @@ http://www.gnu.org/software/src-highlite -->
 
 
    Examples
    
 
    Set the transport options
    
-
    
diff --git a/docs/en/ranch/2.0/manual/ranch.start_listener/index.html b/docs/en/ranch/2.0/manual/ranch.start_listener/index.html
index a3010bab..6ea43fb6 100644
--- a/docs/en/ranch/2.0/manual/ranch.start_listener/index.html
+++ b/docs/en/ranch/2.0/manual/ranch.start_listener/index.html
@@ -65,7 +65,7 @@
 
    Name
    
 
    ranch:start_listener - Start a listener
    
 
    Description
    
-
    
@@ -113,7 +113,7 @@ http://www.gnu.org/software/src-highlite -->
 
 
    Examples
    
 
    Start a listener
    
-
    
@@ -123,7 +123,7 @@ http://www.gnu.org/software/src-highlite -->
 ).
    Start a listener with Ranch-specific options
    -
    @@ -136,7 +136,7 @@ http://www.gnu.org/software/src-highlite --> ).
    Start a listener on a random port
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.stop_listener/index.html b/docs/en/ranch/2.0/manual/ranch.stop_listener/index.html index e2287ceb..8e820644 100644 --- a/docs/en/ranch/2.0/manual/ranch.stop_listener/index.html +++ b/docs/en/ranch/2.0/manual/ranch.stop_listener/index.html @@ -65,7 +65,7 @@

    Name

    ranch:stop_listener - Stop a listener

    Description

    -
    @@ -86,7 +86,7 @@ http://www.gnu.org/software/src-highlite -->

    An error tuple is returned when the listener is not found.

    Examples

    Stop a listener
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.suspend_listener/index.html b/docs/en/ranch/2.0/manual/ranch.suspend_listener/index.html index da1ec7c3..e616ff15 100644 --- a/docs/en/ranch/2.0/manual/ranch.suspend_listener/index.html +++ b/docs/en/ranch/2.0/manual/ranch.suspend_listener/index.html @@ -65,7 +65,7 @@

    Name

    ranch:suspend_listener - Suspend a running listener

    Description

    -
    @@ -90,7 +90,7 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Suspend a listener
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch.wait_for_connections/index.html b/docs/en/ranch/2.0/manual/ranch.wait_for_connections/index.html index 00b7c507..e4b5ba65 100644 --- a/docs/en/ranch/2.0/manual/ranch.wait_for_connections/index.html +++ b/docs/en/ranch/2.0/manual/ranch.wait_for_connections/index.html @@ -65,7 +65,7 @@

    Name

    ranch:wait_for_connections - Wait for a specific number of connections

    Description

    -
    @@ -99,14 +99,14 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Wait for at least 100 connections
    -
    ranch:wait_for_connections(example, '>=', 100).
    Gracefully shutdown a listener
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch/index.html b/docs/en/ranch/2.0/manual/ranch/index.html index 8744dab9..d385f2eb 100644 --- a/docs/en/ranch/2.0/manual/ranch/index.html +++ b/docs/en/ranch/2.0/manual/ranch/index.html @@ -86,6 +86,10 @@

    Connections:

    Types

    max_conns()

    -
    @@ -128,7 +132,7 @@ http://www.gnu.org/software/src-highlite -->

    Maximum number of connections allowed per connection supervisor.

    This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.

    opts()

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

    Transport or socket options.

    It is possible to give the full transport options in a map (see transport_opts(SocketOpts)), or only the socket options (assuming they are not a map and no Ranch-specific option needs to be given).

    ref()

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

    Unique name used to refer to a listener.

    transport_opts(SocketOpts)

    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_app/index.html b/docs/en/ranch/2.0/manual/ranch_app/index.html index eb9f0b0a..dd4c9a74 100644 --- a/docs/en/ranch/2.0/manual/ranch_app/index.html +++ b/docs/en/ranch/2.0/manual/ranch_app/index.html @@ -91,7 +91,7 @@

    All these applications must be started before the ranch application. To start Ranch and all dependencies at once:

    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_protocol/index.html b/docs/en/ranch/2.0/manual/ranch_protocol/index.html index 2cf6cae0..97697460 100644 --- a/docs/en/ranch/2.0/manual/ranch_protocol/index.html +++ b/docs/en/ranch/2.0/manual/ranch_protocol/index.html @@ -68,7 +68,7 @@

    The module ranch_protocol defines the interface used by Ranch protocols.

    Callbacks

    Ranch protocols implement the following interface:

    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_proxy_header.header/index.html b/docs/en/ranch/2.0/manual/ranch_proxy_header.header/index.html index e83340fc..04885699 100644 --- a/docs/en/ranch/2.0/manual/ranch_proxy_header.header/index.html +++ b/docs/en/ranch/2.0/manual/ranch_proxy_header.header/index.html @@ -65,7 +65,7 @@

    Name

    ranch_proxy_header:header - Build a PROXY protocol header

    Description

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

    Examples

    Build a PROXY protocol header
    -
    @@ -114,7 +114,7 @@ http://www.gnu.org/software/src-highlite --> Data = ranch_proxy_header:parse(ProxyInfo).
    Build a PROXY protocol header with checksum and padding
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_proxy_header.parse/index.html b/docs/en/ranch/2.0/manual/ranch_proxy_header.parse/index.html index 8e33d6e4..e1dffb53 100644 --- a/docs/en/ranch/2.0/manual/ranch_proxy_header.parse/index.html +++ b/docs/en/ranch/2.0/manual/ranch_proxy_header.parse/index.html @@ -65,7 +65,7 @@

    Name

    ranch_proxy_header:parse - Parse a PROXY protocol header

    Description

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

    Examples

    Parse the PROXY protocol header
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_proxy_header/index.html b/docs/en/ranch/2.0/manual/ranch_proxy_header/index.html index 3d03e776..551da850 100644 --- a/docs/en/ranch/2.0/manual/ranch_proxy_header/index.html +++ b/docs/en/ranch/2.0/manual/ranch_proxy_header/index.html @@ -74,7 +74,7 @@

    Types

    proxy_info()

    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_ssl/index.html b/docs/en/ranch/2.0/manual/ranch_ssl/index.html index cc3766a4..840273d4 100644 --- a/docs/en/ranch/2.0/manual/ranch_ssl/index.html +++ b/docs/en/ranch/2.0/manual/ranch_ssl/index.html @@ -70,7 +70,7 @@

    The module ranch_ssl implements the interface defined by ranch_transport(3).

    Types

    opt()

    -
    @@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite -->

    Listen options.

    The TCP options are defined in ranch_tcp(3).

    opts()

    -
    @@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

    List of listen options.

    ssl_opt()

    -
    @@ -106,6 +106,7 @@ http://www.gnu.org/software/src-highlite --> | {dhfile, file:filename()} | {eccs, [atom()]} | {fail_if_no_peer_cert, boolean()} + | {handshake, hello | full} | {hibernate_after, timeout()} | {honor_cipher_order, boolean()} | {honor_ecc_order, boolean()} @@ -180,6 +181,10 @@ http://www.gnu.org/software/src-highlite -->
    fail_if_no_peer_cert (false)

    Whether to refuse the connection if the client sends an empty certificate.

    +
    handshake (full)
    +

    If hello is specified for this option, the handshake is paused after receiving the client hello message. The handshake can then be resumed via handshake_continue/3, or cancelled via handshake_cancel/1.

    +

    This option cannot be given to ranch:handshake/1,2.

    +
    hibernate_after (undefined)

    Time in ms after which SSL socket processes go into hibernation to reduce memory usage.

    diff --git a/docs/en/ranch/2.0/manual/ranch_tcp/index.html b/docs/en/ranch/2.0/manual/ranch_tcp/index.html index c5916c7e..c3cc88ec 100644 --- a/docs/en/ranch/2.0/manual/ranch_tcp/index.html +++ b/docs/en/ranch/2.0/manual/ranch_tcp/index.html @@ -71,7 +71,7 @@

    The module ranch_tcp implements the interface defined by ranch_transport(3).

    Types

    opt()

    -
    @@ -182,7 +182,7 @@ http://www.gnu.org/software/src-highlite -->

    In addition, the raw option can be used to set system-specific options by specifying the protocol level, the option number and the actual option value specified as a binary. This option is not portable. Use with caution.

    opts()

    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_transport.sendfile/index.html b/docs/en/ranch/2.0/manual/ranch_transport.sendfile/index.html index cb58f8e0..55239d53 100644 --- a/docs/en/ranch/2.0/manual/ranch_transport.sendfile/index.html +++ b/docs/en/ranch/2.0/manual/ranch_transport.sendfile/index.html @@ -65,7 +65,7 @@

    Name

    ranch_transport:sendfile - Send a file on the socket

    Description

    -
    @@ -109,7 +109,7 @@ http://www.gnu.org/software/src-highlite -->

    Examples

    Implement Transport:sendfile using the fallback
    -
    diff --git a/docs/en/ranch/2.0/manual/ranch_transport/index.html b/docs/en/ranch/2.0/manual/ranch_transport/index.html index 80f9f40c..16d9d4d8 100644 --- a/docs/en/ranch/2.0/manual/ranch_transport/index.html +++ b/docs/en/ranch/2.0/manual/ranch_transport/index.html @@ -69,7 +69,7 @@

    Callbacks

    Ranch transports implement the following interface:

    accept

    -
    @@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite -->

    Use the listening socket returned by listen/1 to accept a new connection. The timeout is specified in milliseconds.

    close

    -
    @@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

    Close the socket.

    controlling_process

    -
    @@ -96,7 +96,7 @@ http://www.gnu.org/software/src-highlite -->

    Assign a new controlling process to the socket. The controlling process is the process that is linked to and receives messages from the socket.

    getopts

    -
    @@ -105,7 +105,7 @@ http://www.gnu.org/software/src-highlite -->

    Get one or more options for the socket.

    getstat

    -
    @@ -113,7 +113,7 @@ http://www.gnu.org/software/src-highlite --> -> {ok, SockStatValues :: any()} | {error, atom()}

    Get all statistics for the socket.

    -
    @@ -122,20 +122,55 @@ http://www.gnu.org/software/src-highlite -->

    Get one or more statistic options for the socket.

    handshake

    -
    handshake(Socket0  :: socket(),
-          SockOpts :: any(),
           Timeout  :: timeout())
-    -> {ok, Socket}
    + -> {ok, Socket :: socket()} + | {ok, Socket :: socket(), Info :: any()} + | {error, any()} + +handshake(Socket0 :: socket(), + SockOpts :: opts(), + Timeout :: timeout()) + -> {ok, Socket :: socket()} + | {ok, Socket :: socket(), Info :: any()} + | {error, any()}

    Perform the transport-level handshake.

    This function will be called by connection processes before performing any socket operation. It allows transports that require extra initialization to perform their task and return a socket that is ready to use.

    +

    If the handshake is completed by this call, the function will return {ok, Socket}. However, some transports (notably, ranch_ssl if {handshake, hello} is specified in the socket options) may pause the handshake at a certain point and return {ok, Socket, Info} instead, in order to allow for additional decisions to be made before resuming the handshake with handshake_continue/3 or cancelling it with handshake_cancel/1.

    This function may also be used to upgrade a connection from a transport to another depending on the capabilities of the transports. For example a ranch_tcp socket may be upgraded to a ranch_ssl one using this function.

    +

    handshake_continue

    +
    +
    handshake_continue(Socket0  :: socket(),
+                   Timeout  :: timeout())
+    -> {ok, Socket :: socket()}
+     | {error, any()}
+
+handshake_continue(Socket0  :: socket(),
+                   SockOpts :: opts(),
+                   Timeout  :: timeout())
+    -> {ok, Socket :: socket()}
+     | {error, any()}
    +
    +

    Resume the paused transport-level handshake and return a socket that is ready to use.

    +

    This function will be called by connection processes to resume a paused handshake.

    +

    handshake_cancel

    +
    +
    handshake_cancel(Socket :: socket()) -> ok
    +
    +

    Cancel the paused transport-level handshake.

    listen

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

    Create a socket that listens on the port given in the socket options.

    The port may not be specified or may be set to 0, which means a random available port number will be chosen.

    messages

    -
    @@ -157,7 +192,7 @@ http://www.gnu.org/software/src-highlite -->

    Return the tuple keys for the messages sent by the socket.

    name

    -
    @@ -165,7 +200,7 @@ http://www.gnu.org/software/src-highlite -->

    Return the name of the transport.

    peername

    -
    @@ -176,7 +211,7 @@ http://www.gnu.org/software/src-highlite -->

    Return the address and port number for the other end of the connection.

    For UNIX Domain sockets the return value will be {local, PeerSocket}, with PeerSocket typically an empty binary.

    recv

    -
    @@ -191,7 +226,7 @@ http://www.gnu.org/software/src-highlite -->

    A length of 0 will return the data available on the socket as soon as possible, regardless of length.

    While it is possible to use the timeout value infinity, it is highly discouraged as it could cause your process to get stuck waiting for data that will never come. This may happen when a socket becomes half-open due to a crash of the remote endpoint. Wi-Fi going down is another common culprit.

    secure

    -
    @@ -199,7 +234,7 @@ http://www.gnu.org/software/src-highlite -->

    Return whether the transport can be used for secure connections.

    send

    -
    @@ -208,7 +243,7 @@ http://www.gnu.org/software/src-highlite -->

    Send a packet on the socket.

    sendfile

    -
    @@ -229,7 +264,7 @@ http://www.gnu.org/software/src-highlite -->

    The file may be sent full or in parts, and may be specified by its filename or by an already open file descriptor.

    Transports that manipulate TCP directly may use the file:sendfile/2,4,5 function, which calls the sendfile syscall where applicable (on Linux, for example). Other transports can use the sendfile/6 function exported from this module.

    setopts

    -
    @@ -238,7 +273,7 @@ http://www.gnu.org/software/src-highlite -->

    Set one or more options for the socket.

    shutdown

    -
    @@ -248,7 +283,7 @@ http://www.gnu.org/software/src-highlite -->

    Close the socket for reading and/or writing.

    sockname

    -
    @@ -265,7 +300,7 @@ http://www.gnu.org/software/src-highlite -->

    Types

    sendfile_opts()

    -
    @@ -277,7 +312,7 @@ http://www.gnu.org/software/src-highlite -->

    socket()

    -
    -- cgit v1.2.3