From f4c6da56d4fe9494f4fe23c48b8d7c3c1e9e6b42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sat, 22 Aug 2015 13:15:08 +0200 Subject: Convert the documentation to Asciidoc --- doc/src/guide/book.asciidoc | 20 +++ doc/src/guide/embedded.asciidoc | 48 ++++++ doc/src/guide/internals.asciidoc | 94 ++++++++++++ doc/src/guide/introduction.asciidoc | 25 ++++ doc/src/guide/listeners.asciidoc | 251 ++++++++++++++++++++++++++++++++ doc/src/guide/parsers.asciidoc | 92 ++++++++++++ doc/src/guide/protocols.asciidoc | 125 ++++++++++++++++ doc/src/guide/ssl_auth.asciidoc | 120 +++++++++++++++ doc/src/guide/transports.asciidoc | 169 +++++++++++++++++++++ doc/src/manual/ranch.asciidoc | 170 +++++++++++++++++++++ doc/src/manual/ranch_app.asciidoc | 27 ++++ doc/src/manual/ranch_protocol.asciidoc | 44 ++++++ doc/src/manual/ranch_ssl.asciidoc | 142 ++++++++++++++++++ doc/src/manual/ranch_tcp.asciidoc | 123 ++++++++++++++++ doc/src/manual/ranch_transport.asciidoc | 194 ++++++++++++++++++++++++ guide/embedded.md | 50 ------- guide/internals.md | 97 ------------ guide/introduction.md | 37 ----- guide/listeners.md | 240 ------------------------------ guide/parsers.md | 92 ------------ guide/protocols.md | 121 --------------- guide/ssl_auth.md | 118 --------------- guide/toc.md | 25 ---- guide/transports.md | 165 --------------------- manual/ranch.md | 182 ----------------------- manual/ranch_app.md | 28 ---- manual/ranch_protocol.md | 42 ------ manual/ranch_ssl.md | 135 ----------------- manual/ranch_tcp.md | 115 --------------- manual/ranch_transport.md | 205 -------------------------- manual/toc.md | 11 -- 31 files changed, 1644 insertions(+), 1663 deletions(-) create mode 100644 doc/src/guide/book.asciidoc create mode 100644 doc/src/guide/embedded.asciidoc create mode 100644 doc/src/guide/internals.asciidoc create mode 100644 doc/src/guide/introduction.asciidoc create mode 100644 doc/src/guide/listeners.asciidoc create mode 100644 doc/src/guide/parsers.asciidoc create mode 100644 doc/src/guide/protocols.asciidoc create mode 100644 doc/src/guide/ssl_auth.asciidoc create mode 100644 doc/src/guide/transports.asciidoc create mode 100644 doc/src/manual/ranch.asciidoc create mode 100644 doc/src/manual/ranch_app.asciidoc create mode 100644 doc/src/manual/ranch_protocol.asciidoc create mode 100644 doc/src/manual/ranch_ssl.asciidoc create mode 100644 doc/src/manual/ranch_tcp.asciidoc create mode 100644 doc/src/manual/ranch_transport.asciidoc delete mode 100644 guide/embedded.md delete mode 100644 guide/internals.md delete mode 100644 guide/introduction.md delete mode 100644 guide/listeners.md delete mode 100644 guide/parsers.md delete mode 100644 guide/protocols.md delete mode 100644 guide/ssl_auth.md delete mode 100644 guide/toc.md delete mode 100644 guide/transports.md delete mode 100644 manual/ranch.md delete mode 100644 manual/ranch_app.md delete mode 100644 manual/ranch_protocol.md delete mode 100644 manual/ranch_ssl.md delete mode 100644 manual/ranch_tcp.md delete mode 100644 manual/ranch_transport.md delete mode 100644 manual/toc.md diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc new file mode 100644 index 0000000..59e8e70 --- /dev/null +++ b/doc/src/guide/book.asciidoc @@ -0,0 +1,20 @@ +// a2x: --dblatex-opts "-P latex.output.revhistory=0 -P doc.publisher.show=0 -P index.numbered=0" +// a2x: -d book --attribute tabsize=4 + += Ranch User Guide + +include::introduction.asciidoc[Introduction] + +include::listeners.asciidoc[Listeners] + +include::transports.asciidoc[Transports] + +include::protocols.asciidoc[Protocols] + +include::embedded.asciidoc[Embedded mode] + +include::parsers.asciidoc[Writing parsers] + +include::ssl_auth.asciidoc[SSL client authentication] + +include::internals.asciidoc[Internals] diff --git a/doc/src/guide/embedded.asciidoc b/doc/src/guide/embedded.asciidoc new file mode 100644 index 0000000..593a807 --- /dev/null +++ b/doc/src/guide/embedded.asciidoc @@ -0,0 +1,48 @@ +== Embedded mode + +Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa. + +=== Embedding + +To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the `init/1` function +of one of your application supervisors. + +Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add `ranch_sup` to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener. + +Ranch has a convenience function for getting the listeners child specs +called `ranch:child_spec/6`, that works like `ranch:start_listener/6`, +except that it doesn't start anything, it only returns child specs. + +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 + +[source,erlang] +---- +init([]) -> + RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []}, + permanent, 5000, supervisor, [ranch_sup]}, + ListenerSpec = ranch:child_spec(echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] + ), + {ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}. +---- + +Remember, you can add as many listener child specs as needed, but only +one `ranch_sup` spec! + +It is recommended that your architecture makes sure that all listeners +are restarted if `ranch_sup` fails. See the Ranch internals chapter for +more details on how Ranch does it. diff --git a/doc/src/guide/internals.asciidoc b/doc/src/guide/internals.asciidoc new file mode 100644 index 0000000..fa63f1d --- /dev/null +++ b/doc/src/guide/internals.asciidoc @@ -0,0 +1,94 @@ +== Internals + +This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application. + +Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system. + +=== Architecture + +Ranch is an OTP application. + +Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the `ranch_server` process and all the listeners that +will be started. + +The `ranch_server` gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called `ranch_server`. The table is owned by the top supervisor +to improve fault tolerance. This way if the `ranch_server` gen_server +fails, it doesn't lose any information and the restarted process can +continue as if nothing happened. + +Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual `sys` and `supervisor` calls will work on +it as expected. + +Listeners are grouped into the `ranch_listener_sup` supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +`ranch_server` gen_server with varying amount of information. + +All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process. + +=== Number of acceptors + +The second argument to `ranch:start_listener/6` is the number of +processes that will be accepting connections. Care should be taken +when choosing this number. + +First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down. + +Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn't +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however. + +Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it's big enough to always have acceptors ready +and it's low enough that it doesn't have a negative impact on the +system's performances. + +=== Platform-specific TCP features + +Some socket options are platform-specific and not supported by `inet`. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the `raw` option, for which we will see an example. + +One of these features is `TCP_DEFER_ACCEPT` on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process. + +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 + +[source,erlang] +{raw, 6, 9, << 30:32/native >>} + +It means go on layer 6, turn on option 9 with the given integer parameter. diff --git a/doc/src/guide/introduction.asciidoc b/doc/src/guide/introduction.asciidoc new file mode 100644 index 0000000..3199fb2 --- /dev/null +++ b/doc/src/guide/introduction.asciidoc @@ -0,0 +1,25 @@ +== Introduction + +Ranch is a socket acceptor pool for TCP protocols. + +Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own. + +=== Prerequisites + +It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols. + +=== Supported platforms + +Ranch is tested and supported on Linux. + +Ranch is developed for Erlang R15B01+. + +Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected. + +=== Versioning + +Ranch uses http://semver.org/[Semantic Versioning 2.0.0] diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc new file mode 100644 index 0000000..ef2d49c --- /dev/null +++ b/doc/src/guide/listeners.asciidoc @@ -0,0 +1,251 @@ +== Listeners + +A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the user of transport handlers. + +The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application. + +=== Starting a listener + +Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections. + +A listener can be started and stopped at will. + +When starting a listener, a number of different settings are required: + +* A name to identify it locally and be able to interact with it. +* The number of acceptors in the pool. +* A transport handler and its associated options. +* A protocol handler and its associated options. + +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/6` +function. Before doing so however, you must ensure that the `ranch` +application is started. + +.Starting the Ranch application + +[source,erlang] +ok = application:start(ranch). + +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 + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] +). + +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 + +[source,bash] +$ make run + +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 + +[source,bash] +---- +$ telnet localhost 5555 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +Hello! +Hello! +It works! +It works! +^] + +telnet> quit +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 + +[source,erlang] +ranch:stop_listener(tcp_echo). + +=== Default transport options + +By default the socket will be set to return `binary` data, with the +options `{active, false}`, `{packet, raw}`, `{reuseaddr, true}` set. +These values can't be overriden when starting the listener, but +they can be overriden using `Transport:setopts/2` in the protocol. + +It will also set `{backlog, 1024}` and `{nodelay, true}`, which +can be overriden at listener startup. + +=== Listening on a random port + +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/6`. + +.Starting a listener for TCP connections on a random port + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 0}], + echo_protocol, [] +). +Port = ranch:get_port(tcp_echo). + +=== Listening on privileged ports + +Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an `{error, eacces}` error when trying +to open a listening socket on such a port. + +The methods for listening on privileged ports vary between systems, +please refer to your system's documentation for more information. + +We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide. + +=== Accepting connections on an existing socket + +If you want to accept connections on an existing socket, you can use the +`socket` transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(`gen_tcp:connect`, `ssl:connect`). The accept function will then be +called on the passed in socket. You should connect the socket in +`{active, false}` mode, as well. + +Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process. + +=== 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 + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}, {max_connections, 100}], + echo_protocol, [] +). + +You can disable this limit by setting its value to the atom `infinity`. + +.Disabling the limit for the number of connections + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}, {max_connections, infinity}], + echo_protocol, [] +). + +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 + +[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. + +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 + +[source,erlang] +ranch:set_max_connections(tcp_echo, MaxConns). + +The change will occur immediately. + +=== Using a supervisor for connection processes + +Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a `worker`. +When the `connection_type` configuration value is set to `supervisor`, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree. + +Connection processes of type `supervisor` can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket). + +Instead of returning `{ok, ConnPid}`, simply return +`{ok, SupPid, ConnPid}`. + +It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped. + +=== Upgrading + +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 + +[source,erlang] +ranch:set_protocol_options(tcp_echo, NewOpts). + +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 + +[source,erlang] +Opts = ranch:get_protocol_options(tcp_echo). diff --git a/doc/src/guide/parsers.asciidoc b/doc/src/guide/parsers.asciidoc new file mode 100644 index 0000000..9eacbfa --- /dev/null +++ b/doc/src/guide/parsers.asciidoc @@ -0,0 +1,92 @@ +== Writing parsers + +There are three kinds of protocols: + +* Text protocols +* Schema-less binary protocols +* Schema-based binary protocols + +This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators. + +This chapter isn't specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn't been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two. + +=== Parsing text + +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 + +[source,erlang] +case binary:split(Buffer, <<"\n">>) of + [_] -> + get_more_data(Buffer); + [Line, Rest] -> + handle_line(Line, Rest) +end. + +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 + +[source,erlang] +case binary:split(Line, <<" ">>, [global]) of + [<<"HELLO">>] -> + be_polite(); + [<<"AUTH">>, User, Password] -> + authenticate_user(User, Password); + [<<"QUIT">>, Reason] -> + quit(Reason) + %% ... +end. + +Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions. + +After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data. + +=== Parsing binary + +Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters. + +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 + +[source,erlang] +<< Size:32, _/bits >> = Buffer, +case Buffer of + << Frame:Size/binary, Rest/bits >> -> + handle_frame(Frame, Rest); + _ -> + get_more_data(Buffer) +end. + +You will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data. diff --git a/doc/src/guide/protocols.asciidoc b/doc/src/guide/protocols.asciidoc new file mode 100644 index 0000000..8060343 --- /dev/null +++ b/doc/src/guide/protocols.asciidoc @@ -0,0 +1,125 @@ +== Protocols + +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/6`. 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 + +[source,erlang] +ok = ranch:accept_ack(Ref). + +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 + +[source,erlang] +---- +-module(echo_protocol). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/4]). + +start_link(Ref, Socket, Transport, Opts) -> + Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]), + {ok, Pid}. + +init(Ref, Socket, Transport, _Opts = []) -> + ok = ranch:accept_ack(Ref), + loop(Socket, Transport). + +loop(Socket, Transport) -> + case Transport:recv(Socket, 0, 5000) of + {ok, Data} -> + Transport:send(Socket, Data), + loop(Socket, Transport); + _ -> + ok = Transport:close(Socket) + end. +---- + +=== Using gen_server + +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. + +There are two ways of solving this problem. + +The first, and probably the most elegant one, is to make use of 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 + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_server). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/4]). +%% Exports of other gen_server callbacks here. + +start_link(Ref, Socket, Transport, Opts) -> + proc_lib:start_link(?MODULE, init, [Ref, Socket, Transport, Opts]). + +init(Ref, Socket, Transport, _Opts = []) -> + ok = proc_lib:init_ack({ok, self()}), + %% Perform any required state initialization here. + ok = ranch:accept_ack(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + gen_server:enter_loop(?MODULE, [], {state, Socket, Transport}). + +%% Other gen_server callbacks here. +---- + +The second method involves triggering a timeout just after `gen_server:init` +ends. If you return a timeout value of `0` then the `gen_server` will call +`handle_info(timeout, _, _)` right away. + +.Use a gen_server for protocol handling, method 2 + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_server). +-behaviour(ranch_protocol). + +%% Exports go here. + +init([Ref, Socket, Transport]) -> + {ok, {state, Ref, Socket, Transport}, 0}. + +handle_info(timeout, State={state, Ref, Socket, Transport}) -> + ok = ranch:accept_ack(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + {noreply, State}; +%% ... +---- diff --git a/doc/src/guide/ssl_auth.asciidoc b/doc/src/guide/ssl_auth.asciidoc new file mode 100644 index 0000000..39f9c3c --- /dev/null +++ b/doc/src/guide/ssl_auth.asciidoc @@ -0,0 +1,120 @@ +== SSL client authentication + +=== Purpose + +SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security. + +The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate. + +As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of `Transport:name/0`. + +=== Obtaining client certificates + +You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free. + +Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser. + +* Open [CAcert.org](http://cacert.org) in your favorite browser +* Root Certificate link: install both certificates +* Join (Register an account) +* Verify your account (check your email inbox!) +* Log in +* Client Certificates: New +* Follow instructions to create the certificate +* Install the certificate in your browser + +You can optionally save the certificate for later use, for example +to extract the `IssuerID` information as will be detailed later on. + +=== 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 + +[source,erlang] +{ok, _} = ranch:start_listener(my_ssl, 100, + ranch_ssl, [ + {port, SSLPort}, + {certfile, PathToCertfile}, + {cacertfile, PathToCACertfile}, + {verify, verify_peer} + ], + my_protocol, [] +). + +In this example we set the required `port` and `certfile`, but also +the `cacertfile` containing the CACert.org root certificate, and +the option to request the client certificate. + +If you enable the `{verify, verify_peer}` option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients. + +=== 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 + +[source,erlang] +---- +certfile_to_issuer_id(Filename) -> + {ok, Data} = file:read_file(Filename), + [{'Certificate', Cert, not_encrypted}] = public_key:pem_decode(Data), + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID. +---- + +The `IssuerID` variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved. + +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 + +[source,erlang] +---- +socket_to_issuer_id(Socket) -> + case ssl:peercert(Socket) of + {error, no_peercert} -> + false; + {ok, Cert} -> + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID + end. +---- + +You then only need to match the `IssuerID` value to authenticate the +user. diff --git a/doc/src/guide/transports.asciidoc b/doc/src/guide/transports.asciidoc new file mode 100644 index 0000000..9195376 --- /dev/null +++ b/doc/src/guide/transports.asciidoc @@ -0,0 +1,169 @@ +== Transports + +A transport defines the interface to interact with a socket. + +Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive. + +=== TCP transport + +The TCP transport is a thin wrapper around `gen_tcp`. + +=== SSL transport + +The SSL transport is a thin wrapper around `ssl`. It requires +the `crypto`, `asn1`, `public_key` and `ssl` applications +to be started. When starting an SSL listener, Ranch will attempt +to automatically start them. It will not try to stop them when +the listener is removed, however. + +.Starting the SSL application + +[source,erlang] +ssl:start(). + +In a proper OTP setting, you will need to make your application +depend on the `crypto`, `public_key` and `ssl` applications. +They will be started automatically when starting your release. + +The SSL transport `accept/2` function performs both transport +and SSL accepts. Errors occurring during the SSL accept phase +are returned as `{error, {ssl_accept, atom()}}` to differentiate +on which socket the problem occurred. + +=== Sending and receiving data + +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 + +[source,erlang] +---- +Transport:send(Socket, <<"Ranch is cool!">>). +Transport:send(Socket, "Ranch is cool!"). +Transport:send(Socket, ["Ranch", ["is", "cool!"]]). +Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]). +---- + +You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking `Transport:recv/3` call, while +active mode means that you will receive the data as a message. + +By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols. + +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 + +[source,erlang] +{ok, Data} = Transport:recv(Socket, 0, 5000). + +Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it. + +There are two kinds of active modes: `{active, once}` and +`{active, true}`. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the `{active, true}` mode as it could quickly +flood your process mailbox. It's better to keep the data in the socket +and read it only when required. + +Three different messages can be received: + +* `{OK, Socket, Data}` +* `{Closed, Socket}` +* `{Error, Socket, Reason}` + +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 + +[source,erlang] +{OK, Closed, Error} = Transport:messages(). + +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 + +[source,erlang] +---- +{OK, Closed, Error} = Transport:messages(), +Transport:setopts(Socket, [{active, once}]), +receive + {OK, Socket, Data} -> + io:format("data received: ~p~n", [Data]); + {Closed, Socket} -> + io:format("socket got closed!~n"); + {Error, Socket, Reason} -> + io:format("error happened: ~p~n", [Reason]) +end. +---- + +You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages. + +=== Sending files + +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 + +[source,erlang] +{ok, SentBytes} = Transport:sendfile(Socket, Filename). + +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 + +[source,erlang] +Opts = [{chunk_size, ChunkSize}], +{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts). + +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 + +[source,erlang] +{ok, RawFile} = file:open(Filename, [raw, read, binary]), +{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts). + +=== Writing a transport handler + +A transport handler is a module implementing the `ranch_transport` behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler. + +The behavior doesn't define the socket options available when opening a +socket. These do not need to be common to all transports as it's easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The `setopts/2` function *must* +implement the `{active, once}` and the `{active, true}` options. + +If the transport handler doesn't have a native implementation of `sendfile/5` a +fallback is available, `ranch_transport:sendfile/6`. The extra first argument +is the transport's module. See `ranch_ssl` for an example. diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc new file mode 100644 index 0000000..f2e8a7d --- /dev/null +++ b/doc/src/manual/ranch.asciidoc @@ -0,0 +1,170 @@ += ranch(3) + +== Name + +ranch - socket acceptor pool + +== Description + +The `ranch` module provides functions for starting and +manipulating Ranch listeners. + +== Types + +=== max_conns() = non_neg_integer() | infinity + +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() + +[source,erlang] +---- +opt() = {ack_timeout, timeout()} + | {connection_type, worker | supervisor} + | {max_connections, max_conns()} + | {shutdown, timeout() | brutal_kill} + | {socket, any()} +---- + +Ranch-specific transport options. + +These options are not passed on to the transports. +They are used by Ranch while setting up the listeners. + +=== ref() = any() + +Unique name used to refer to a listener. + +== Option descriptions + +None of the options are required. + +ack_timeout (5000):: + Maximum allowed time for the `ranch:accept_ack/1` call to finish. +connection_type (worker):: + Type of process that will handle the connection. +max_connections (1024):: + Maximum number of active connections. Soft limit. Using `infinity` will disable the limit entirely. +shutdown (5000):: + Maximum allowed time for children to stop on listener shutdown. +socket:: + Listening socket opened externally to be used instead of calling `Transport:listen/1`. + +== Exports + +=== accept_ack(Ref) -> ok + +Ref = ref():: Listener name. + +Acknowledge that the connection is accepted. + +This function MUST be used by a connection process to inform +Ranch that it initialized properly and let it perform any +additional operations before the socket can be safely used. + +=== child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> supervisor:child_spec() + +Ref = ref():: Listener name. +NbAcceptors = non_neg_integer():: Number of acceptor processes. +Transport = module():: Transport module. +TransOpts = any():: Transport options. +Protocol = module():: Protocol module. +ProtoOpts = any():: Protocol options. + +Return child specifications for a new listener. + +This function can be used to embed a listener directly +in an application instead of letting Ranch handle it. + +=== get_max_connections(Ref) -> MaxConns + +Ref = ref():: Listener name. +MaxConns = max_conns():: Current maximum number of connections. + +Return the max number of connections allowed for the given listener. + +=== get_port(Ref) -> Port + +Ref = ref():: Listener name. +Port = inet:port_number():: Port number used by this listener. + +Return the port for the given listener. + +=== get_protocol_options(Ref) -> ProtoOpts + +Ref = ref():: Listener name. +ProtoOpts = any():: Current protocol options. + +Return the protocol options set for the given listener. + +=== remove_connection(Ref) -> ok + +Ref = ref():: Listener name. + +Do not count this connection when limiting the number of connections. + +You can use this function for long-running connection processes +which spend most of their time idling rather than consuming +resources. This allows Ranch to accept a lot more connections +without sacrificing the latency of the system. + +This function may only be called from a connection process. + +=== set_max_connections(Ref, MaxConns) -> ok + +Ref = ref():: Listener name. +MaxConns = max_conns():: New maximum number of connections. + +Set the max number of connections for the given listener. + +The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will not kill the extra +connections, but will wait for them to terminate properly. + +=== set_protocol_options(Ref, ProtoOpts) -> ok + +Ref = ref():: Listener name. +ProtoOpts = any():: New protocol options. + +Set the protocol options for the given listener. + +The change will be applied immediately for all new connections. +Old connections will not receive the new options. + +=== start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> {ok, pid()} | {error, badarg} + +Ref = ref():: Listener name. +NbAcceptors = non_neg_integer():: Number of acceptor processes. +Transport = module():: Transport module. +TransOpts = any():: Transport options. +Protocol = module():: Protocol module. +ProtoOpts = any():: Protocol options. + +Start listening for connections using the given transport +and protocol. Returns the pid for this listener's supervisor. + +There are additional transport options that apply +regardless of transport. They allow configuring how the +connections are supervised, rate limited and more. Please +consult the previous section for more details. + +=== stop_listener(Ref) -> ok | {error, not_found} + +Ref = ref():: Listener name. + +Stop the given listener. + +The listener is stopped gracefully, first by closing the +listening port, then by stopping the connection processes. +These processes are stopped according to the `shutdown` +transport option, which may be set to brutally kill all +connection processes or give them some time to stop properly. + +This function does not return until the listener is +completely stopped. diff --git a/doc/src/manual/ranch_app.asciidoc b/doc/src/manual/ranch_app.asciidoc new file mode 100644 index 0000000..2edfc72 --- /dev/null +++ b/doc/src/manual/ranch_app.asciidoc @@ -0,0 +1,27 @@ += ranch(7) + +== Name + +ranch - Socket acceptor pool for TCP protocols. + +== Dependencies + +The `ranch` application has no particular dependency required +to start. + +It has optional dependencies that are only required when +listening for SSL connections. The dependencies are `crypto`, +`asn1`, `public_key` and `ssl`. They are started automatically +if they weren't before. + +== Environment + +The `ranch` application defines one application environment +configuration parameter. + +profile (false):: + When enabled, Ranch will start `eprof` profiling automatically. + +You can use the `ranch_app:profile_output/0` function to stop +profiling and output the results to the files 'procs.profile' +and 'total.profile'. Do not use in production. diff --git a/doc/src/manual/ranch_protocol.asciidoc b/doc/src/manual/ranch_protocol.asciidoc new file mode 100644 index 0000000..714a82b --- /dev/null +++ b/doc/src/manual/ranch_protocol.asciidoc @@ -0,0 +1,44 @@ += ranch_protocol(3) + +== Name + +ranch_protocol - behaviour for protocol modules + +== Description + +The `ranch_protocol` behaviour defines the interface used +by Ranch protocols. + +== Types + +None. + +== Callbacks + +=== start_link(Ref, Socket, Transport, ProtoOpts) -> {ok, pid()} | {ok, pid(), pid()} + +Ref = ranch:ref():: Listener name. +Socket = any():: Socket for this connection. +Transport = module():: Transport module for this socket. +ProtoOpts = any():: Protocol options. + +Start a new connection process for the given socket. + +The only purpose of this callback is to start a process that +will handle the socket. It must spawn the process, link and +then return the new pid. This function will always be called +from inside a supervisor. + +This callback can also return two pids. The first pid is the +pid of the process that will be supervised. The second pid is +the pid of the process that will receive ownership of the +socket. This second process must be a child of the first. This +form is only available when `connection_type` is set to +`supervisor`. + +If any other value is returned, the supervisor will close the +socket and assume no process has been started. + +Do not perform any operations in this callback, as this would +block the supervisor responsible for starting connection +processes and degrade performance severely. diff --git a/doc/src/manual/ranch_ssl.asciidoc b/doc/src/manual/ranch_ssl.asciidoc new file mode 100644 index 0000000..55accad --- /dev/null +++ b/doc/src/manual/ranch_ssl.asciidoc @@ -0,0 +1,142 @@ += ranch_ssl(3) + +== Name + +ranch_ssl - SSL transport module + +== Description + +The `ranch_ssl` module implements an SSL Ranch transport. + +== Types + +=== ssl_opt() + +[source,erlang] +---- +ssl_opt() = {alpn_preferred_protocols, [binary()]} + | {cacertfile, string()} + | {cacerts, [public_key:der_encoded()]} + | {cert, public_key:der_encoded()} + | {certfile, string()} + | {ciphers, [ssl:erl_cipher_suite()] | string()} + | {client_renegotiation, boolean()} + | {crl_cache, {module(), {internal | any(), list()}}} + | {crl_check, boolean() | peer | best_effort} + | {depth, 0..255} + | {dh, public_key:der_encoded()} + | {dhfile, string()} + | {fail_if_no_peer_cert, boolean()} + | {hibernate_after, integer() | undefined} + | {honor_cipher_order, boolean()} + | {key, {'RSAPrivateKey' | 'DSAPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}} + | {keyfile, string()} + | {log_alert, boolean()} + | {next_protocols_advertised, [binary()]} + | {partial_chain, fun(([public_key:der_encoded()]) -> {trusted_ca, public_key:der_encoded()} | unknown_ca)} + | {password, string()} + | {psk_identity, string()} + | {reuse_session, fun()} + | {reuse_sessions, boolean()} + | {secure_renegotiate, boolean()} + | {sni_fun, fun()} + | {sni_hosts, [{string(), ssl_opt()}]} + | {user_lookup_fun, {fun(), any()}} + | {verify, ssl:verify_type()} + | {verify_fun, {fun(), any()}} + | {versions, [atom()]}. +---- + +SSL-specific listen options. + +=== opt() = ranch_tcp:opt() | ssl_opt() + +Listen options. + +=== opts() = [opt()] + +List of listen options. + +== Option descriptions + +Specifying a certificate is mandatory, either through the `cert` +or the `certfile` option. None of the other options are required. + +The default value is given next to the option name. + +alpn_preferred_protocols:: + Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. +cacertfile:: + Path to PEM encoded trusted certificates file used to verify peer certificates. +cacerts:: + List of DER encoded trusted certificates. +cert:: + DER encoded user certificate. +certfile:: + Path to the PEM encoded user certificate file. May also contain the private key. +ciphers:: + List of ciphers that clients are allowed to use. +client_renegotiation (true):: + Whether to allow client-initiated renegotiation. +crl_cache ({ssl_crl_cache, {internal, []}}):: + Customize the module used to cache Certificate Revocation Lists. +crl_check (false):: + Whether to perform CRL check on all certificates in the chain during validation. +depth (1):: + Maximum of intermediate certificates allowed in the certification path. +dh:: + DER encoded Diffie-Hellman parameters. +dhfile:: + Path to the PEM encoded Diffie-Hellman parameters file. +fail_if_no_peer_cert (false):: + Whether to refuse the connection if the client sends an empty certificate. +hibernate_after (undefined):: + Time in ms after which SSL socket processes go into hibernation to reduce memory usage. +honor_cipher_order (false):: + If true, use the server's preference for cipher selection. If false, use the client's preference. +key:: + DER encoded user private key. +keyfile:: + Path to the PEM encoded private key file, if different than the certfile. +log_alert (true):: + If false, error reports will not be displayed. +next_protocols_advertised:: + List of protocols to send to the client if it supports the Next Protocol extension. +nodelay (true):: + Whether to enable TCP_NODELAY. +partial_chain:: + Claim an intermediate CA in the chain as trusted. +password:: + Password to the private key file, if password protected. +psk_identity:: + Provide the given PSK identity hint to the client during the handshake. +reuse_session:: + Custom policy to decide whether a session should be reused. +reuse_sessions (false):: + Whether to allow session reuse. +secure_renegotiate (false):: + Whether to reject renegotiation attempts that do not conform to RFC5746. +sni_fun:: + Function called when the client requests a host using Server Name Indication. Returns options to apply. +sni_hosts:: + Options to apply for the host that matches what the client requested with Server Name Indication. +user_lookup_fun:: + Function called to determine the shared secret when using PSK, or provide parameters when using SRP. +verify (verify_none):: + Use `verify_peer` to request a certificate from the client. +verify_fun:: + Custom policy to decide whether a client certificate is valid. +versions:: + TLS protocol versions that will be supported. + +Note that the client will not send a certificate unless the +value for the `verify` option is set to `verify_peer`. This +means that the `fail_if_no_peer_cert` only apply when combined +with the `verify` option. The `verify_fun` option allows +greater control over the client certificate validation. + +The options `sni_fun` and `sni_hosts` are mutually exclusive. + +== Exports + +None. diff --git a/doc/src/manual/ranch_tcp.asciidoc b/doc/src/manual/ranch_tcp.asciidoc new file mode 100644 index 0000000..1fc268d --- /dev/null +++ b/doc/src/manual/ranch_tcp.asciidoc @@ -0,0 +1,123 @@ += ranch_tcp(3) + +== Name + +ranch_tcp - TCP transport module + +== Description + +The `ranch_tcp` module implements a TCP Ranch transport. + +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() + +[source,erlang] +---- +opt() = {backlog, non_neg_integer()} + | {buffer, non_neg_integer()} + | {delay_send, boolean()} + | {dontroute, boolean()} + | {exit_on_close, boolean()} + | {fd, non_neg_integer()} + | {high_msgq_watermark, non_neg_integer()} + | {high_watermark, non_neg_integer()} + | inet + | inet6 + | {ip, inet:ip_address()} + | {keepalive, boolean()} + | {linger, {boolean(), non_neg_integer()}} + | {low_msgq_watermark, non_neg_integer()} + | {low_watermark, non_neg_integer()} + | {nodelay, boolean()} + | {port, inet:port_number()} + | {priority, integer()} + | {raw, non_neg_integer(), non_neg_integer(), binary()} + | {recbuf, non_neg_integer()} + | {send_timeout, timeout()} + | {send_timeout_close, boolean()} + | {sndbuf, non_neg_integer()} + | {tos, integer()} +---- + +Listen options. + +This does not represent the entirety of the options that can +be set on the socket, but only the options that may be +set independently of protocol implementation. + +=== opts() = [opt()] + +List of listen options. + +Option descriptions +------------------- + +None of the options are required. + +Please consult the `gen_tcp` and `inet` manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to `gen_tcp`. +Defaults are given next to the option name. + +backlog (1024):: + Max length of the queue of pending connections. +buffer:: + Size of the buffer used by the Erlang driver. Default is system-dependent. +delay_send (false):: + Always queue packets before sending, to send fewer, larger packets over the network. +dontroute (false):: + Don't send via a gateway, only send to directly connected hosts. +exit_on_close (true):: + Disable to allow sending data after a close has been detected. +fd:: + File descriptor of the socket, if it was opened externally. +high_msgq_watermark (8192):: + Limit in the amount of data in the socket message queue before the socket queue becomes busy. +high_watermark (8192):: + Limit in the amount of data in the ERTS socket implementation's queue before the socket becomes busy. +inet:: + Set up the socket for IPv4. +inet6:: + Set up the socket for IPv6. +ip:: + Interface to listen on. Listen on all interfaces by default. +keepalive (false):: + Enable sending of keep-alive messages. +linger ({false, 0}):: + Whether to wait and how long to flush data sent before closing the socket. +low_msgq_watermark (4096):: + Amount of data in the socket message queue before the socket queue leaves busy state. +low_watermark (4096):: + Amount of data in the ERTS socket implementation's queue before the socket leaves busy state. +nodelay (true):: + Whether to enable TCP_NODELAY. +port (0):: + TCP port number to listen on. 0 means a random port will be used. +priority (0):: + Priority value for all packets to be sent by this socket. +recbuf:: + Minimum size of the socket's receive buffer. Default is system-dependent. +send_timeout (30000):: + How long the send call may wait for confirmation before returning. +send_timeout_close (true):: + Whether to close the socket when the confirmation wasn't received. +sndbuf:: + Minimum size of the socket's send buffer. Default is system-dependent. +tos:: + Value for the IP_TOS IP level option. Use with caution. + +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. + +== Exports + +None. diff --git a/doc/src/manual/ranch_transport.asciidoc b/doc/src/manual/ranch_transport.asciidoc new file mode 100644 index 0000000..a9322f4 --- /dev/null +++ b/doc/src/manual/ranch_transport.asciidoc @@ -0,0 +1,194 @@ += ranch_transport(3) + +== Name + +ranch_transport - behaviour for transport modules + +== Description + +The `ranch_transport` behaviour defines the interface used +by Ranch transports. + +== Types + +=== sendfile_opts() = [{chunk_size, non_neg_integer()}] + +Options used by the sendfile function and callbacks. + +Allows configuring the chunk size, in bytes. Defaults to 8191 bytes. + +== Callbacks + +=== accept(LSocket, Timeout) -> {ok, CSocket} | {error, closed | timeout | atom()} + +LSocket = CSocket = any():: Listening socket. +Timeout = timeout():: Accept timeout. + +Accept a connection on the given listening socket. + +The `accept_ack` callback will be used to initialize the socket +after accepting the connection. This is most useful when the +transport is not raw TCP, like with SSL for example. + +=== accept_ack(CSocket, Timeout) -> ok + +CSocket = any():: Socket for this connection. +Timeout = timeout():: Ack timeout. + +Perform post-accept initialization of the connection. + +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 make the socket ready to use. + +=== close(Socket) -> ok + +Socket = any():: Socket opened with listen/1 or accept/2. + +Close the given socket. + +=== controlling_process(Socket, Pid) -> ok | {error, closed | not_owner | atom()} + +Socket = any():: Socket opened with listen/1 or accept/2. +Pid = pid():: Pid of the new owner of the socket. + +Change the controlling process for the given socket. + +The controlling process is the process that is allowed to +perform operations on the socket, and that will receive +messages from the socket when active mode is used. When +the controlling process dies, the socket is closed. + +=== listen(TransOpts) -> {ok, LSocket} | {error, atom()} + +TransOpts = any():: Transport options. +LSocket = any():: Listening socket. + +Listen for connections on the given port. + +The port is given as part of the transport options under +the key `port`. Any other option is transport dependent. + +The socket returned by this call can then be used to +accept connections. It is not possible to send or receive +data from the listening socket. + +=== messages() -> {OK, Closed, Error} + +OK = Closed = Error = atom():: Tuple names. + +Return the atoms used to identify messages sent in active mode. + +=== name() -> Name + +Name = atom():: Transport module name. + +Return the name of the transport. + +=== peername(CSocket) -> {ok, {IP, Port}} | {error, atom()} + +CSocket = any():: Socket for this connection. +IP = inet:ip_address():: IP of the remote endpoint. +Port = inet:port_number():: Port of the remote endpoint. + +Return the IP and port of the remote endpoint. + +=== recv(CSocket, Length, Timeout) -> {ok, Packet} | {error, closed | timeout | atom()} + +CSocket = any():: Socket for this connection. +Length = non_neg_integer():: Requested length. +Timeout = timeout():: Receive timeout. +Packet = iodata() | any():: Data received. + +Receive data from the given socket when in passive mode. + +Trying to receive data from a socket that is in active mode +will return an error. + +A length of 0 will return any data available on the socket. + +While it is possible to use the timeout value `infinity`, +this is highly discouraged as this 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 +of this issue. + +=== send(CSocket, Packet) -> ok | {error, atom()} + +CSocket = any():: Socket for this connection. +Packet = iodata():: Data to be sent. + +Send data to the given socket. + +=== sendfile(CSocket, File) -> sendfile(CSocket, File, 0, 0, []) + +Alias of `ranch_transport:sendfile/5`. + +=== sendfile(CSocket, File, Offset, Bytes) -> sendfile(CSocket, File, Offset, Bytes, []) + +Alias of `ranch_transport:sendfile/5`. + +=== sendfile(CSocket, File, Offset, Bytes, SfOpts) -> {ok, SentBytes} | {error, atom()} + +CSocket = any():: Socket for this connection. +File = file:filename_all() | file:fd():: Filename or file descriptor for the file to be sent. +Offset = non_neg_integer():: Begin sending at this position in the file. +Bytes = non_neg_integer():: Send this many bytes. +SentBytes = non_neg_integer():: This many bytes were sent. +SfOpts = sendfile_opts():: Sendfile options. + +Send data from a file to the given socket. + +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(CSocket, SockOpts) -> ok | {error, atom()} + +CSocket = any():: Socket for this connection. +SockOpts = any():: Socket options. + +Change options for the given socket. + +This is mainly useful for switching to active or passive mode +or to set protocol-specific options. + +=== shutdown(CSocket, How) -> ok | {error, atom()} + +CSocket = any():: Socket for this connection. +How = read | write | read_write:: Which side(s) of the socket to close. + +Immediately close the socket in one or two directions. + +=== sockname(Socket) -> {ok, {IP, Port}} | {error, atom()} + +Socket = any():: Socket opened with listen/1 or accept/2. +IP = inet:ip_address():: IP of the local endpoint. +Port = inet:port_number():: Port of the local endpoint. + +Return the IP and port of the local endpoint. + +== Exports + +=== sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) -> {ok, SentBytes} | {error, atom()} + +Transport = module():: Transport module for this socket. +CSocket = any():: Socket for this connection. +File = file:filename_all() | file:fd():: Filename or file descriptor for the file to be sent. +Offset = non_neg_integer():: Begin sending at this position in the file. +Bytes = non_neg_integer():: Send this many bytes. +SentBytes = non_neg_integer():: This many bytes were sent. +SfOpts = sendfile_opts():: Sendfile options. + +Send data from a file to the given socket. + +This function emulates the function `file:sendfile/{2,4,5}` +and may be used when transports are not manipulating TCP +directly. diff --git a/guide/embedded.md b/guide/embedded.md deleted file mode 100644 index 6cac064..0000000 --- a/guide/embedded.md +++ /dev/null @@ -1,50 +0,0 @@ -Embedded mode -============= - -Purpose -------- - -Embedded mode allows you to insert Ranch listeners directly -in your supervision tree. This allows for greater fault tolerance -control by permitting the shutdown of a listener due to the -failure of another part of the application and vice versa. - -Embedding ---------- - -To embed Ranch in your application you can simply add the child specs -to your supervision tree. This can all be done in the `init/1` function -of one of your application supervisors. - -Ranch requires at the minimum two kinds of child specs for embedding. -First, you need to add `ranch_sup` to your supervision tree, only once, -regardless of the number of listeners you will use. Then you need to -add the child specs for each listener. - -Ranch has a convenience function for getting the listeners child specs -called `ranch:child_spec/6`, that works like `ranch:start_listener/6`, -except that it doesn't start anything, it only returns child specs. - -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. - -``` erlang -init([]) -> - RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []}, - permanent, 5000, supervisor, [ranch_sup]}, - ListenerSpec = ranch:child_spec(echo, 100, - ranch_tcp, [{port, 5555}], - echo_protocol, [] - ), - {ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}. -``` - -Remember, you can add as many listener child specs as needed, but only -one `ranch_sup` spec! - -It is recommended that your architecture makes sure that all listeners -are restarted if `ranch_sup` fails. See the Ranch internals chapter for -more details on how Ranch does it. diff --git a/guide/internals.md b/guide/internals.md deleted file mode 100644 index 03977c1..0000000 --- a/guide/internals.md +++ /dev/null @@ -1,97 +0,0 @@ -Internals -========= - -This chapter may not apply to embedded Ranch as embedding allows you -to use an architecture specific to your application, which may or may -not be compatible with the description of the Ranch application. - -Note that for everything related to efficiency and performance, -you should perform the benchmarks yourself to get the numbers that -matter to you. Generic benchmarks found on the web may or may not -be of use to you, you can never know until you benchmark your own -system. - -Architecture ------------- - -Ranch is an OTP application. - -Like all OTP applications, Ranch has a top supervisor. It is responsible -for supervising the `ranch_server` process and all the listeners that -will be started. - -The `ranch_server` gen_server is a central process keeping track of the -listeners and their acceptors. It does so through the use of a public ets -table called `ranch_server`. The table is owned by the top supervisor -to improve fault tolerance. This way if the `ranch_server` gen_server -fails, it doesn't lose any information and the restarted process can -continue as if nothing happened. - -Ranch uses a custom supervisor for managing connections. This supervisor -keeps track of the number of connections and handles connection limits -directly. While it is heavily optimized to perform the task of creating -connection processes for accepted connections, it is still following the -OTP principles and the usual `sys` and `supervisor` calls will work on -it as expected. - -Listeners are grouped into the `ranch_listener_sup` supervisor and -consist of three kinds of processes: the listener gen_server, the -acceptor processes and the connection processes, both grouped under -their own supervisor. All of these processes are registered to the -`ranch_server` gen_server with varying amount of information. - -All socket operations, including listening for connections, go through -transport handlers. Accepted connections are given to the protocol handler. -Transport handlers are simple callback modules for performing operations on -sockets. Protocol handlers start a new process, which receives socket -ownership, with no requirements on how the code should be written inside -that new process. - -Number of acceptors -------------------- - -The second argument to `ranch:start_listener/6` is the number of -processes that will be accepting connections. Care should be taken -when choosing this number. - -First of all, it should not be confused with the maximum number -of connections. Acceptor processes are only used for accepting and -have nothing else in common with connection processes. Therefore -there is nothing to be gained from setting this number too high, -in fact it can slow everything else down. - -Second, this number should be high enough to allow Ranch to accept -connections concurrently. But the number of cores available doesn't -seem to be the only factor for choosing this number, as we can -observe faster accepts if we have more acceptors than cores. It -might be entirely dependent on the protocol, however. - -Our observations suggest that using 100 acceptors on modern hardware -is a good solution, as it's big enough to always have acceptors ready -and it's low enough that it doesn't have a negative impact on the -system's performances. - -Platform-specific TCP features ------------------------------- - -Some socket options are platform-specific and not supported by `inet`. -They can be of interest because they generally are related to -optimizations provided by the underlying OS. They can still be enabled -thanks to the `raw` option, for which we will see an example. - -One of these features is `TCP_DEFER_ACCEPT` on Linux. It is a simplified -accept mechanism which will wait for application data to come in before -handing out the connection to the Erlang process. - -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. - -``` erlang - {raw, 6, 9, << 30:32/native >>} -``` - -It means go on layer 6, turn on option 9 with the given integer parameter. diff --git a/guide/introduction.md b/guide/introduction.md deleted file mode 100644 index 9cb5f15..0000000 --- a/guide/introduction.md +++ /dev/null @@ -1,37 +0,0 @@ -Introduction -============ - -Purpose -------- - -Ranch is a socket acceptor pool for TCP protocols. - -Ranch aims to provide everything you need to accept TCP connections -with a small code base and low latency while being easy to use directly -as an application or to embed into your own. - -Prerequisites -------------- - -It is assumed the developer already knows Erlang and has some experience -with socket programming and TCP protocols. - -Supported platforms -------------------- - -Ranch is tested and supported on Linux. - -Ranch has been reported to work on other platforms, but we make no -guarantee that the experience will be safe and smooth. You are advised -to perform the necessary testing and security audits prior to deploying -on other platforms. - -Ranch is developed for Erlang R15B01 and later versions. - -Ranch may be compiled on earlier Erlang versions with small source code -modifications but there is no guarantee that it will work as expected. - -Versioning ----------- - -Ranch uses [Semantic Versioning 2.0.0](http://semver.org/). diff --git a/guide/listeners.md b/guide/listeners.md deleted file mode 100644 index d2f7eed..0000000 --- a/guide/listeners.md +++ /dev/null @@ -1,240 +0,0 @@ -Listeners -========= - -Purpose -------- - -A listener is a set of processes whose role is to listen on a port -for new connections. It manages a pool of acceptor processes, each -of them indefinitely accepting connections. When it does, it starts -a new process executing the protocol handler code. All the socket -programming is abstracted through the user of transport handlers. - -The listener takes care of supervising all the acceptor and connection -processes, allowing developers to focus on building their application. - -Starting and stopping ---------------------- - -Ranch does nothing by default. It is up to the application developer -to request that Ranch listens for connections. - -A listener can be started and stopped at will. - -When starting a listener, a number of different settings are required: - * A name to identify it locally and be able to interact with it. - * The number of acceptors in the pool. - * A transport handler and its associated options. - * A protocol handler and its associated options. - -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/6` -function. Before doing so however, you must ensure that the `ranch` -application is started. - -To start the `ranch` application: - -``` erlang -ok = application:start(ranch). -``` - -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. - -``` erlang -{ok, _} = ranch:start_listener(tcp_echo, 100, - ranch_tcp, [{port, 5555}], - echo_protocol, [] -). -``` - -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 commands: - -``` bash -$ make -$ ./_rel/bin/tcp_echo console -``` - -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. - -``` -$ telnet localhost 5555 -Trying 127.0.0.1... -Connected to localhost. -Escape character is '^]'. -Hello! -Hello! -It works! -It works! -^] - -telnet> quit -Connection closed. -``` - -Default transport options -------------------------- - -By default the socket will be set to return `binary` data, with the -options `{active, false}`, `{packet, raw}`, `{reuseaddr, true}` set. -These values can't be overriden when starting the listener, but -they can be overriden using `Transport:setopts/2` in the protocol. - -It will also set `{backlog, 1024}` and `{nodelay, true}`, which -can be overriden at listener startup. - -Listening on a random port --------------------------- - -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/6`. - -``` erlang -{ok, _} = ranch:start_listener(tcp_echo, 100, - ranch_tcp, [{port, 0}], - echo_protocol, [] -). -Port = ranch:get_port(tcp_echo). -``` - -Listening on privileged ports ------------------------------ - -Some systems limit access to ports below 1024 for security reasons. -This can easily be identified by an `{error, eacces}` error when trying -to open a listening socket on such a port. - -The methods for listening on privileged ports vary between systems, -please refer to your system's documentation for more information. - -We recommend the use of port rewriting for systems with a single server, -and load balancing for systems with multiple servers. Documenting these -solutions is however out of the scope of this guide. - -Accepting connections on an existing socket -------------------------------------------- - -If you want to accept connections on an existing socket, you can use the -`socket` transport option, which should just be the relevant data returned -from the connect function for the transport or the underlying socket library -(`gen_tcp:connect`, `ssl:connect`). The accept function will then be -called on the passed in socket. You should connect the socket in -`{active, false}` mode, as well. - -Note, however, that because of a bug in SSL, you cannot change ownership of an -SSL listen socket prior to R16. Ranch will catch the error thrown, but the -owner of the SSL socket will remain as whatever process created the socket. -However, this will not affect accept behaviour unless the owner process dies, -in which case the socket is closed. Therefore, to use this feature with SSL -with an erlang release prior to R16, ensure that the SSL socket is opened in a -persistant process. - -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. - -``` erlang -{ok, _} = ranch:start_listener(tcp_echo, 100, - ranch_tcp, [{port, 5555}, {max_connections, 100}], - echo_protocol, [] -). -``` - -You can disable this limit by setting its value to the atom `infinity`. - -``` erlang -{ok, _} = ranch:start_listener(tcp_echo, 100, - ranch_tcp, [{port, 5555}, {max_connections, infinity}], - echo_protocol, [] -). -``` - -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. - -``` 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. - -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. - -``` erlang -ranch:set_max_connections(tcp_echo, MaxConns). -``` - -The change will occur immediately. - -Using a supervisor for connection processes -------------------------------------------- - -Ranch allows you to define the type of process that will be used -for the connection processes. By default it expects a `worker`. -When the `connection_type` configuration value is set to `supervisor`, -Ranch will consider that the connection process it manages is a -supervisor and will reflect that in its supervision tree. - -Connection processes of type `supervisor` can either handle the -socket directly or through one of their children. In the latter -case the start function for the connection process must return -two pids: the pid of the supervisor you created (that will be -supervised) and the pid of the protocol handling process (that -will receive the socket). - -Instead of returning `{ok, ConnPid}`, simply return -`{ok, SupPid, ConnPid}`. - -It is very important that the connection process be created -under the supervisor process so that everything works as intended. -If not, you will most likely experience issues when the supervised -process is stopped. - -Upgrading ---------- - -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. - -``` erlang -ranch:set_protocol_options(tcp_echo, NewOpts). -``` - -All future connections will use the new options. - -You can also retrieve the current options similarly by -calling `ranch:get_protocol_options/1`. - -``` erlang -Opts = ranch:get_protocol_options(tcp_echo). -``` diff --git a/guide/parsers.md b/guide/parsers.md deleted file mode 100644 index c38af0c..0000000 --- a/guide/parsers.md +++ /dev/null @@ -1,92 +0,0 @@ -Writing parsers -=============== - -There are three kinds of protocols: - - * Text protocols - * Schema-less binary protocols - * Schema-based binary protocols - -This chapter introduces the first two kinds. It will not cover -more advanced topics such as continuations or parser generators. - -This chapter isn't specifically about Ranch, we assume here that -you know how to read data from the socket. The data you read and -the data that hasn't been parsed is saved in a buffer. Every -time you read from the socket, the data read is appended to the -buffer. What happens next depends on the kind of protocol. We -will only cover the first two. - -Parsing text ------------- - -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}`. - -``` erlang -case binary:split(Buffer, <<"\n">>) of - [_] -> - get_more_data(Buffer); - [Line, Rest] -> - handle_line(Line, Rest) -end. -``` - -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. - -``` erlang -case binary:split(Line, <<" ">>, [global]) of - [<<"HELLO">>] -> - be_polite(); - [<<"AUTH">>, User, Password] -> - authenticate_user(User, Password); - [<<"QUIT">>, Reason] -> - quit(Reason) - %% ... -end. -``` - -Pretty simple, right? Match on the command name, get the rest -of the tokens in variables and call the respective functions. - -After doing this, you will want to check if there is another -line in the buffer, and handle it immediately if any. -Otherwise wait for more data. - -Parsing binary --------------- - -Binary protocols can be more varied, although most of them are -pretty similar. The first four bytes of a frame tend to be -the size of the frame, which is followed by a certain number -of bytes for the type of frame and then various parameters. - -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. - -``` erlang -<< Size:32, _/bits >> = Buffer, -case Buffer of - << Frame:Size/binary, Rest/bits >> -> - handle_frame(Frame, Rest); - _ -> - get_more_data(Buffer) -end. -``` - -You will then need to parse this frame using binary pattern -matching, and handle it. Then you will want to check if there -is another frame fully received in the buffer, and handle it -immediately if any. Otherwise wait for more data. diff --git a/guide/protocols.md b/guide/protocols.md deleted file mode 100644 index 0cf0dc1..0000000 --- a/guide/protocols.md +++ /dev/null @@ -1,121 +0,0 @@ -Protocols -========= - -Purpose -------- - -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/6`. 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. - -``` erlang -ok = ranch:accept_ack(Ref). -``` - -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/`. - -``` erlang --module(echo_protocol). --behaviour(ranch_protocol). - --export([start_link/4]). --export([init/4]). - -start_link(Ref, Socket, Transport, Opts) -> - Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]), - {ok, Pid}. - -init(Ref, Socket, Transport, _Opts = []) -> - ok = ranch:accept_ack(Ref), - loop(Socket, Transport). - -loop(Socket, Transport) -> - case Transport:recv(Socket, 0, 5000) of - {ok, Data} -> - Transport:send(Socket, Data), - loop(Socket, Transport); - _ -> - ok = Transport:close(Socket) - end. -``` - -Using gen_server ----------------- - -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. - -There are two ways of solving this problem. - -The first, and probably the most elegant one, is to make use of 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. - -``` erlang --module(my_protocol). --behaviour(gen_server). --behaviour(ranch_protocol). - --export([start_link/4]). --export([init/4]). -%% Exports of other gen_server callbacks here. - -start_link(Ref, Socket, Transport, Opts) -> - proc_lib:start_link(?MODULE, init, [Ref, Socket, Transport, Opts]). - -init(Ref, Socket, Transport, _Opts = []) -> - ok = proc_lib:init_ack({ok, self()}), - %% Perform any required state initialization here. - ok = ranch:accept_ack(Ref), - ok = Transport:setopts(Socket, [{active, once}]), - gen_server:enter_loop(?MODULE, [], {state, Socket, Transport}). - -%% Other gen_server callbacks here. -``` - -The second method involves triggering a timeout just after `gen_server:init` -ends. If you return a timeout value of `0` then the `gen_server` will call -`handle_info(timeout, _, _)` right away. - -``` erlang --module(my_protocol). --behaviour(gen_server). --behaviour(ranch_protocol). - -%% Exports go here. - -init([Ref, Socket, Transport]) -> - {ok, {state, Ref, Socket, Transport}, 0}. - -handle_info(timeout, State={state, Ref, Socket, Transport}) -> - ok = ranch:accept_ack(Ref), - ok = Transport:setopts(Socket, [{active, once}]), - {noreply, State}; -%% ... -``` diff --git a/guide/ssl_auth.md b/guide/ssl_auth.md deleted file mode 100644 index f9a4812..0000000 --- a/guide/ssl_auth.md +++ /dev/null @@ -1,118 +0,0 @@ -SSL client authentication -========================= - -Purpose -------- - -SSL client authentication is a mechanism allowing applications to -identify certificates. This allows your application to make sure that -the client is an authorized certificate, but makes no claim about -whether the user can be trusted. This can be combined with a password -based authentication to attain greater security. - -The server only needs to retain the certificate serial number and -the certificate issuer to authenticate the certificate. Together, -they can be used to uniquely identify a certicate. - -As Ranch allows the same protocol code to be used for both SSL and -non-SSL transports, you need to make sure you are in an SSL context -before attempting to perform an SSL client authentication. This -can be done by checking the return value of `Transport:name/0`. - -Obtaining client certificates ------------------------------ - -You can obtain client certificates from various sources. You can -generate them yourself, or you can use a service like CAcert.org -which allows you to generate client and server certificates for -free. - -Following are the steps you need to take to create a CAcert.org -account, generate a certificate and install it in your favorite -browser. - - * Open [CAcert.org](http://cacert.org) in your favorite browser - * Root Certificate link: install both certificates - * Join (Register an account) - * Verify your account (check your email inbox!) - * Log in - * Client Certificates: New - * Follow instructions to create the certificate - * Install the certificate in your browser - -You can optionally save the certificate for later use, for example -to extract the `IssuerID` information as will be detailed later on. - -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. - -``` erlang -{ok, _} = ranch:start_listener(my_ssl, 100, - ranch_ssl, [ - {port, SSLPort}, - {certfile, PathToCertfile}, - {cacertfile, PathToCACertfile}, - {verify, verify_peer} - ], - my_protocol, [] -). -``` - -In this example we set the required `port` and `certfile`, but also -the `cacertfile` containing the CACert.org root certificate, and -the option to request the client certificate. - -If you enable the `{verify, verify_peer}` option and the client does -not have a client certificate configured for your domain, then no -certificate will be sent. This allows you to use SSL for more than -just authenticated clients. - -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. - -``` erlang -certfile_to_issuer_id(Filename) -> - {ok, Data} = file:read_file(Filename), - [{'Certificate', Cert, not_encrypted}] = public_key:pem_decode(Data), - {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), - IssuerID. -``` - -The `IssuerID` variable contains both the certificate serial number -and the certificate issuer stored in a tuple, so this value alone can -be used to uniquely identify the user certificate. You can save this -value in a database, a configuration file or any other place where an -Erlang term can be stored and retrieved. - -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. - -``` erlang -socket_to_issuer_id(Socket) -> - case ssl:peercert(Socket) of - {error, no_peercert} -> - false; - {ok, Cert} -> - {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), - IssuerID - end. -``` - -You then only need to match the `IssuerID` value to authenticate the -user. diff --git a/guide/toc.md b/guide/toc.md deleted file mode 100644 index 4f17a22..0000000 --- a/guide/toc.md +++ /dev/null @@ -1,25 +0,0 @@ -Ranch User Guide -================ - -The Ranch User Guide explores how to make best use of Ranch -for writing powerful TCP applications. - -Introducing Ranch ------------------ - - * [Introduction](introduction.md) - -Using Ranch ------------ - - * [Listeners](listeners.md) - * [Transports](transports.md) - * [Protocols](protocols.md) - * [Writing parsers](parsers.md) - -Advanced topics ---------------- - - * [SSL client authentication](ssl_auth.md) - * [Embedded mode](embedded.md) - * [Internals](internals.md) diff --git a/guide/transports.md b/guide/transports.md deleted file mode 100644 index 5c26c51..0000000 --- a/guide/transports.md +++ /dev/null @@ -1,165 +0,0 @@ -Transports -========== - -Purpose -------- - -A transport defines the interface to interact with a socket. - -Transports can be used for connecting, listening and accepting -connections, but also for receiving and sending data. Both -passive and active mode are supported, although all sockets -are initialized as passive. - -TCP transport -------------- - -The TCP transport is a thin wrapper around `gen_tcp`. - -SSL transport -------------- - -The SSL transport is a thin wrapper around `ssl`. It requires -the `crypto`, `asn1`, `public_key` and `ssl` applications -to be started. When starting an SSL listener, Ranch will attempt -to automatically start them. It will not try to stop them when -the listener is removed, however. - -``` erlang -ssl:start(). -``` - -In a proper OTP setting, you will need to make your application -depend on the `crypto`, `public_key` and `ssl` applications. -They will be started automatically when starting your release. - -The SSL transport `accept/2` function performs both transport -and SSL accepts. Errors occurring during the SSL accept phase -are returned as `{error, {ssl_accept, atom()}}` to differentiate -on which socket the problem occurred. - -Sending and receiving data --------------------------- - -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: - -``` erlang -Transport:send(Socket, <<"Ranch is cool!">>). -Transport:send(Socket, "Ranch is cool!"). -Transport:send(Socket, ["Ranch", ["is", "cool!"]]). -Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]). -``` - -You can receive data either in passive or in active mode. Passive mode -means that you will perform a blocking `Transport:recv/3` call, while -active mode means that you will receive the data as a message. - -By default, all data will be received as binary. It is possible to -receive data as strings, although this is not recommended as binaries -are a more efficient construct, especially for binary protocols. - -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. - -``` erlang -{ok, Data} = Transport:recv(Socket, 0, 5000). -``` - -Active mode requires you to inform the socket that you want to receive -data as a message and to write the code to actually receive it. - -There are two kinds of active modes: `{active, once}` and -`{active, true}`. The first will send a single message before going -back to passive mode; the second will send messages indefinitely. -We recommend not using the `{active, true}` mode as it could quickly -flood your process mailbox. It's better to keep the data in the socket -and read it only when required. - -Three different messages can be received: - * `{OK, Socket, Data}` - * `{Closed, Socket}` - * `{Error, Socket, Reason}` - -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. - -``` erlang -{OK, Closed, Error} = Transport:messages(). -``` - -To start receiving messages you will need to call the `Transport:setopts/2` -function, and do so every time you want to receive data. - -``` erlang -{OK, Closed, Error} = Transport:messages(), -Transport:setopts(Socket, [{active, once}]), -receive - {OK, Socket, Data} -> - io:format("data received: ~p~n", [Data]); - {Closed, Socket} -> - io:format("socket got closed!~n"); - {Error, Socket, Reason} -> - io:format("error happened: ~p~n", [Reason]) -end. -``` - -You can easily integrate active sockets with existing Erlang code as all -you really need is just a few more clauses when receiving messages. - -Sending files -------------- - -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: - -```erlang -{ok, SentBytes} = Transport:sendfile(Socket, Filename). -``` - -Or part of a file, with `Offset` greater than or equal to 0, `Bytes` number of -bytes and chunks of size `ChunkSize`: - -```erlang -Opts = [{chunk_size, ChunkSize}], -{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts). -``` - -To improve efficiency when sending multiple parts of the same file it is also -possible to use a file descriptor opened in raw mode: - -```erlang -{ok, RawFile} = file:open(Filename, [raw, read, binary]), -{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts). -``` - -Writing a transport handler ---------------------------- - -A transport handler is a module implementing the `ranch_transport` behavior. -It defines a certain number of callbacks that must be written in order to -allow transparent usage of the transport handler. - -The behavior doesn't define the socket options available when opening a -socket. These do not need to be common to all transports as it's easy enough -to write different initialization functions for the different transports that -will be used. With one exception though. The `setopts/2` function *must* -implement the `{active, once}` and the `{active, true}` options. - -If the transport handler doesn't have a native implementation of `sendfile/5` a -fallback is available, `ranch_transport:sendfile/6`. The extra first argument -is the transport's module. See `ranch_ssl` for an example. diff --git a/manual/ranch.md b/manual/ranch.md deleted file mode 100644 index 52c792e..0000000 --- a/manual/ranch.md +++ /dev/null @@ -1,182 +0,0 @@ -ranch -===== - -The `ranch` module provides functions for starting and -manipulating Ranch listeners. - -Types ------ - -### max_conns() = non_neg_integer() | infinity - -> 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() = {ack_timeout, timeout()} - | {connection_type, worker | supervisor} - | {max_connections, max_conns()} - | {shutdown, timeout() | brutal_kill} - | {socket, any()} - -> Ranch-specific transport options. -> -> These options are not passed on to the transports. -> They are used by Ranch while setting up the listeners. - -### ref() = any() - -> Unique name used to refer to a listener. - -Exports -------- - -### accept_ack(Ref) -> ok - -> Types: -> * Ref = ref() -> -> Acknowledge that the connection is accepted. -> -> This function MUST be used by a connection process to inform -> Ranch that it initialized properly and let it perform any -> additional operations before the socket can be safely used. - -### child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) - -> supervisor:child_spec() - -> Types: -> * Ref = ref() -> * NbAcceptors = non_neg_integer() -> * Transport = module() -> * TransOpts = any() -> * Protocol = module() -> * ProtoOpts = any() -> -> Return child specifications for a new listener. -> -> This function can be used to embed a listener directly -> in an application instead of letting Ranch handle it. - -### get_max_connections(Ref) -> MaxConns - -> Types: -> * Ref = ref() -> * MaxConns = max_conns() -> -> Return the max number of connections allowed for the given listener. - -### get_port(Ref) -> Port - -> Types: -> * Ref = ref() -> * Port = inet:port_number() -> -> Return the port for the given listener. - -### get_protocol_options(Ref) -> ProtoOpts - -> Types: -> * Ref = ref() -> * ProtoOpts = any() -> -> Return the protocol options set for the given listener. - -### remove_connection(Ref) -> ok - -> Types: -> * Ref = ref() -> -> Do not count this connection when limiting the number of connections. -> -> You can use this function for long-running connection processes -> which spend most of their time idling rather than consuming -> resources. This allows Ranch to accept a lot more connections -> without sacrificing the latency of the system. -> -> This function may only be called from a connection process. - -### set_max_connections(Ref, MaxConns) -> ok - -> Types: -> * Ref = ref() -> * MaxConns = max_conns() -> -> Set the max number of connections for the given listener. -> -> The change will be applied immediately. If the new value is -> smaller than the previous one, Ranch will not kill the extra -> connections, but will wait for them to terminate properly. - -### set_protocol_options(Ref, ProtoOpts) -> ok - -> Types: -> * Ref = ref() -> * ProtoOpts = any() -> -> Set the protocol options for the given listener. -> -> The change will be applied immediately for all new connections. -> Old connections will not receive the new options. - -### start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) - -> {ok, pid()} | {error, badarg} - -> Types: -> * Ref = ref() -> * NbAcceptors = non_neg_integer() -> * Transport = module() -> * TransOpts = any() -> * Protocol = module() -> * ProtoOpts = any() -> -> Start listening for connections using the given transport -> and protocol. Returns the pid for this listener's supervisor. -> -> There are five additional transport options that apply -> regardless of transport. They allow configuring how the -> connections are supervised, rate limited and allow using -> an already open listening socket. -> -> The `ack_timeout` option defines how long post-accept socket -> initialization should take at a maximum. It defaults to `5000`. -> -> The `connection_type` option defines the type of process -> that will handle the connection. It can be either `worker` -> or `supervisor`. It defaults to `worker`. -> -> The `max_connections` option determines how many active -> connections are allowed before Ranch starts throttling -> the accept rate. This is a soft limit. It defaults to `1024`. -> Using the value `infinity` will disable this functionality -> entirely. -> -> The `shutdown` option determines the policy used with -> regards to connection processes when shutting down the listener. -> It can be either a positive integer indicating the max number -> of ms the supervisor will wait before forcibly killing the -> children, or the atom `brutal_kill`. It defaults to `5000`. -> -> The `socket` option allow passing an already open listening -> socket. In this case, Ranch will not call `Transport:listen/1` -> and so none of the transport specific options apply. - -### stop_listener(Ref) -> ok | {error, not_found} - -> Types: -> * Ref = ref() -> -> Stop the given listener. -> -> The listener is stopped gracefully, first by closing the -> listening port, then by stopping the connection processes. -> These processes are stopped according to the `shutdown` -> transport option, which may be set to brutally kill all -> connection processes or give them some time to stop properly. -> -> This function does not return until the listener is -> completely stopped. diff --git a/manual/ranch_app.md b/manual/ranch_app.md deleted file mode 100644 index 1f9d976..0000000 --- a/manual/ranch_app.md +++ /dev/null @@ -1,28 +0,0 @@ -The Ranch Application -===================== - -Socket acceptor pool for TCP protocols. - -Dependencies ------------- - -The `ranch` application has no particular dependency required -to start. - -It has optional dependencies that are only required when -listening for SSL connections. The dependencies are `crypto`, -`asn1`, `public_key` and `ssl`. They are started automatically -if they weren't before. - -Environment ------------ - -The `ranch` application defines one application environment -configuration parameter. - - - profile (false) - - When enabled, Ranch will start `eprof` profiling automatically. - -You can use the `ranch_app:profile_output/0` function to stop -profiling and output the results to the files `procs.profile` -and `total.profile`. Do not use in production. diff --git a/manual/ranch_protocol.md b/manual/ranch_protocol.md deleted file mode 100644 index 807d20a..0000000 --- a/manual/ranch_protocol.md +++ /dev/null @@ -1,42 +0,0 @@ -ranch_protocol -============== - -The `ranch_protocol` behaviour defines the interface used -by Ranch protocols. - -Types ------ - -None. - -Callbacks ---------- - -### start_link(Ref, Socket, Transport, ProtoOpts) -> {ok, pid()} | {ok, pid(), pid()} - -> Types: -> * Ref = ranch:ref() -> * Socket = any() -> * Transport = module() -> * ProtoOpts = any() -> -> Start a new connection process for the given socket. -> -> The only purpose of this callback is to start a process that -> will handle the socket. It must spawn the process, link and -> then return the new pid. This function will always be called -> from inside a supervisor. -> -> This callback can also return two pids. The first pid is the -> pid of the process that will be supervised. The second pid is -> the pid of the process that will receive ownership of the -> socket. This second process must be a child of the first. This -> form is only available when `connection_type` is set to -> `supervisor`. -> -> If any other value is returned, the supervisor will close the -> socket and assume no process has been started. -> -> Do not perform any operations in this callback, as this would -> block the supervisor responsible for starting connection -> processes and degrade performance severely. diff --git a/manual/ranch_ssl.md b/manual/ranch_ssl.md deleted file mode 100644 index 13790d6..0000000 --- a/manual/ranch_ssl.md +++ /dev/null @@ -1,135 +0,0 @@ -ranch_ssl -========= - -The `ranch_ssl` module implements an SSL Ranch transport. - -Types ------ - -### ssl_opt() = {alpn_preferred_protocols, [binary()]} - | {cacertfile, string()} - | {cacerts, [public_key:der_encoded()]} - | {cert, public_key:der_encoded()} - | {certfile, string()} - | {ciphers, [ssl:erl_cipher_suite()] | string()} - | {client_renegotiation, boolean()} - | {crl_cache, {module(), {internal | any(), list()}}} - | {crl_check, boolean() | peer | best_effort} - | {depth, 0..255} - | {dh, public_key:der_encoded()} - | {dhfile, string()} - | {fail_if_no_peer_cert, boolean()} - | {hibernate_after, integer() | undefined} - | {honor_cipher_order, boolean()} - | {key, {'RSAPrivateKey' | 'DSAPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}} - | {keyfile, string()} - | {log_alert, boolean()} - | {next_protocols_advertised, [binary()]} - | {partial_chain, fun(([public_key:der_encoded()]) -> {trusted_ca, public_key:der_encoded()} | unknown_ca)} - | {password, string()} - | {psk_identity, string()} - | {reuse_session, fun()} - | {reuse_sessions, boolean()} - | {secure_renegotiate, boolean()} - | {sni_fun, fun()} - | {sni_hosts, [{string(), ssl_opt()}]} - | {user_lookup_fun, {fun(), any()}} - | {verify, ssl:verify_type()} - | {verify_fun, {fun(), any()}} - | {versions, [atom()]}. - -> SSL-specific listen options. - -### opt() = ranch_tcp:opt() | ssl_opt() - -> Listen options. - -### opts() = [opt()] - -> List of listen options. - -Option descriptions -------------------- - -Specifying a certificate is mandatory, either through the `cert` -or the `certfile` option. None of the other options are required. - -The default value is given next to the option name. - - - alpn_preferred_protocols - - Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. - - cacertfile - - Path to PEM encoded trusted certificates file used to verify peer certificates. - - cacerts - - List of DER encoded trusted certificates. - - cert - - DER encoded user certificate. - - certfile - - Path to the PEM encoded user certificate file. May also contain the private key. - - ciphers - - List of ciphers that clients are allowed to use. - - client_renegotiation (true) - - Whether to allow client-initiated renegotiation. - - crl_cache ({ssl_crl_cache, {internal, []}}) - - Customize the module used to cache Certificate Revocation Lists. - - crl_check (false) - - Whether to perform CRL check on all certificates in the chain during validation. - - depth (1) - - Maximum of intermediate certificates allowed in the certification path. - - dh - - DER encoded Diffie-Hellman parameters. - - dhfile - - Path to the PEM encoded Diffie-Hellman parameters file. - - fail_if_no_peer_cert (false) - - Whether to refuse the connection if the client sends an empty certificate. - - hibernate_after (undefined) - - Time in ms after which SSL socket processes go into hibernation to reduce memory usage. - - honor_cipher_order (false) - - If true, use the server's preference for cipher selection. If false, use the client's preference. - - key - - DER encoded user private key. - - keyfile - - Path to the PEM encoded private key file, if different than the certfile. - - log_alert (true) - - If false, error reports will not be displayed. - - next_protocols_advertised - - List of protocols to send to the client if it supports the Next Protocol extension. - - nodelay (true) - - Whether to enable TCP_NODELAY. - - partial_chain - - Claim an intermediate CA in the chain as trusted. - - password - - Password to the private key file, if password protected. - - psk_identity - - Provide the given PSK identity hint to the client during the handshake. - - reuse_session - - Custom policy to decide whether a session should be reused. - - reuse_sessions (false) - - Whether to allow session reuse. - - secure_renegotiate (false) - - Whether to reject renegotiation attempts that do not conform to RFC5746. - - sni_fun - - Function called when the client requests a host using Server Name Indication. Returns options to apply. - - sni_hosts - - Options to apply for the host that matches what the client requested with Server Name Indication. - - user_lookup_fun - - Function called to determine the shared secret when using PSK, or provide parameters when using SRP. - - verify (verify_none) - - Use `verify_peer` to request a certificate from the client. - - verify_fun - - Custom policy to decide whether a client certificate is valid. - - versions - - TLS protocol versions that will be supported. - -Note that the client will not send a certificate unless the -value for the `verify` option is set to `verify_peer`. This -means that the `fail_if_no_peer_cert` only apply when combined -with the `verify` option. The `verify_fun` option allows -greater control over the client certificate validation. - -The options `sni_fun` and `sni_hosts` are mutually exclusive. - -Exports -------- - -None. diff --git a/manual/ranch_tcp.md b/manual/ranch_tcp.md deleted file mode 100644 index c274b0b..0000000 --- a/manual/ranch_tcp.md +++ /dev/null @@ -1,115 +0,0 @@ -ranch_tcp -========= - -The `ranch_tcp` module implements a TCP Ranch transport. - -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() = {backlog, non_neg_integer()} - | {buffer, non_neg_integer()} - | {delay_send, boolean()} - | {dontroute, boolean()} - | {exit_on_close, boolean()} - | {fd, non_neg_integer()} - | {high_msgq_watermark, non_neg_integer()} - | {high_watermark, non_neg_integer()} - | inet - | inet6 - | {ip, inet:ip_address()} - | {keepalive, boolean()} - | {linger, {boolean(), non_neg_integer()}} - | {low_msgq_watermark, non_neg_integer()} - | {low_watermark, non_neg_integer()} - | {nodelay, boolean()} - | {port, inet:port_number()} - | {priority, integer()} - | {raw, non_neg_integer(), non_neg_integer(), binary()} - | {recbuf, non_neg_integer()} - | {send_timeout, timeout()} - | {send_timeout_close, boolean()} - | {sndbuf, non_neg_integer()} - | {tos, integer()} - -> Listen options. -> -> This does not represent the entirety of the options that can -> be set on the socket, but only the options that may be -> set independently of protocol implementation. - -### opts() = [opt()] - -> List of listen options. - -Option descriptions -------------------- - -None of the options are required. - -Please consult the `gen_tcp` and `inet` manuals for a more -thorough description of these options. This manual only aims -to provide a short description along with what the defaults -are. Defaults may be different in Ranch compared to `gen_tcp`. -Defaults are given next to the option name. - - - backlog (1024) - - Max length of the queue of pending connections. - - buffer - - Size of the buffer used by the Erlang driver. Default is system-dependent. - - delay_send (false) - - Always queue packets before sending, to send fewer, larger packets over the network. - - dontroute (false) - - Don't send via a gateway, only send to directly connected hosts. - - exit_on_close (true) - - Disable to allow sending data after a close has been detected. - - fd - - File descriptor of the socket, if it was opened externally. - - high_msgq_watermark (8192) - - Limit in the amount of data in the socket message queue before the socket queue becomes busy. - - high_watermark (8192) - - Limit in the amount of data in the ERTS socket implementation's queue before the socket becomes busy. - - inet - - Set up the socket for IPv4. - - inet6 - - Set up the socket for IPv6. - - ip - - Interface to listen on. Listen on all interfaces by default. - - keepalive (false) - - Enable sending of keep-alive messages. - - linger ({false, 0}) - - Whether to wait and how long to flush data sent before closing the socket. - - low_msgq_watermark (4096) - - Amount of data in the socket message queue before the socket queue leaves busy state. - - low_watermark (4096) - - Amount of data in the ERTS socket implementation's queue before the socket leaves busy state. - - nodelay (true) - - Whether to enable TCP_NODELAY. - - port (0) - - TCP port number to listen on. 0 means a random port will be used. - - priority (0) - - Priority value for all packets to be sent by this socket. - - recbuf - - Minimum size of the socket's receive buffer. Default is system-dependent. - - send_timeout (30000) - - How long the send call may wait for confirmation before returning. - - send_timeout_close (true) - - Whether to close the socket when the confirmation wasn't received. - - sndbuf - - Minimum size of the socket's send buffer. Default is system-dependent. - - tos - - Value for the IP_TOS IP level option. Use with caution. - -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. - -Exports -------- - -None. diff --git a/manual/ranch_transport.md b/manual/ranch_transport.md deleted file mode 100644 index 7ae3e31..0000000 --- a/manual/ranch_transport.md +++ /dev/null @@ -1,205 +0,0 @@ -ranch_transport -=============== - -The `ranch_transport` behaviour defines the interface used -by Ranch transports. - -Types ------ - -### sendfile_opts() = [{chunk_size, non_neg_integer()}] - -> Options used by the sendfile function and callbacks. -> -> Allows configuring the chunk size, in bytes. Defaults to 8191 bytes. - -Callbacks ---------- - -### accept(LSocket, Timeout) - -> {ok, CSocket} | {error, closed | timeout | atom()} - -> Types: -> * LSocket = CSocket = any() -> * Timeout = timeout() -> -> Accept a connection on the given listening socket. -> -> The `accept_ack` callback will be used to initialize the socket -> after accepting the connection. This is most useful when the -> transport is not raw TCP, like with SSL for example. - -### accept_ack(CSocket, Timeout) -> ok - -> Types: -> * CSocket = any() -> * Timeout = timeout() -> -> Perform post-accept initialization of the connection. -> -> 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 make the socket ready to use. - -### close(CSocket) -> ok - -> Types: -> * CSocket = any() -> -> Close the given socket. - -### controlling_process(CSocket, Pid) - -> ok | {error, closed | not_owner | atom()} - -> Types: -> * CSocket = any() -> * Pid = pid() -> -> Change the controlling process for the given socket. -> -> The controlling process is the process that is allowed to -> perform operations on the socket, and that will receive -> messages from the socket when active mode is used. When -> the controlling process dies, the socket is closed. - -### listen(TransOpts) -> {ok, LSocket} | {error, atom()} - -> Types: -> * TransOpts = any() -> * LSocket = any() -> -> Listen for connections on the given port. -> -> The port is given as part of the transport options under -> the key `port`. Any other option is transport dependent. -> -> The socket returned by this call can then be used to -> accept connections. It is not possible to send or receive -> data from the listening socket. - -### messages() -> {OK, Closed, Error} - -> Types: -> * OK = Closed = Error = atom() -> -> Return the atoms used to identify messages sent in active mode. - -### name() -> Name - -> Types: -> * Name = atom() -> -> Return the name of the transport. - -### peername(CSocket) -> {ok, {IP, Port}} | {error, atom()} - -> Types: -> * CSocket = any() -> * IP = inet:ip_address() -> * Port = inet:port_number() -> -> Return the IP and port of the remote endpoint. - -### recv(CSocket, Length, Timeout) - -> {ok, Packet} | {error, closed | timeout | atom()} - -> Types: -> * CSocket = any() -> * Length = non_neg_integer() -> * Timeout = timeout() -> * Packet = iodata() | any() -> -> Receive data from the given socket when in passive mode. -> -> Trying to receive data from a socket that is in active mode -> will return an error. -> -> A length of 0 will return any data available on the socket. -> -> While it is possible to use the timeout value `infinity`, -> this is highly discouraged as this 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 -> of this issue. - -### send(CSocket, Packet) -> ok | {error, atom()} - -> Types: -> * CSocket = any() -> * Packet = iodata() -> -> Send data to the given socket. - -### sendfile(CSocket, File) - -> sendfile(CSocket, File, 0, 0, []) -### sendfile(CSocket, File, Offset, Bytes) - -> sendfile(CSocket, File, Offset, Bytes, []) -### sendfile(CSocket, File, Offset, Bytes, SfOpts) - -> {ok, SentBytes} | {error, atom()} - -> Types: -> * CSocket = any() -> * File = file:filename_all() | file:fd() -> * Offset = non_neg_integer() -> * Bytes = SentBytes = non_neg_integer() -> * SfOpts = sendfile_opts() -> -> Send data from a file to the given socket. -> -> 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(CSocket, TransOpts) -> ok | {error, atom()} - -> Types: -> * CSocket = any() -> * TransOpts = any() -> -> Change transport options for the given socket. -> -> This is mainly useful for switching to active or passive mode. - -### shutdown(CSocket, How) -> ok | {error, atom()} - -> Types: -> * CSocket = any() -> * How = read | write | read_write -> -> Immediately close the socket in one or two directions. - -### sockname(CSocket) -> {ok, {IP, Port}} | {error, atom()} - -> Types: -> * CSocket = any() -> * IP = inet:ip_address() -> * Port = inet:port_number() -> -> Return the IP and port of the local endpoint. - -Exports -------- - -### sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) - -> {ok, SentBytes} | {error, atom()} - -> Types: -> * Transport = module() -> * CSocket = any() -> * File = file:filename_all() | file:fd() -> * Offset = non_neg_integer() -> * Bytes = SentBytes = non_neg_integer() -> * SfOpts = sendfile_opts() -> -> Send data from a file to the given socket. -> -> This function emulates the function `file:sendfile/{2,4,5}` -> and may be used when transports are not manipulating TCP -> directly. diff --git a/manual/toc.md b/manual/toc.md deleted file mode 100644 index af99d14..0000000 --- a/manual/toc.md +++ /dev/null @@ -1,11 +0,0 @@ -Ranch Function Reference -======================== - -The function reference documents the public interface of Ranch. - - * [The Ranch Application](ranch_app.md) - * [ranch](ranch.md) - * [ranch_protocol](ranch_protocol.md) - * [ranch_ssl](ranch_ssl.md) - * [ranch_tcp](ranch_tcp.md) - * [ranch_transport](ranch_transport.md) -- cgit v1.2.3