ranch

Ranch

Ranch is a socket acceptor pool for TCP protocols.

Goals

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.

Ranch provides a modular design, letting you choose which transport and protocol are going to be used for a particular listener. Listeners accept and manage connections on one port, and include facilities to limit the number of concurrent connections. Connections are sorted into pools, each pool having a different configurable limit.

Ranch also allows you to upgrade the acceptor pool without having to close any of the currently opened sockets.

The project is currently in early development. Comments and suggestions are more than welcome. To contribute, either open bug reports, or fork the project and send us pull requests with new or improved functionality. You should discuss your plans with us before doing any serious work, though, to avoid duplicating efforts.

Quick start

• Add Ranch as a rebar or agner dependency to your application.
• Start Ranch and add one or more listeners.
• Write protocol handlers for your application.

Getting Started

Ranch accepts connections received on a given port and using a given transport, like TCP or SSL, and forward them to a given protocol handler. Acceptors and protocol handler processes are of course supervised automatically.

Ranch does nothing by default. You need to explicitly request Ranch to listen on a port with your chosen transport and protocol handlers. To do so, you must start a listener.

A listener is a special kind of supervisor that manages both the acceptor pool and the protocol processes. It is named and can thus be started and stopped at will.

An acceptor pool is a pool of processes whose only role is to accept new connections. It's good practice to have many of these processes as they are very cheap and allow much quicker response when you get many connections. Of course, as with everything else, you should benchmark before you decide what's best for you.

Ranch includes both TCP and SSL transport handlers, abstracted through a single common interface.

You can start and stop listeners by calling ranch:start_listener/6 and ranch:stop_listener/1 respectively.

The following example demonstrates the startup of a very simple listener.

application:start(ranch),
%% Name, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts
ranch:start_listener(my_echo_listener, 100,
    ranch_tcp, [{port, 1234}],
    my_echo_protocol, [{log, "echo.log"}]
).

Writing a protocol handler

The only exported function a protocol handler needs is the start_link/4 function, with arguments ListenerPid, Socket, Transport and Opts. ListenerPid is the pid to the listener's gen_server, managing the connections. Socket is of course the client socket; Transport is the module name of the chosen transport handler and Opts is protocol options defined when starting the listener.

After initializing your protocol, it is recommended to call the function ranch:accept_ack/1 with the ListenerPid as argument, as it will ensure Ranch has been able to fully initialize the socket. Anything you do past this point is up to you!

If you need to change some socket options, like enabling raw mode for example, you can call the Transport:setopts/2 function. It is the protocol's responsability to manage the socket usage, there should be no need for an user to specify that kind of options while starting a listener.