ranch/guide/embedded.md

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.

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.