I will simply quote the official documentation:

It is worth emphasizing that Ranch manage a pool of listeners.

It is worth noticing here that the ranch dependency is part of the applications field, as expected. A quick check proves that the ranch binaries are available in the deps/ directory.

tcp_echo_app is the entry point of the application, as it is the value of the mod parameter.

That’s the entry point of the application. The module implements the "application" API with the methods start/2 and stop/1 - as expected.

In start/2, ranch:start_listener/5 is called. That’s the core of Ranch. It starts the pool of TCP/IP listener. Take note that the module echo_protocol is being passed as parameter.

The next line tcp_echo_sup:start_link() basically starts a custom supervisor.

Let’s see the supervisor code.

It’s written as a dynamic supervisor, but…​ No child is ever added using supervisor:start_child/2 in the rest of the files. So as is, this supervisor is useless…​

This module was passed as parameter in ranch:start_listener/5. It implements the ranch protocol behaviour (-behaviour(ranch_protocol)). The entry point being start_link/3 that basically spawn a linked process that will ultimately run init/3. Contrary to a traditional gen_server that’s not init/1 that’s being called.

init/3 runs ranch:handshake(Ref) which most probably initiates the Socket acceptors…​? Then it runs a recursive loop function, that simply pattern match the data being received. Transport:recv(Socket, 0, 5000) being probably a blocking operation, it just waits until data is received.

Then, it reads the first data and if anything is received, echoes back the same message using Transport:send(Socket, Data) and start the same function loop again. Ultimately, when no data is received, it closes the socket using Transport:close(Socket). Then it goes out of the loop and the process terminates.

Nothing much different from before here, just a basic .app file which tells us that tcp_reverse_app is the starting module of the application.

Starting the ranch_listener, like before. Still using ranch_tcp transport, and this time the custom reverse_protocol.

Same as before. Useless supervisor here.

This example is useful to show how to integrate a gen_statem custom protocol handler with Ranch. It would also work the same way for a gen_server.

The official Ranch documentation is enough.

Read LYSEFGG and the official Erlang documentation to know more about Finite State Machines and gen_statem.

This is the main file defining the project. Let’s decrypt it together and remind ourselves what is the meaning of the different values.

]}.

Source: Official Erlang Documentation

Yep, it has -behaviour(application), which makes sense because it is part of the mod parameter above. The file is quite small and easy to understand.

That’s the supervisor for the whole Ranch app. We can now start our supervisor tree:

See LYSEFGG for more info on the Application Master. Let’s dive in ranch_sup to know what’s behind these question marks.

As expected, it implements the supervisor behaviour.

The following code:

start_link() → supervisor:start_link({local, ?MODULE}, ?MODULE, []).

is standard. No argument will be passed to init/1.

init/1 with an empty argument list will be run in the spawned supervisor process. We will now study its content.

The first thing to notice is that it implements gen_server, as expected by its name.

start_link/0 without surprises is running gen_server:start_link/4, with standard arguments.

We know that the init/1 function is the starting point of this process. We therefore scroll the file down to see its implementation.

As expected, init/1 returns {ok, State} with State being here of type state, record defined previously (see above).

The list of all connections and listener supervisors is fetched from the ETS table previously created. ranch_server starts monitoring them, and store the returned reference in the state, together with its corresponding Pid, the Reference of the supervisor process itself, and its Id (for connection supervisor).

From that point on, it would be interesting to look for the location where the connection and listener supervisors are added to the ETS table.

To do so, we can search for "conns_sup" or "listener_sup" or "ets:insert" in the project.

ranch_server:set_monitored_process/3 is simply making ranch_server monitor the connection/listener supervisor, update the ETS Table accordingly and return the new updated state.

It is called on creation of the supervisors.

What happens when ranch_server dies and is restarted by ranch_sup? In this case, there will still be data in the ETS Table, data that will be monitored by…​ the ranch_server process that just died! So, basically not monitored at all! That’s it! That’s the reason why the use of erlang:monitor(process, Pid) in ranch_server:init/1 does not stack with another monitoring. Its only (and important!) point is in case the process that was previously monitoring died!

These functions are the API that’s accessible by the user of the library. They are features. See the official documentation to know more about their usage.

Finally, ranch_server:get_connections_sup/2 is used by ranch_acceptor:start_link/5. If you remember well the previous chapter, the listener was the one that was creating the connection supervisor supervisor and the acceptor supervisor. Which means they were basically creating them. However, it is obviously the acceptor which needs to trigger the connection supervisor to start the connection process. So the acceptor has to know about a process that’s neither his parent nor his child. That’s why he needs to get it from an ETS table, that’s handled by ranch_server!

We can now improve our schema:

