diff options
Diffstat (limited to 'guide')
| -rw-r--r-- | guide/embedded.md | 50 | ||||
| -rw-r--r-- | guide/internals.md | 97 | ||||
| -rw-r--r-- | guide/introduction.md | 37 | ||||
| -rw-r--r-- | guide/listeners.md | 240 | ||||
| -rw-r--r-- | guide/parsers.md | 92 | ||||
| -rw-r--r-- | guide/protocols.md | 121 | ||||
| -rw-r--r-- | guide/ssl_auth.md | 118 | ||||
| -rw-r--r-- | guide/toc.md | 25 | ||||
| -rw-r--r-- | guide/transports.md | 165 |
9 files changed, 0 insertions, 945 deletions
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. |