Convert the documentation to Asciidoc

9 files changed, 944 insertions, 0 deletions

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.