So, as expected after the study of the documentation, everytime a connection supervisor or a listener supervisor is started, it is registered within the ranch_server.

Now we are wondering: when are they started?

That’s the where all the API functions are stored. The most important one here being ranch:start_listener/5. Let’s dive in its implementation.

Open the source code, and look at it with me!

It starts by "normalizing" the TransportOpts0 parameter using ranch:normalize_opts/1.

The list of socket options being the old way, it is still handled by modern Ranch for backward compatibility purpose.

Interestingly, code:ensure_loaded(Transport) is being used. If you are no idea what module loading, interactive and embedded mode are, then check the official documentation. The commit message from Andrew Majorov corresponding to the usage of this method is the following:

It should be self-explanatory, but I found the whole usage of the code module interesting enough to point it out here!

Then, once the Transport module loaded, the Transport options are being validated using ranch:validate_transport_opts/1.

If it passes, then the method kindly asks the ranch_sup module to start the ranch_listener_sup supervisor using: supervisor:start_child(ranch_sup, ChildSpec).

The maybe_started/1 method is just there for error reporting enhancement purpose.

Hey! We can improve our little schema again!

It implements the supervisor behaviour, as expected.

This file is very simple. It basically starts two children, both being supervisors: ranch_conns_sup_sup and ranch_acceptors_sup. It was expected from the chapter dealing about the documentation.

The restart strategy is rest_for_one. It means that if ranch_conns_sup_sup dies, then ranch_acceptors_sup will be terminated and then both will be restarted sequentially. However, if ranch_acceptors_sup dies, it will be restarted but ranch_conns_sup_sup will not be affected.

If a supervisor starts A, then B, and B depends on A, the rest_for_one strategy is usually selected. Here, it is indeed used because ranch_acceptor relies on ranch_conns_sup. We will see later how. I anticipate a little bit here, as we wouldn’t know just now.

We can update our schema!

This supervisor is starting the ranch_conns_sup supervisors. It starts by cleaning up all the ranch_conns_sup supervisors monitored by ranch_server. That’s because if ranch_conns_sup_sup is restarted, all its children would have been been killed and restarted as well.

num_acceptors being defaulted at 10 while num_conns_sups is default to the current value of num_acceptors.

As indicated by its name, num_conns_sup is the number of connection supervisor ranch_conns_sup being started by ranch_conns_sup_sup for each listener.

I quote the official documentation:

Also the following commit message from the 5th of August 2019 by "juhlig":

I am not certain I fully understand the purpose of num_conns_sups at the moment - you will see why later.

Note that each ranch_conns_sup module being spawned is attributed an Id - passed as a parameter to ranch_conns_sup:start_link/6 function. This Id is a digit ranging from 1 to the value of the maximum number of connection supervisors (num_conns_sups).

It implements the supervisor behaviour.

This module’s responsibility is to start the listenning socket(s) and then delegating the socket(s) responsibility to each of the corresponding the ranch_acceptor being spawned.

How do Ranch determines which socket reference to pass to the acceptor? The following code answers this question:

As you probably know, the remainder r of an euclidian division a/b is such as

therefore we have :

which is what we were looking for.

How is the distribution of LSocketId given AcceptorId is variable and NumListenSockets is constant?

When it could seem obvious that this distribution is even, you’ll read here that it isn’t. This specific post was in case AcceptorId would be constant instead of NumListenSockets. I haven’t been able to answer that question. If anyone has a glimpse, please start an issue on the GitHub repo!

This file is rather unusual compared to what we faced until now. It does not implement the traditional supervisor behaviour. It’s a so-called special process. This will be interesting! If you don’t know anything about it, I recommend going through this article. I found it quite insightful.

As seen earlier, ranch_conns_sup:start_protocol/3 is called by ranch_acceptor. It ultimately calls Protocol:start_link/3 - which starts the connection process. It is not started the usual way like a supervisor would do because we’re using the delegate parameter. That’s the reason why a special process is used here instead of a regular supervisor.

This file is by far the most complex - and deserve all your attention.

Note that ranch_conns_sup registers itself to ranch_server’s ETS Table on its initialization using ranch_server:set_connections_sup/3.

We notice that this module maintains a state record that in particular hold the Parent Pid of this supervisor - which is ranch_conns_sup_sup Pid. It also holds the Transport and Protocol options as well as the max_conns parameter and the logger.

Right at its initialization, this module calls ranch_server:get_connections_sup(Ref, AcceptorId).

I’ll copy-paste the full implementation of the function here:

As a matter of readability, I’ll extend what get_connections_sups(Ref) is doing, and rename the parameter Id to what is really is, i.e AcceptorId:

See the ranch_listener_sup booting order exposed earlier to understand why these two steps happen sequentially.