diff options
Diffstat (limited to 'docs/en/ranch/2.1/guide')
29 files changed, 5426 insertions, 0 deletions
diff --git a/docs/en/ranch/2.1/guide/connection_draining.asciidoc b/docs/en/ranch/2.1/guide/connection_draining.asciidoc new file mode 100644 index 00000000..2ccdbc84 --- /dev/null +++ b/docs/en/ranch/2.1/guide/connection_draining.asciidoc @@ -0,0 +1,98 @@ +== Connection draining + +Stopping a Ranch listener via `ranch:stop_listener/1` will invariably kill +all connection processes the listener hosts. However, you may want to stop +a listener in a graceful fashion, ie by not accepting any new connections, +but allowing the existing connection processes to exit by themselves instead +of being killed. + +For this purpose, you should first suspend the listener you wish to +stop gracefully, and then wait for its connection count to drop to +zero. + +.Draining a single listener + +[source,erlang] +---- +ok = ranch:suspend_listener(Ref), +ok = ranch:wait_for_connections(Ref, '==', 0), +ok = ranch:stop_listener(Ref). +---- + +If you want to drain more than just one listener, it may be important to first suspend +them all before beginning to wait for their connection counts to reach zero. Otherwise, +the not yet suspended listeners will still be accepting connections while you wait for +the suspended ones to be drained. + +.Draining multiple listeners + +[source,erlang] +---- +lists:foreach( + fun (Ref) -> + ok = ranch:suspend_listener(Ref) + end, + Refs +), +lists:foreach( + fun (Ref) -> + ok = ranch:wait_for_connections(Ref, '==', 0), + ok = ranch:stop_listener(Ref) + end, + Refs +). +---- + +If you have long-running connection processes hosted by the listener you want to stop +gracefully, draining may take a long time, possibly forever. If you just want to give +the connection processes a chance to finish, but are not willing to wait for infinity, +the waiting part could be handled in a separate process. + +.Draining a listener with a timeout + +[source,erlang] +---- +ok = ranch:suspend_listener(Ref), +{DrainPid, DrainRef} = spawn_monitor( + fun () -> + ok = ranch:wait_for_connections(Ref, '==', 0) + end +), +receive + {'DOWN', DrainRef, process, DrainPid, _} -> + ok +after DrainTimeout -> + exit(DrainPid, kill), + ok +end, +ok = ranch:stop_listener(Ref). +---- + +To drain listeners automatically as part of your application shutdown routine, +use the `prep_stop/1` function of your application module. + +.Draining listeners automatically on application shutdown + +[source,erlang] +---- +-module(my_app). + +-behavior(application). + +-export([start/2]). +-export([prep_stop/1]). +-export([stop/1]). + +start(_StartType, _StartArgs) -> + {ok, _} = ranch:start_listener(my_listener, ranch_tcp, #{}, my_protocol, []), + my_app_sup:start_link(). + +prep_stop(State) -> + ok = ranch:suspend_listener(my_listener), + ok = ranch:wait_for_connections(my_listener, '==', 0), + ok = ranch:stop_listener(my_listener), + State. + +stop(_State) -> + ok. +---- diff --git a/docs/en/ranch/2.1/guide/connection_draining/index.html b/docs/en/ranch/2.1/guide/connection_draining/index.html new file mode 100644 index 00000000..52a279f3 --- /dev/null +++ b/docs/en/ranch/2.1/guide/connection_draining/index.html @@ -0,0 +1,258 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Connection draining</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Connection draining</span></h1> + +<p>Stopping a Ranch listener via <code>ranch:stop_listener/1</code> will invariably kill all connection processes the listener hosts. However, you may want to stop a listener in a graceful fashion, ie by not accepting any new connections, but allowing the existing connection processes to exit by themselves instead of being killed.</p> +<p>For this purpose, you should first suspend the listener you wish to stop gracefully, and then wait for its connection count to drop to zero.</p> +<div class="listingblock"><div class="title">Draining a single listener</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:suspend_listener</font></b>(<font color="#009900">Ref</font>), +<font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:wait_for_connections</font></b>(<font color="#009900">Ref</font>, <font color="#FF6600">'=='</font>, <font color="#993399">0</font>), +<font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:stop_listener</font></b>(<font color="#009900">Ref</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>If you want to drain more than just one listener, it may be important to first suspend them all before beginning to wait for their connection counts to reach zero. Otherwise, the not yet suspended listeners will still be accepting connections while you wait for the suspended ones to be drained.</p> +<div class="listingblock"><div class="title">Draining multiple listeners</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">lists:foreach</font></b>( + <b><font color="#0000FF">fun</font></b> (<font color="#009900">Ref</font>) <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:suspend_listener</font></b>(<font color="#009900">Ref</font>) + <b><font color="#0000FF">end</font></b>, + <font color="#009900">Refs</font> +), +<b><font color="#000000">lists:foreach</font></b>( + <b><font color="#0000FF">fun</font></b> (<font color="#009900">Ref</font>) <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:wait_for_connections</font></b>(<font color="#009900">Ref</font>, <font color="#FF6600">'=='</font>, <font color="#993399">0</font>), + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:stop_listener</font></b>(<font color="#009900">Ref</font>) + <b><font color="#0000FF">end</font></b>, + <font color="#009900">Refs</font> +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>If you have long-running connection processes hosted by the listener you want to stop gracefully, draining may take a long time, possibly forever. If you just want to give the connection processes a chance to finish, but are not willing to wait for infinity, the waiting part could be handled in a separate process.</p> +<div class="listingblock"><div class="title">Draining a listener with a timeout</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:suspend_listener</font></b>(<font color="#009900">Ref</font>), +{<font color="#009900">DrainPid</font>, <font color="#009900">DrainRef</font>} <font color="#990000">=</font> <b><font color="#000000">spawn_monitor</font></b>( + <b><font color="#0000FF">fun</font></b> () <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:wait_for_connections</font></b>(<font color="#009900">Ref</font>, <font color="#FF6600">'=='</font>, <font color="#993399">0</font>) + <b><font color="#0000FF">end</font></b> +), +<b><font color="#0000FF">receive</font></b> + {<font color="#FF6600">'DOWN'</font>, <font color="#009900">DrainRef</font>, <b><font color="#000080">process</font></b>, <font color="#009900">DrainPid</font>, <font color="#990000">_</font>} <font color="#990000">-></font> + <font color="#FF6600">ok</font> +<b><font color="#0000FF">after</font></b> <font color="#009900">DrainTimeout</font> <font color="#990000">-></font> + <b><font color="#000080">exit</font></b>(<font color="#009900">DrainPid</font>, <b><font color="#000080">kill</font></b>), + <font color="#FF6600">ok</font> +<b><font color="#0000FF">end</font></b>, +<font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:stop_listener</font></b>(<font color="#009900">Ref</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>To drain listeners automatically as part of your application shutdown routine, use the <code>prep_stop/1</code> function of your application module.</p> +<div class="listingblock"><div class="title">Draining listeners automatically on application shutdown</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000080">-module</font></b>(<font color="#FF6600">my_app</font>)<font color="#990000">.</font> + +<b><font color="#000080">-behavior</font></b>(<font color="#FF6600">application</font>)<font color="#990000">.</font> + +<b><font color="#000080">-export</font></b>([<b><font color="#000000">start</font></b><font color="#990000">/</font><font color="#993399">2</font>])<font color="#990000">.</font> +<b><font color="#000080">-export</font></b>([<b><font color="#000000">prep_stop</font></b><font color="#990000">/</font><font color="#993399">1</font>])<font color="#990000">.</font> +<b><font color="#000080">-export</font></b>([<b><font color="#000000">stop</font></b><font color="#990000">/</font><font color="#993399">1</font>])<font color="#990000">.</font> + +<b><font color="#000000">start</font></b>(<font color="#009900">_StartType</font>, <font color="#009900">_StartArgs</font>) <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">my_listener</font>, <font color="#FF6600">ranch_tcp</font>, #{}, <font color="#FF6600">my_protocol</font>, []), + <b><font color="#000000">my_app_sup:start_link</font></b>()<font color="#990000">.</font> + +<b><font color="#000000">prep_stop</font></b>(<font color="#009900">State</font>) <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:suspend_listener</font></b>(<font color="#FF6600">my_listener</font>), + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:wait_for_connections</font></b>(<font color="#FF6600">my_listener</font>, <font color="#FF6600">'=='</font>, <font color="#993399">0</font>), + <font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:stop_listener</font></b>(<font color="#FF6600">my_listener</font>), + <font color="#009900">State</font><font color="#990000">.</font> + +<b><font color="#000000">stop</font></b>(<font color="#009900">_State</font>) <font color="#990000">-></font> + <font color="#FF6600">ok</font><font color="#990000">.</font></tt></pre> +</div></div> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/ssl_auth/"> + SSL client authentication + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/internals/"> + Internals + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/embedded.asciidoc b/docs/en/ranch/2.1/guide/embedded.asciidoc new file mode 100644 index 00000000..28f567bc --- /dev/null +++ b/docs/en/ranch/2.1/guide/embedded.asciidoc @@ -0,0 +1,47 @@ +== 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. + +However, just as for non-embedded listeners that were started via +`ranch:start_listener/5`, it is required that the `ranch` application +is running before you can start embedded listeners. Furthermore, +this also means that embedded listeners will restart when `ranch_sup` fails. + +WARNING: By using embedded mode, it is possible to start a listener with the same name +as an already existing listener. This will corrupt the information Ranch +keeps for that listener, so you should take care to ensure unique listener +names yourself. A good way to achieve this is by combining the embedded +listener's name with `?MODULE`, or the name of the application it is used +in. + +=== 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 has a convenience function for getting the listeners child specs +called `ranch:child_spec/5`, that works like `ranch:start_listener/5`, +except that it doesn't start anything, it only returns child specs. + +The following example adds one listener to another application's +supervision tree. + +.Embed Ranch directly in your supervision tree + +[source,erlang] +---- +init([]) -> + ListenerSpec = ranch:child_spec({?MODULE, echo}, + ranch_tcp, #{socket_opts => [{port, 5555}]}, + echo_protocol, [] + ), + {ok, {#{}, [ListenerSpec]}}. +---- + +Embedded listeners cannot be stopped via `ranch:stop_listener/1`. Instead, +are to be stopped as part of the shutdown of your application's supervison +tree. diff --git a/docs/en/ranch/2.1/guide/embedded/index.html b/docs/en/ranch/2.1/guide/embedded/index.html new file mode 100644 index 00000000..7d8c0075 --- /dev/null +++ b/docs/en/ranch/2.1/guide/embedded/index.html @@ -0,0 +1,199 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Embedded mode</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Embedded mode</span></h1> + +<p>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.</p> +<p>However, just as for non-embedded listeners that were started via <code>ranch:start_listener/5</code>, it is required that the <code>ranch</code> application is running before you can start embedded listeners. Furthermore, this also means that embedded listeners will restart when <code>ranch_sup</code> fails.</p> +<p>WARNING: By using embedded mode, it is possible to start a listener with the same name as an already existing listener. This will corrupt the information Ranch keeps for that listener, so you should take care to ensure unique listener names yourself. A good way to achieve this is by combining the embedded listener's name with <code>?MODULE</code>, or the name of the application it is used in.</p> +<h2 id="_embedding">Embedding</h2> +<p>To embed Ranch in your application you can simply add the child specs to your supervision tree. This can all be done in the <code>init/1</code> function of one of your application supervisors.</p> +<p>Ranch has a convenience function for getting the listeners child specs called <code>ranch:child_spec/5</code>, that works like <code>ranch:start_listener/5</code>, except that it doesn't start anything, it only returns child specs.</p> +<p>The following example adds one listener to another application's supervision tree.</p> +<div class="listingblock"><div class="title">Embed Ranch directly in your supervision tree</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">init</font></b>([]) <font color="#990000">-></font> + <font color="#009900">ListenerSpec</font> <font color="#990000">=</font> <b><font color="#000000">ranch:child_spec</font></b>({<b><font color="#000080">?MODULE</font></b>, <font color="#FF6600">echo</font>}, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}]}, + <font color="#FF6600">echo_protocol</font>, [] + ), + {<font color="#FF6600">ok</font>, {#{}, [<font color="#009900">ListenerSpec</font>]}}<font color="#990000">.</font></tt></pre> +</div></div> +<p>Embedded listeners cannot be stopped via <code>ranch:stop_listener/1</code>. Instead, are to be stopped as part of the shutdown of your application's supervison tree.</p> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/protocols/"> + Protocols + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/parsers/"> + Writing parsers + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/index.html b/docs/en/ranch/2.1/guide/index.html new file mode 100644 index 00000000..016fe7dd --- /dev/null +++ b/docs/en/ranch/2.1/guide/index.html @@ -0,0 +1,193 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Ranch User Guide</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Ranch User Guide</span></h1> + +<h2 id="_interface">Interface</h2> +<ul><li><a href="introduction/">Introduction</a> +</li> +<li><a href="listeners/">Listeners</a> +</li> +<li><a href="transports/">Transports</a> +</li> +<li><a href="protocols/">Protocols</a> +</li> +<li><a href="embedded/">Embedded mode</a> +</li> +</ul> +<h2 id="_how_to">How to</h2> +<ul><li><a href="parsers/">Writing parsers</a> +</li> +<li><a href="ssl_auth/">SSL client authentication</a> +</li> +<li><a href="connection_draining/">Connection draining</a> +</li> +</ul> +<h2 id="_advanced">Advanced</h2> +<ul><li><a href="internals/">Internals</a> +</li> +</ul> +<h2 id="_additional_information">Additional information</h2> +<ul><li><a href="migrating_from_2.0/">Migrating from Ranch 2.0 to 2.1</a> +</li> +<li><a href="migrating_from_1.7/">Migrating from Ranch 1.7 to 2.0</a> +</li> +<li><a href="migrating_from_1.6/">Migrating from Ranch 1.6 to 1.7</a> +</li> +<li><a href="migrating_from_1.5/">Migrating from Ranch 1.5 to 1.6</a> +</li> +<li><a href="migrating_from_1.x/">Migrating from Ranch 1.x</a> +</li> +</ul> + + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/internals.asciidoc b/docs/en/ranch/2.1/guide/internals.asciidoc new file mode 100644 index 00000000..600920fc --- /dev/null +++ b/docs/en/ranch/2.1/guide/internals.asciidoc @@ -0,0 +1,99 @@ +== 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. + +A third party dive into the internals of Ranch is available should +you be interested: https://baozi.technology/ranch-under-the-hood/[Ranch: what's under the hood?] +We make no claims with regard to its freshness or accuracy but this +is a nice document to read along this section. + +=== 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/5` 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/docs/en/ranch/2.1/guide/internals/index.html b/docs/en/ranch/2.1/guide/internals/index.html new file mode 100644 index 00000000..35082102 --- /dev/null +++ b/docs/en/ranch/2.1/guide/internals/index.html @@ -0,0 +1,207 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Internals</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Internals</span></h1> + +<p>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.</p> +<p>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.</p> +<p>A third party dive into the internals of Ranch is available should you be interested: <a href="https://baozi.technology/ranch-under-the-hood/">Ranch: what's under the hood?</a> We make no claims with regard to its freshness or accuracy but this is a nice document to read along this section.</p> +<h2 id="_architecture">Architecture</h2> +<p>Ranch is an OTP application.</p> +<p>Like all OTP applications, Ranch has a top supervisor. It is responsible for supervising the <code>ranch_server</code> process and all the listeners that will be started.</p> +<p>The <code>ranch_server</code> 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 <code>ranch_server</code>. The table is owned by the top supervisor to improve fault tolerance. This way if the <code>ranch_server</code> gen_server fails, it doesn't lose any information and the restarted process can continue as if nothing happened.</p> +<p>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 <code>sys</code> and <code>supervisor</code> calls will work on it as expected.</p> +<p>Listeners are grouped into the <code>ranch_listener_sup</code> 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 <code>ranch_server</code> gen_server with varying amount of information.</p> +<p>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.</p> +<h2 id="_number_of_acceptors">Number of acceptors</h2> +<p>The second argument to <code>ranch:start_listener/5</code> is the number of processes that will be accepting connections. Care should be taken when choosing this number.</p> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2> +<p>Some socket options are platform-specific and not supported by <code>inet</code>. 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 <code>raw</code> option, for which we will see an example.</p> +<p>One of these features is <code>TCP_DEFER_ACCEPT</code> 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.</p> +<p>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.</p> +<p>To enable this mechanism, the following option can be used.</p> +<div class="listingblock"><div class="title">Using raw transport options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">raw</font>, <font color="#993399">6</font>, <font color="#993399">9</font>, <font color="#990000"><<</font> <b><font color="#000000">30:32</font></b><font color="#990000">/</font><font color="#FF6600">native</font> <font color="#990000">>></font>}</tt></pre> +</div></div> +<p>It means go on layer 6, turn on option 9 with the given integer parameter.</p> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/connection_draining/"> + Connection draining + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_2.0/"> + Migrating from Ranch 2.0 to Ranch 2.1 + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/introduction.asciidoc b/docs/en/ranch/2.1/guide/introduction.asciidoc new file mode 100644 index 00000000..a682c46f --- /dev/null +++ b/docs/en/ranch/2.1/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, FreeBSD, macOS and Windows. + +Ranch is developed for Erlang/OTP 22+. + +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/docs/en/ranch/2.1/guide/introduction/index.html b/docs/en/ranch/2.1/guide/introduction/index.html new file mode 100644 index 00000000..9c62fc75 --- /dev/null +++ b/docs/en/ranch/2.1/guide/introduction/index.html @@ -0,0 +1,185 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Introduction</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Introduction</span></h1> + +<p>Ranch is a socket acceptor pool for TCP protocols.</p> +<p>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.</p> +<h2 id="_prerequisites">Prerequisites</h2> +<p>It is assumed the developer already knows Erlang and has some experience with socket programming and TCP protocols.</p> +<h2 id="_supported_platforms">Supported platforms</h2> +<p>Ranch is tested and supported on Linux, FreeBSD, macOS and Windows.</p> +<p>Ranch is developed for Erlang/OTP 22+.</p> +<p>Ranch may be compiled on earlier Erlang versions with small source code modifications but there is no guarantee that it will work as expected.</p> +<h2 id="_versioning">Versioning</h2> +<p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p> + + + + + + + + + + + + <nav style="margin:1em 0"> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/listeners/"> + Listeners + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/listeners.asciidoc b/docs/en/ranch/2.1/guide/listeners.asciidoc new file mode 100644 index 00000000..9ee2d987 --- /dev/null +++ b/docs/en/ranch/2.1/guide/listeners.asciidoc @@ -0,0 +1,479 @@ +== 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 use 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. +* 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/5` +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, + ranch_tcp, #{socket_opts => [{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). + +=== Suspending and resuming a listener + +Listeners can be suspended and resumed by calling +`ranch:suspend_listener/1` and `ranch:resume_listener/1`, +respectively, with the name of the listener as argument. + +Suspending a listener will cause it to stop listening and not accept +new connections, but existing connection processes will not be stopped. + +.Suspending a listener + +[source,erlang] +ranch:suspend_listener(tcp_echo). + +Resuming a listener will cause it to start listening and accept new +connections again. +It is worth mentioning, however, that if the listener is configured +to listen on a random port, it will listen on a different port than +before it was suspended. + +.Resuming a listener + +[source,erlang] +ranch:resume_listener(tcp_echo). + +Whether a listener is currently running or suspended can be queried +by calling `ranch:get_status/1` with the listener name as argument. + +=== 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 overridden when starting the listener, but +they can be overridden using `Transport:setopts/2` in the protocol. + +It will also set `{backlog, 1024}` and `{nodelay, true}`, which +can be overridden 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/5`. + +.Starting a listener for TCP connections on a random port + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, #{socket_opts => [{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. + +=== Listening on a UNIX Domain socket + +On UNIX systems, it is also possible to use Ranch to listen on a UNIX +domain socket by specifying `{local, SocketFile}` for the `ip` socket +option. In this case, the port must be set to 0 or omitted. The given +file must not exist: Ranch must be able to create it. + +.Starting a listener for TCP connections on a UNIX Domain socket + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, #{socket_opts => [ + {ip, {local, "/tmp/ranch_echo.sock"}}, + {port, 0} + ]}, echo_protocol, [] +). + +=== Performing additional setup steps on a listening socket + +If it is necessary to perform additional setup steps on the listening +socket, it is possible to specify a function with the transport option +`post_listen_callback`. This function will be called after the listening +socket has been created but before accepting connections on it, +with the socket as the single argument. + +The function must return either the atom `ok`, after which the listener +will start accepting connections on the socket, or a tuple +`{error, Reason}` which will cause the listener to fail starting with +`Reason`. + +.Setting permissions on a UNIX Domain socket file + +[source,erlang] +---- +PostListenCb = fun (Sock) -> + case ranch_tcp:sockname(Sock) of + {ok, {local, SockFile}} -> + file:change_mode(SockFile, 8#777); + {ok, _} -> + ok; + Error = {error, _} -> + Error + end +end, + +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, #{ + socket_opts => [ + {ip, {local, "/tmp/ranch_echo.sock"}}, + {port, 0}], + post_listen_callback => PostListenCb}, + echo_protocol, [] +). +---- + +=== Accepting connections on an existing socket + +If you want to accept connections on an existing socket, you can write +a custom `ranch_transport` implementation that fetches or otherwise +acquires a listening socket in the `listen/1` callback and returns it +in the form of `{ok, ListenSocket}`. + +The custom `listen/1` function must ensure that the listener process +(usually the process calling it) is also made the controlling process +of the socket it returns. Failing to do so will result in stop/start +and suspend/resume not working properly for that listener. + +=== Limiting the number of concurrent connections + +The `max_connections` transport option allows you to limit the number +of concurrent connections per connection supervisor (see below). +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, + ranch_tcp, #{socket_opts => [{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, + ranch_tcp, #{socket_opts => [{port, 5555}], max_connections => infinity}, + echo_protocol, [] +). + +The maximum number of connections is a soft limit. In practice, it +can reach `max_connections` + the number of acceptors. + +When the maximum number of connections is reached, Ranch will stop +accepting connections. This will not result in further connections +being rejected, as the kernel option allows queueing incoming +connections. The size of this queue is determined by the `backlog` +option and defaults to 1024. Ranch does not know about the number +of connections that are in the backlog. + +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 reference is received +as the first argument of the protocol's `start_link/3` 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. + +=== Customizing the number of acceptor processes + +By default Ranch will use 10 acceptor processes. Their role is +to accept connections and spawn a connection process for every +new connection. + +This number can be tweaked to improve performance. A good +number is typically between 10 or 100 acceptors. You must +measure to find the best value for your application. + +.Specifying a custom number of acceptor processes + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, #{socket_opts => [{port, 5555}], num_acceptors => 42}, + echo_protocol, [] +). + +=== Customizing the number of connection supervisors + +By default Ranch will use one connection supervisor for each +acceptor process (but not vice versa). Their task is to +supervise the connection processes started by an acceptor. +The number of connection supervisors can be tweaked. + +Note that the association between the individual acceptors and +connection supervisors is fixed, meaning that acceptors will +always use the same connection supervisor to start connection +processes. + +.Specifying a custom number of connection supervisors + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, #{socket_opts => [{port, 5555}], num_conns_sups => 42}, + echo_protocol, [] +). + +=== Setting connection count alarms + +The `alarms` transport option allows you to configure alarms +which will be triggered when the number of connections tracked +by one connection supervisor reaches or exceeds the defined treshold. + +The `alarms` transport option takes a map with alarm names as keys and alarm +options as values. + +Any term is allowed as an alarm name. + +Alarm options include the alarm type and a treshold that, when reached, +triggers the given callback. A cooldown prevents the alarm from being +triggered too often. + +.Log warnings when the number of connections exceeds 100 + +[source,erlang] +---- +Alarms = #{ + my_alarm => #{ + type => num_connections, + treshold => 100, + callback => fun(Ref, Name, ConnSup, ConnPids]) -> + logger:warning("Warning (~s): " + "Supervisor ~s of listener ~s " + "has ~b connections", + [Name, Ref, ConnSup, length(ConnPids)]) + end + } +}, +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, #{alarms => Alarms, socket_opts => [{port, 5555}]}, + echo_protocol, [] +). +---- + +In the example code, an alarm named `my_alarm` is defined, which will +call the given function when the number of connections tracked +by the connection supervisor reaches or exceeds 100. When the number of +connections is still (or again) above 100 after the default cooldown +period of 5 seconds, the alarm will trigger again. + +=== When running out of file descriptors + +Operating systems have limits on the number of sockets +which can be opened by applications. When this maximum is +reached the listener can no longer accept new connections. The +accept rate of the listener will be automatically reduced, and a +warning message will be logged. + +---- +=ERROR REPORT==== 13-Jan-2016::12:24:38 === +Ranch acceptor reducing accept rate: out of file descriptors +---- + +If you notice messages like this you should increase the number +of file-descriptors which can be opened by your application. How +this should be done is operating-system dependent. Please consult +the documentation of your operating system. + +=== 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). + +=== Changing transport options + +Ranch allows you to change the transport options of a listener with +the `ranch:set_transport_options/2` function, for example to change the +number of acceptors or to make it listen on a different port. + +.Changing the transport options + +[source,erlang] +ranch:set_transport_options(tcp_echo, NewOpts). + +You can retrieve the current transport options by calling +`ranch:get_transport_options/1`. + +.Retrieving the current transport options + +[source,erlang] +Opts = ranch:get_transport_options(tcp_echo). + +=== Obtaining information about listeners + +Ranch provides two functions for retrieving information about the +listeners, for reporting and diagnostic purposes. + +The `ranch:info/0` function will return detailed information +about all listeners. + +.Retrieving detailed information +[source,erlang] +ranch:info(). + +The `ranch:procs/2` function will return all acceptor or listener +processes for a given listener. + +.Get all acceptor processes +[source,erlang] +ranch:procs(tcp_echo, acceptors). + +.Get all connection processes +[source,erlang] +ranch:procs(tcp_echo, connections). diff --git a/docs/en/ranch/2.1/guide/listeners/index.html b/docs/en/ranch/2.1/guide/listeners/index.html new file mode 100644 index 00000000..1a3bf448 --- /dev/null +++ b/docs/en/ranch/2.1/guide/listeners/index.html @@ -0,0 +1,502 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Listeners</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Listeners</span></h1> + +<p>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 use of transport handlers.</p> +<p>The listener takes care of supervising all the acceptor and connection processes, allowing developers to focus on building their application.</p> +<h2 id="_starting_a_listener">Starting a listener</h2> +<p>Ranch does nothing by default. It is up to the application developer to request that Ranch listens for connections.</p> +<p>A listener can be started and stopped at will.</p> +<p>When starting a listener, a number of different settings are required:</p> +<ul><li>A name to identify it locally and be able to interact with it. +</li> +<li>A transport handler and its associated options. +</li> +<li>A protocol handler and its associated options. +</li> +</ul> +<p>Ranch includes both TCP and SSL transport handlers, respectively <code>ranch_tcp</code> and <code>ranch_ssl</code>.</p> +<p>A listener can be started by calling the <code>ranch:start_listener/5</code> function. Before doing so however, you must ensure that the <code>ranch</code> application is started.</p> +<div class="listingblock"><div class="title">Starting the Ranch application</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">application:start</font></b>(<font color="#FF6600">ranch</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You are then ready to start a listener. Let's call it <code>tcp_echo</code>. It will have a pool of 100 acceptors, use a TCP transport and forward connections to the <code>echo_protocol</code> handler.</p> +<div class="listingblock"><div class="title">Starting a listener for TCP connections on port 5555</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}]}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can try this out by compiling and running the <code>tcp_echo</code> example in the examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em> directory and run the following command:</p> +<div class="listingblock"><div class="title">Building and starting a Ranch example</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make run</tt></pre> +</div></div> +<p>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 <code>Ctrl+]</code> key to escape to the telnet command line and type <code>quit</code> to exit.</p> +<div class="listingblock"><div class="title">Connecting to the example listener with telnet</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ telnet localhost <font color="#993399">5555</font> +Trying <font color="#993399">127.0</font><font color="#990000">.</font><font color="#993399">0.1</font><font color="#990000">...</font> +Connected to localhost<font color="#990000">.</font> +Escape character is <font color="#FF0000">'^]'</font><font color="#990000">.</font> +Hello<font color="#990000">!</font> +Hello<font color="#990000">!</font> +It works<font color="#990000">!</font> +It works<font color="#990000">!</font> +<font color="#990000">^]</font> + +telnet<font color="#990000">></font> quit +Connection closed<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_stopping_a_listener">Stopping a listener</h2> +<p>All you need to stop a Ranch listener is to call the <code>ranch:stop_listener/1</code> function with the listener's name as argument. In the previous section we started the listener named <code>tcp_echo</code>. We can now stop it.</p> +<div class="listingblock"><div class="title">Stopping a listener</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:stop_listener</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_suspending_and_resuming_a_listener">Suspending and resuming a listener</h2> +<p>Listeners can be suspended and resumed by calling <code>ranch:suspend_listener/1</code> and <code>ranch:resume_listener/1</code>, respectively, with the name of the listener as argument.</p> +<p>Suspending a listener will cause it to stop listening and not accept new connections, but existing connection processes will not be stopped.</p> +<div class="listingblock"><div class="title">Suspending a listener</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:suspend_listener</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>Resuming a listener will cause it to start listening and accept new connections again. It is worth mentioning, however, that if the listener is configured to listen on a random port, it will listen on a different port than before it was suspended.</p> +<div class="listingblock"><div class="title">Resuming a listener</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:resume_listener</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>Whether a listener is currently running or suspended can be queried by calling <code>ranch:get_status/1</code> with the listener name as argument.</p> +<h2 id="_default_transport_options">Default transport options</h2> +<p>By default the socket will be set to return <code>binary</code> data, with the options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set. These values can't be overridden when starting the listener, but they can be overridden using <code>Transport:setopts/2</code> in the protocol.</p> +<p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which can be overridden at listener startup.</p> +<h2 id="_listening_on_a_random_port">Listening on a random port</h2> +<p>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.</p> +<p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p> +<div class="listingblock"><div class="title">Starting a listener for TCP connections on a random port</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">0</font>}]}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font> +<font color="#009900">Port</font> <font color="#990000">=</font> <b><font color="#000000">ranch:get_port</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2> +<p>Some systems limit access to ports below 1024 for security reasons. This can easily be identified by an <code>{error, eacces}</code> error when trying to open a listening socket on such a port.</p> +<p>The methods for listening on privileged ports vary between systems, please refer to your system's documentation for more information.</p> +<p>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.</p> +<h2 id="_listening_on_a_unix_domain_socket">Listening on a UNIX Domain socket</h2> +<p>On UNIX systems, it is also possible to use Ranch to listen on a UNIX domain socket by specifying <code>{local, SocketFile}</code> for the <code>ip</code> socket option. In this case, the port must be set to 0 or omitted. The given file must not exist: Ranch must be able to create it.</p> +<div class="listingblock"><div class="title">Starting a listener for TCP connections on a UNIX Domain socket</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [ + {<font color="#FF6600">ip</font>, {<font color="#FF6600">local</font>, <font color="#FF0000">"/tmp/ranch_echo.sock"</font>}}, + {<font color="#FF6600">port</font>, <font color="#993399">0</font>} + ]}, <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_performing_additional_setup_steps_on_a_listening_socket">Performing additional setup steps on a listening socket</h2> +<p>If it is necessary to perform additional setup steps on the listening socket, it is possible to specify a function with the transport option <code>post_listen_callback</code>. This function will be called after the listening socket has been created but before accepting connections on it, with the socket as the single argument.</p> +<p>The function must return either the atom <code>ok</code>, after which the listener will start accepting connections on the socket, or a tuple <code>{error, Reason}</code> which will cause the listener to fail starting with <code>Reason</code>.</p> +<div class="listingblock"><div class="title">Setting permissions on a UNIX Domain socket file</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#009900">PostListenCb</font> <font color="#990000">=</font> <b><font color="#0000FF">fun</font></b> (<font color="#009900">Sock</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">ranch_tcp:sockname</font></b>(<font color="#009900">Sock</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, {<font color="#FF6600">local</font>, <font color="#009900">SockFile</font>}} <font color="#990000">-></font> + <b><font color="#000000">file:change_mode</font></b>(<font color="#009900">SockFile</font>, <font color="#993399">8#777</font>); + {<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">-></font> + <font color="#FF6600">ok</font>; + <font color="#009900">Error</font> <font color="#990000">=</font> {<font color="#FF6600">error</font>, <font color="#990000">_</font>} <font color="#990000">-></font> + <font color="#009900">Error</font> + <b><font color="#0000FF">end</font></b> +<b><font color="#0000FF">end</font></b>, + +{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{ + <font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [ + {<font color="#FF6600">ip</font>, {<font color="#FF6600">local</font>, <font color="#FF0000">"/tmp/ranch_echo.sock"</font>}}, + {<font color="#FF6600">port</font>, <font color="#993399">0</font>}], + <font color="#0000FF">post_listen_callback</font> <font color="#990000">=></font> <font color="#009900">PostListenCb</font>}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2> +<p>If you want to accept connections on an existing socket, you can write a custom <code>ranch_transport</code> implementation that fetches or otherwise acquires a listening socket in the <code>listen/1</code> callback and returns it in the form of <code>{ok, ListenSocket}</code>.</p> +<p>The custom <code>listen/1</code> function must ensure that the listener process (usually the process calling it) is also made the controlling process of the socket it returns. Failing to do so will result in stop/start and suspend/resume not working properly for that listener.</p> +<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2> +<p>The <code>max_connections</code> transport option allows you to limit the number of concurrent connections per connection supervisor (see below). It defaults to 1024. Its purpose is to prevent your system from being overloaded and ensuring all the connections are handled optimally.</p> +<div class="listingblock"><div class="title">Customizing the maximum number of concurrent connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}], <font color="#0000FF">max_connections</font> <font color="#990000">=></font> <font color="#993399">100</font>}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p> +<div class="listingblock"><div class="title">Disabling the limit for the number of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}], <font color="#0000FF">max_connections</font> <font color="#990000">=></font> <font color="#FF6600">infinity</font>}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>The maximum number of connections is a soft limit. In practice, it can reach <code>max_connections</code> + the number of acceptors.</p> +<p>When the maximum number of connections is reached, Ranch will stop accepting connections. This will not result in further connections being rejected, as the kernel option allows queueing incoming connections. The size of this queue is determined by the <code>backlog</code> option and defaults to 1024. Ranch does not know about the number of connections that are in the backlog.</p> +<p>You may not always want connections to be counted when checking for <code>max_connections</code>. 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.</p> +<p>To remove the connection from the count, you must call the <code>ranch:remove_connection/1</code> from within the connection process, with the name of the listener as the only argument.</p> +<div class="listingblock"><div class="title">Removing a connection from the count of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:remove_connection</font></b>(<font color="#009900">Ref</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>As seen in the chapter covering protocols, this reference is received as the first argument of the protocol's <code>start_link/3</code> callback.</p> +<p>You can modify the <code>max_connections</code> value on a running listener by using the <code>ranch:set_max_connections/2</code> function, with the name of the listener as first argument and the new value as the second.</p> +<div class="listingblock"><div class="title">Upgrading the maximum number of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:set_max_connections</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#009900">MaxConns</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>The change will occur immediately.</p> +<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2> +<p>By default Ranch will use 10 acceptor processes. Their role is to accept connections and spawn a connection process for every new connection.</p> +<p>This number can be tweaked to improve performance. A good number is typically between 10 or 100 acceptors. You must measure to find the best value for your application.</p> +<div class="listingblock"><div class="title">Specifying a custom number of acceptor processes</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}], <font color="#0000FF">num_acceptors</font> <font color="#990000">=></font> <font color="#993399">42</font>}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_customizing_the_number_of_connection_supervisors">Customizing the number of connection supervisors</h2> +<p>By default Ranch will use one connection supervisor for each acceptor process (but not vice versa). Their task is to supervise the connection processes started by an acceptor. The number of connection supervisors can be tweaked.</p> +<p>Note that the association between the individual acceptors and connection supervisors is fixed, meaning that acceptors will always use the same connection supervisor to start connection processes.</p> +<div class="listingblock"><div class="title">Specifying a custom number of connection supervisors</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}], <font color="#0000FF">num_conns_sups</font> <font color="#990000">=></font> <font color="#993399">42</font>}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_setting_connection_count_alarms">Setting connection count alarms</h2> +<p>The <code>alarms</code> transport option allows you to configure alarms which will be triggered when the number of connections tracked by one connection supervisor reaches or exceeds the defined treshold.</p> +<p>The <code>alarms</code> transport option takes a map with alarm names as keys and alarm options as values.</p> +<p>Any term is allowed as an alarm name.</p> +<p>Alarm options include the alarm type and a treshold that, when reached, triggers the given callback. A cooldown prevents the alarm from being triggered too often.</p> +<div class="listingblock"><div class="title">Log warnings when the number of connections exceeds 100</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#009900">Alarms</font> <font color="#990000">=</font> #{ + <font color="#0000FF">my_alarm</font> <font color="#990000">=></font> #{ + <font color="#0000FF">type</font> <font color="#990000">=></font> <font color="#FF6600">num_connections</font>, + <font color="#0000FF">treshold</font> <font color="#990000">=></font> <font color="#993399">100</font>, + <font color="#0000FF">callback</font> <font color="#990000">=></font> <b><font color="#0000FF">fun</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Name</font>, <font color="#009900">ConnSup</font>, <font color="#009900">ConnPids</font>]) <font color="#990000">-></font> + <b><font color="#000000">logger:warning</font></b>(<font color="#FF0000">"Warning (~s): "</font> + <font color="#FF0000">"Supervisor ~s of listener ~s "</font> + <font color="#FF0000">"has ~b connections"</font>, + [<font color="#009900">Name</font>, <font color="#009900">Ref</font>, <font color="#009900">ConnSup</font>, <b><font color="#000080">length</font></b>(<font color="#009900">ConnPids</font>)]) + <b><font color="#0000FF">end</font></b> + } +}, +{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">tcp_echo</font>, + <font color="#FF6600">ranch_tcp</font>, #{<font color="#0000FF">alarms</font> <font color="#990000">=></font> <font color="#009900">Alarms</font>, <font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [{<font color="#FF6600">port</font>, <font color="#993399">5555</font>}]}, + <font color="#FF6600">echo_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>In the example code, an alarm named <code>my_alarm</code> is defined, which will call the given function when the number of connections tracked by the connection supervisor reaches or exceeds 100. When the number of connections is still (or again) above 100 after the default cooldown period of 5 seconds, the alarm will trigger again.</p> +<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2> +<p>Operating systems have limits on the number of sockets which can be opened by applications. When this maximum is reached the listener can no longer accept new connections. The accept rate of the listener will be automatically reduced, and a warning message will be logged.</p> +<div class="listingblock"><div class="content"><pre>=ERROR REPORT==== 13-Jan-2016::12:24:38 === +Ranch acceptor reducing accept rate: out of file descriptors</pre></div></div> +<p>If you notice messages like this you should increase the number of file-descriptors which can be opened by your application. How this should be done is operating-system dependent. Please consult the documentation of your operating system.</p> +<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2> +<p>Ranch allows you to define the type of process that will be used for the connection processes. By default it expects a <code>worker</code>. When the <code>connection_type</code> configuration value is set to <code>supervisor</code>, Ranch will consider that the connection process it manages is a supervisor and will reflect that in its supervision tree.</p> +<p>Connection processes of type <code>supervisor</code> 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).</p> +<p>Instead of returning <code>{ok, ConnPid}</code>, simply return <code>{ok, SupPid, ConnPid}</code>.</p> +<p>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.</p> +<h2 id="_upgrading">Upgrading</h2> +<p>Ranch allows you to upgrade the protocol options. This takes effect immediately and for all subsequent connections.</p> +<p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code> with the name of the listener as first argument and the new options as the second.</p> +<div class="listingblock"><div class="title">Upgrading the protocol options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:set_protocol_options</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#009900">NewOpts</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>All future connections will use the new options.</p> +<p>You can also retrieve the current options similarly by calling <code>ranch:get_protocol_options/1</code>.</p> +<div class="listingblock"><div class="title">Retrieving the current protocol options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#009900">Opts</font> <font color="#990000">=</font> <b><font color="#000000">ranch:get_protocol_options</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_changing_transport_options">Changing transport options</h2> +<p>Ranch allows you to change the transport options of a listener with the <code>ranch:set_transport_options/2</code> function, for example to change the number of acceptors or to make it listen on a different port.</p> +<div class="listingblock"><div class="title">Changing the transport options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:set_transport_options</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#009900">NewOpts</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can retrieve the current transport options by calling <code>ranch:get_transport_options/1</code>.</p> +<div class="listingblock"><div class="title">Retrieving the current transport options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#009900">Opts</font> <font color="#990000">=</font> <b><font color="#000000">ranch:get_transport_options</font></b>(<font color="#FF6600">tcp_echo</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2> +<p>Ranch provides two functions for retrieving information about the listeners, for reporting and diagnostic purposes.</p> +<p>The <code>ranch:info/0</code> function will return detailed information about all listeners.</p> +<div class="listingblock"><div class="title">Retrieving detailed information</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:info</font></b>()<font color="#990000">.</font></tt></pre> +</div></div> +<p>The <code>ranch:procs/2</code> function will return all acceptor or listener processes for a given listener.</p> +<div class="listingblock"><div class="title">Get all acceptor processes</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:procs</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#FF6600">acceptors</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<div class="listingblock"><div class="title">Get all connection processes</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">ranch:procs</font></b>(<font color="#FF6600">tcp_echo</font>, <font color="#FF6600">connections</font>)<font color="#990000">.</font></tt></pre> +</div></div> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/introduction/"> + Introduction + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/transports/"> + Transports + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.5.asciidoc b/docs/en/ranch/2.1/guide/migrating_from_1.5.asciidoc new file mode 100644 index 00000000..a454f932 --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.5.asciidoc @@ -0,0 +1,76 @@ +[appendix] +== Migrating from Ranch 1.5 to 1.6 + +Ranch 1.6 added the ability to suspend and resume listeners. +It also deprecates a number of features and add interfaces +that will be used in Ranch 2.0. + +Ranch 1.6 is compatible with Erlang/OTP 18.0 onward. Support +for older releases has been removed. + +=== Features added + +* Listeners can now be suspended/resumed without stopping existing + connection processes. This effectively closes the listening socket + and stops the acceptor processes. + +* Transport options can now be updated for suspended listeners. + +* The `Socket` argument given when the protocol starts has been + deprecated. In Ranch 2.0 the socket will be obtainable only + by calling `ranch:handshake/1,2`. + +* Ranch-specific transport options and socket options are now + better separated. When passing Ranch-specific transport options, + Ranch now expects to receive a map, in which case socket + options are passed in the `socket_opts` value. When there + are only socket options they can be passed to Ranch directly + as a convenience. + +* Any future transport option will only be added to the map + type. This includes transport options added in this release. + +* The transport option `ack_timeout` was renamed to `handshake_timeout` + in the map type. + +* The `cacerts` socket option is now silenced in error logs + just like the `certs` and `key` options. + +* The manual has been heavily updated and now features one + manual page per function and module, complete with a per-function + changelog, examples and more. + +=== Experimental features added + +* It is now possible to configure the restart intensity for + `ranch_sup` using the OTP application environment. This + feature will remain undocumented unless there is popular + demand for it. + +* Add the transport option `logger` that allows configuring + which logger module will be used. The logger module must + follow the interface of the new `logger` module in Erlang/OTP 21, + or be set to `error_logger` to keep the old behavior. + +=== Changed behaviors + +* Transport modules must now implement `Transport:handshake/2,3` + which deprecates and will replace `Transport:accept_ack/1` in + Ranch 2.0. It returns a new socket and can therefore be used + for implementing TLS upgrade mechanisms. + +=== New functions + +* The functions `ranch:suspend_listener/1` and `ranch:resume_listener/1` + were added. In addition the function `ranch:get_state/1` can be used + to obtain the running state of a listener. + +* A function `ranch:wait_for_connections/3` was added. + +* A function `ranch:handshake/1,2` was added to replace the + function `ranch:accept_ack/1`. + +=== Bugs fixed + +* The specs for the function `Transport:sendfile/2,4,5` have been + corrected. The type used for the filename was too restricting. diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.5/index.html b/docs/en/ranch/2.1/guide/migrating_from_1.5/index.html new file mode 100644 index 00000000..ae89f9ed --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.5/index.html @@ -0,0 +1,221 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Migrating from Ranch 1.5 to 1.6</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Migrating from Ranch 1.5 to 1.6</span></h1> + +<p>Ranch 1.6 added the ability to suspend and resume listeners. It also deprecates a number of features and add interfaces that will be used in Ranch 2.0.</p> +<p>Ranch 1.6 is compatible with Erlang/OTP 18.0 onward. Support for older releases has been removed.</p> +<h2 id="_features_added">Features added</h2> +<ul><li>Listeners can now be suspended/resumed without stopping existing connection processes. This effectively closes the listening socket and stops the acceptor processes. +</li> +<li>Transport options can now be updated for suspended listeners. +</li> +<li>The <code>Socket</code> argument given when the protocol starts has been deprecated. In Ranch 2.0 the socket will be obtainable only by calling <code>ranch:handshake/1,2</code>. +</li> +<li>Ranch-specific transport options and socket options are now better separated. When passing Ranch-specific transport options, Ranch now expects to receive a map, in which case socket options are passed in the <code>socket_opts</code> value. When there are only socket options they can be passed to Ranch directly as a convenience. +</li> +<li>Any future transport option will only be added to the map type. This includes transport options added in this release. +</li> +<li>The transport option <code>ack_timeout</code> was renamed to <code>handshake_timeout</code> in the map type. +</li> +<li>The <code>cacerts</code> socket option is now silenced in error logs just like the <code>certs</code> and <code>key</code> options. +</li> +<li>The manual has been heavily updated and now features one manual page per function and module, complete with a per-function changelog, examples and more. +</li> +</ul> +<h2 id="_experimental_features_added">Experimental features added</h2> +<ul><li>It is now possible to configure the restart intensity for <code>ranch_sup</code> using the OTP application environment. This feature will remain undocumented unless there is popular demand for it. +</li> +<li>Add the transport option <code>logger</code> that allows configuring which logger module will be used. The logger module must follow the interface of the new <code>logger</code> module in Erlang/OTP 21, or be set to <code>error_logger</code> to keep the old behavior. +</li> +</ul> +<h2 id="_changed_behaviors">Changed behaviors</h2> +<ul><li>Transport modules must now implement <code>Transport:handshake/2,3</code> which deprecates and will replace <code>Transport:accept_ack/1</code> in Ranch 2.0. It returns a new socket and can therefore be used for implementing TLS upgrade mechanisms. +</li> +</ul> +<h2 id="_new_functions">New functions</h2> +<ul><li>The functions <code>ranch:suspend_listener/1</code> and <code>ranch:resume_listener/1</code> were added. In addition the function <code>ranch:get_state/1</code> can be used to obtain the running state of a listener. +</li> +<li>A function <code>ranch:wait_for_connections/3</code> was added. +</li> +<li>A function <code>ranch:handshake/1,2</code> was added to replace the function <code>ranch:accept_ack/1</code>. +</li> +</ul> +<h2 id="_bugs_fixed">Bugs fixed</h2> +<ul><li>The specs for the function <code>Transport:sendfile/2,4,5</code> have been corrected. The type used for the filename was too restricting. +</li> +</ul> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_1.6/"> + Migrating from Ranch 1.6 to 1.7 + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_1.x/"> + Migrating from Ranch 1.x + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.6.asciidoc b/docs/en/ranch/2.1/guide/migrating_from_1.6.asciidoc new file mode 100644 index 00000000..f0c32e88 --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.6.asciidoc @@ -0,0 +1,46 @@ +[appendix] +== Migrating from Ranch 1.6 to 1.7 + +Ranch 1.7 adds built-in support for the PROXY protocol. + +The PROXY protocol is a simple and efficient way for proxies +to transmit information about the client. + +While a third-party library already existed, it was not +entirely compatible with the Ranch interface, in particular +when socket active mode was involved. This new implementation +fixes that and supports the full protocol with as little +overhead as possible compared to normal operations: just one +extra function call. + +Ranch 1.7 is compatible with Erlang/OTP 19.0 onward. Support +for Erlang/OTP 18 has been removed. + +=== Features added + +* Full support for the PROXY protocol was added. + +=== New functions + +* Add the function `ranch:recv_proxy_header/2` to receive + the PROXY protocol header and parse it. It must be called + before `ranch:handshake/1,2`. + +* Add the functions `ranch_proxy_header:parse/1` and + `ranch_proxy_header:header/1,2` to parse and build a + PROXY protocol header, respectively. + +=== Bugs fixed + +* Fix a race condition when the listener is restarted + after `ranch_listener_sup` crashes. This resulted in + the original options being used even if the options + were updated at runtime. + +* Make the acceptors exit instead of crash when the + listening socket has been closed to prevent + unnecessary logs. + +* Fix an issue where listener information would not get + cleaned up when an embedded listener was stopped. This + was fixed in Ranch 1.6.2. diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.6/index.html b/docs/en/ranch/2.1/guide/migrating_from_1.6/index.html new file mode 100644 index 00000000..13ff2201 --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.6/index.html @@ -0,0 +1,201 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Migrating from Ranch 1.6 to 1.7</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Migrating from Ranch 1.6 to 1.7</span></h1> + +<p>Ranch 1.7 adds built-in support for the PROXY protocol.</p> +<p>The PROXY protocol is a simple and efficient way for proxies to transmit information about the client.</p> +<p>While a third-party library already existed, it was not entirely compatible with the Ranch interface, in particular when socket active mode was involved. This new implementation fixes that and supports the full protocol with as little overhead as possible compared to normal operations: just one extra function call.</p> +<p>Ranch 1.7 is compatible with Erlang/OTP 19.0 onward. Support for Erlang/OTP 18 has been removed.</p> +<h2 id="_features_added">Features added</h2> +<ul><li>Full support for the PROXY protocol was added. +</li> +</ul> +<h2 id="_new_functions">New functions</h2> +<ul><li>Add the function <code>ranch:recv_proxy_header/2</code> to receive the PROXY protocol header and parse it. It must be called before <code>ranch:handshake/1,2</code>. +</li> +<li>Add the functions <code>ranch_proxy_header:parse/1</code> and <code>ranch_proxy_header:header/1,2</code> to parse and build a PROXY protocol header, respectively. +</li> +</ul> +<h2 id="_bugs_fixed">Bugs fixed</h2> +<ul><li>Fix a race condition when the listener is restarted after <code>ranch_listener_sup</code> crashes. This resulted in the original options being used even if the options were updated at runtime. +</li> +<li>Make the acceptors exit instead of crash when the listening socket has been closed to prevent unnecessary logs. +</li> +<li>Fix an issue where listener information would not get cleaned up when an embedded listener was stopped. This was fixed in Ranch 1.6.2. +</li> +</ul> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_1.7/"> + Migrating from Ranch 1.7+ to Ranch 2.0 + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_1.5/"> + Migrating from Ranch 1.5 to 1.6 + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.7.asciidoc b/docs/en/ranch/2.1/guide/migrating_from_1.7.asciidoc new file mode 100644 index 00000000..e9b1c96e --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.7.asciidoc @@ -0,0 +1,163 @@ +[appendix] +== Migrating from Ranch 1.7+ to Ranch 2.0 + +Ranch 2.0 adds support for multiple connection supervisors. + +Ranch 1.x had a bottleneck because it used only a single +connection supervisor. This was more evident when many +connections were dropped at once as the supervisor couldn't +keep up and failed to accept new connections while cleaning +up the old ones. Ranch 2.0 behaves much better in this scenario +by default. Multiple connection supervisors also helps with +concurrently accepting new connections. + +Ranch 2.0 also adds experimental support for opening more +than one listening socket on a single port. + +Starting with Ranch 2.0 we are also providing a +https://github.com/juhlig/prometheus_ranch[Prometheus collector] +as a separate project as well as a +https://github.com/juhlig/prometheus_ranch/blob/master/dashboards/ranch-dashboard.json[Grafana dashboard]. + +Ranch 2.0 is compatible with Erlang/OTP 21.0 onward. Support +for Erlang/OTP 19 and 20 has been removed. + +=== Features added + +* Ranch now comes with a `ranch.appup` file necessary for + performing release upgrades. A test suite has been added + to confirm release upgrades work from one tag to the next. + Numerous fixes were made that will also improve error recovery. + Release upgrades will only be supported from Ranch 2.0 + onward. + +* The `num_conns_sups` option has been added. It allows + configuring the number of connection supervisors. It + now defaults to `num_accceptors`. The old behavior can + be obtained by setting this value to 1. + +* The `logger` option is no longer experimental. It now + defaults to `logger` instead of `error_logger`. + +* UNIX domain sockets are now supported. + +* The active N socket option is now supported. It requires + Erlang/OTP 21.3 or above for TLS, however. + +* Embedded listeners are now failing in a predictable + manner when `ranch_server` goes down. It is no longer + necessary to embed `ranch_sup` and the recommendation + is now to just start Ranch normally when using embedded + listeners. + +* Two steps handshake is now supported. This allows + obtaining TLS extensions and updating options before + resuming the handshake. The handshake can also be + canceled. + +=== Experimental features added + +* The experimental `num_listen_sockets` option has been + added. It allows opening more than one listening socket + per listener. It can only be used alongside the Linux + `SO_REUSEPORT` socket option or equivalent. It allows + working around a bottleneck in the kernel and maximizes + resource usage, leading to increased rates for accepting + new connections. + +=== Features removed + +* The `socket` option was removed. A more viable solution + is to define a custom transport module that returns a fresh + socket when `Transport:listen/1` is called. + +=== Changed behaviors + +* The callback function `Transport:listen/1` and its + implementations in `ranch_tcp` and `ranch_ssl` have changed + to accept a map of transport options instead of only + socket options. + +* The callback function `Transport:messages/0` return value + now includes the tag used for passive messages. + +* The `Socket` argument was removed from `Protocol:start_link/3`. + The socket must now be obtained by calling `ranch:handshake/1,2`. + +=== Added functions + +* The functions `ranch:handshake_continue/1,2` and + `ranch:handshake_cancel/1` can be used to perform + a two steps handshake. These functions may not be + supported by all transports. + +=== Changed functions + +* The `NumAcceptors` argument was removed from `ranch:start_listener/5` + and `ranch:child_spec/5` and moved to the transport options. + +* Ranch options can no longer be passed along with socket options + as a proplist. The only forms allowed are now the `ranch:opts()` + map or only socket options as-is. Individual transport options + are now validated as well. The `ranch:opts()` map must + be used when socket options also use a map. This applies to the + `ranch:start_listener/5`, `ranch:child_spec/5` and + `ranch:set_transport_options/2` functions. + +* The function `ranch:info/1,2` now returns a map containing + each listener's information rather than a list of key/values. + The key `num_acceptors` was removed as it can be found in the + transport options. + +* The function `ranch:set_transport_options/2` no longer requires + the listener to be suspended. Which options apply immediately, + on suspend/resume or on restart has been documented. Some work + has also been done to make these option changes more predictable. + +=== Removed functions + +* The function `ranch:accept_ack/1` has been removed in favor + of `ranch:handshake/1,2`. + +=== Bugs fixed + +* Calling `ranch:remove_connection/1` will now resume a sleeping + acceptor process when applicable. + +* Repeatedly calling `ranch:remove_connection/1` from a connection + process would crash the respective connection supervisor. This has + now been fixed. + +* When a connection process was failing to start, the socket was + not closed and this lead to leaking sockets. This is now corrected. + +=== Other changes + +* Connection draining has now been documented in the guide + following user feedback and discussions. + +* Ranch is now tested against https://concuerror.com/[Concuerror], + a model checking tool for debugging, testing and verifying + concurrent Erlang programs. Two tests have been added in this + release and more will follow in the future. + +* Ranch is now tested against `stampede`, a chaos monkey style + testing tool. Currently includes three scenarios: normal + TCP and TLS listeners and embedded TCP listener. This new + test suite helped uncover a misplaced `monitor/2` call + added during the development of Ranch 2.0 (we were using a + similar tool, `havoc`, at the time of finding that issue). + +* The supervisor for acceptors and the parent supervisor for + connection supervisors now have an adaptive restart + intensity limit set to `1 + ceil(math:log2(NumChildren))` + to allow room for errors when they have many children. + +* Ranch now uses stricter compiler options. Missing function + specs were added to internal modules. + +* Ranch now calls `ssl:handshake/1,2,3` instead of + `ssl:ssl_accept/1,2`. + +* The `ranch_ssl:ssl_opt()` type has been updated to conform + with Erlang/OTP 23.0. diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.7/index.html b/docs/en/ranch/2.1/guide/migrating_from_1.7/index.html new file mode 100644 index 00000000..ee99259a --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.7/index.html @@ -0,0 +1,258 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Migrating from Ranch 1.7+ to Ranch 2.0</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Migrating from Ranch 1.7+ to Ranch 2.0</span></h1> + +<p>Ranch 2.0 adds support for multiple connection supervisors.</p> +<p>Ranch 1.x had a bottleneck because it used only a single connection supervisor. This was more evident when many connections were dropped at once as the supervisor couldn't keep up and failed to accept new connections while cleaning up the old ones. Ranch 2.0 behaves much better in this scenario by default. Multiple connection supervisors also helps with concurrently accepting new connections.</p> +<p>Ranch 2.0 also adds experimental support for opening more than one listening socket on a single port.</p> +<p>Starting with Ranch 2.0 we are also providing a <a href="https://github.com/juhlig/prometheus_ranch">Prometheus collector</a> as a separate project as well as a <a href="https://github.com/juhlig/prometheus_ranch/blob/master/dashboards/ranch-dashboard.json">Grafana dashboard</a>.</p> +<p>Ranch 2.0 is compatible with Erlang/OTP 21.0 onward. Support for Erlang/OTP 19 and 20 has been removed.</p> +<h2 id="_features_added">Features added</h2> +<ul><li>Ranch now comes with a <code>ranch.appup</code> file necessary for performing release upgrades. A test suite has been added to confirm release upgrades work from one tag to the next. Numerous fixes were made that will also improve error recovery. Release upgrades will only be supported from Ranch 2.0 onward. +</li> +<li>The <code>num_conns_sups</code> option has been added. It allows configuring the number of connection supervisors. It now defaults to <code>num_accceptors</code>. The old behavior can be obtained by setting this value to 1. +</li> +<li>The <code>logger</code> option is no longer experimental. It now defaults to <code>logger</code> instead of <code>error_logger</code>. +</li> +<li>UNIX domain sockets are now supported. +</li> +<li>The active N socket option is now supported. It requires Erlang/OTP 21.3 or above for TLS, however. +</li> +<li>Embedded listeners are now failing in a predictable manner when <code>ranch_server</code> goes down. It is no longer necessary to embed <code>ranch_sup</code> and the recommendation is now to just start Ranch normally when using embedded listeners. +</li> +<li>Two steps handshake is now supported. This allows obtaining TLS extensions and updating options before resuming the handshake. The handshake can also be canceled. +</li> +</ul> +<h2 id="_experimental_features_added">Experimental features added</h2> +<ul><li>The experimental <code>num_listen_sockets</code> option has been added. It allows opening more than one listening socket per listener. It can only be used alongside the Linux <code>SO_REUSEPORT</code> socket option or equivalent. It allows working around a bottleneck in the kernel and maximizes resource usage, leading to increased rates for accepting new connections. +</li> +</ul> +<h2 id="_features_removed">Features removed</h2> +<ul><li>The <code>socket</code> option was removed. A more viable solution is to define a custom transport module that returns a fresh socket when <code>Transport:listen/1</code> is called. +</li> +</ul> +<h2 id="_changed_behaviors">Changed behaviors</h2> +<ul><li>The callback function <code>Transport:listen/1</code> and its implementations in <code>ranch_tcp</code> and <code>ranch_ssl</code> have changed to accept a map of transport options instead of only socket options. +</li> +<li>The callback function <code>Transport:messages/0</code> return value now includes the tag used for passive messages. +</li> +<li>The <code>Socket</code> argument was removed from <code>Protocol:start_link/3</code>. The socket must now be obtained by calling <code>ranch:handshake/1,2</code>. +</li> +</ul> +<h2 id="_added_functions">Added functions</h2> +<ul><li>The functions <code>ranch:handshake_continue/1,2</code> and <code>ranch:handshake_cancel/1</code> can be used to perform a two steps handshake. These functions may not be supported by all transports. +</li> +</ul> +<h2 id="_changed_functions">Changed functions</h2> +<ul><li>The <code>NumAcceptors</code> argument was removed from <code>ranch:start_listener/5</code> and <code>ranch:child_spec/5</code> and moved to the transport options. +</li> +<li>Ranch options can no longer be passed along with socket options as a proplist. The only forms allowed are now the <code>ranch:opts()</code> map or only socket options as-is. Individual transport options are now validated as well. The <code>ranch:opts()</code> map must be used when socket options also use a map. This applies to the <code>ranch:start_listener/5</code>, <code>ranch:child_spec/5</code> and <code>ranch:set_transport_options/2</code> functions. +</li> +<li>The function <code>ranch:info/1,2</code> now returns a map containing each listener's information rather than a list of key/values. The key <code>num_acceptors</code> was removed as it can be found in the transport options. +</li> +<li>The function <code>ranch:set_transport_options/2</code> no longer requires the listener to be suspended. Which options apply immediately, on suspend/resume or on restart has been documented. Some work has also been done to make these option changes more predictable. +</li> +</ul> +<h2 id="_removed_functions">Removed functions</h2> +<ul><li>The function <code>ranch:accept_ack/1</code> has been removed in favor of <code>ranch:handshake/1,2</code>. +</li> +</ul> +<h2 id="_bugs_fixed">Bugs fixed</h2> +<ul><li>Calling <code>ranch:remove_connection/1</code> will now resume a sleeping acceptor process when applicable. +</li> +<li>Repeatedly calling <code>ranch:remove_connection/1</code> from a connection process would crash the respective connection supervisor. This has now been fixed. +</li> +<li>When a connection process was failing to start, the socket was not closed and this lead to leaking sockets. This is now corrected. +</li> +</ul> +<h2 id="_other_changes">Other changes</h2> +<ul><li>Connection draining has now been documented in the guide following user feedback and discussions. +</li> +<li>Ranch is now tested against <a href="https://concuerror.com/">Concuerror</a>, a model checking tool for debugging, testing and verifying concurrent Erlang programs. Two tests have been added in this release and more will follow in the future. +</li> +<li>Ranch is now tested against <code>stampede</code>, a chaos monkey style testing tool. Currently includes three scenarios: normal TCP and TLS listeners and embedded TCP listener. This new test suite helped uncover a misplaced <code>monitor/2</code> call added during the development of Ranch 2.0 (we were using a similar tool, <code>havoc</code>, at the time of finding that issue). +</li> +<li>The supervisor for acceptors and the parent supervisor for connection supervisors now have an adaptive restart intensity limit set to <code>1 + ceil(math:log2(NumChildren))</code> to allow room for errors when they have many children. +</li> +<li>Ranch now uses stricter compiler options. Missing function specs were added to internal modules. +</li> +<li>Ranch now calls <code>ssl:handshake/1,2,3</code> instead of <code>ssl:ssl_accept/1,2</code>. +</li> +<li>The <code>ranch_ssl:ssl_opt()</code> type has been updated to conform with Erlang/OTP 23.0. +</li> +</ul> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_2.0/"> + Migrating from Ranch 2.0 to Ranch 2.1 + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_1.6/"> + Migrating from Ranch 1.6 to 1.7 + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.x.asciidoc b/docs/en/ranch/2.1/guide/migrating_from_1.x.asciidoc new file mode 100644 index 00000000..44babf17 --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.x.asciidoc @@ -0,0 +1,70 @@ +[appendix] +== Migrating from Ranch 1.x + +The changelog for Ranch releases before 1.6 can be found +in this section. + +=== 1.5.0 + +* Add transport functions getopts/2, getstat/1 and getstat/2 +* Fix ranch:info/0 and ranch:procs/2 in embedded mode +* Prevent ranch_conns_sup from stopping on unexpected messages + +=== 1.4.0 + +* Add new transport option num_acceptor +* Deprecate ranch:start_listener/6 in favor of start_listener/5 +* Deprecate ranch:child_spec/6 in favor of child_spec/5 + +=== 1.3.0 + +The version numbers 1.3.1 and 1.3.2 were later made to fix +small mistakes made during the 1.3.0 release process. They +do not include code changes. + +* Tested with OTP R16B+ on Linux, FreeBSD, OSX and Windows +* Add ssl to the list of dependencies +* Add ranch:info/0 and ranch:procs/2 to retrieve Ranch state information +* Allow configuring a listener with only SNI, without a default certificate +* Blacklist transport options instead of whitelist +** Unknown options are now allowed, but will result in a Dialyzer warning +* Add many transport options typespecs and documentation +* Don't silently drop the accept rate when running out of fds +* Prevent a race condition when stopping listeners +* Improve reporting for common errors, for example eaddrinuse +* Fix double removal of connections bug +** The number of active connections should now be exact +* Fix stuck acceptor bug when controlling_socket returned errors +* Numerous documentation and examples improvements + +=== 1.2.1 + +* Fix bug preventing node shutdown when SSL is used with OTP 17.1+ +* Tune restart intensity in all supervisors + +=== 1.2.0 + +* Allow the supervised process and the process owning the socket to be different +* Add many transport options (please refer to the documentation) +* Add function ranch:get_addr/1 to retrieve both IP and port of listener +* Don't pass Ranch-specific options down to transports +** Should make Dialyzer happy in user projects +** New types ranch:opt(), ranch_tcp:opt(), ranch_ssl:ssl_opt() and ranch_ssl:opt() +* Fix crash when filtering unknown options out +* Print a warning for each option filtered out +* Handle Transport:controlling_socket/2 errors and close the socket +* Handle Protocol:start_link/4 crashes to avoid killing all active connections +* Use Asciidoc for documentation +* Test Ranch across 14 Erlang versions on CircleCI +* Improve and document test suites with recent ct_helper improvements +* Fix a number of intermittent test issues + +=== 1.1.0 + +* Add Transport:secure/0 +* Add SSL partial_chain option +* Stop reporting errors on {error, closed} in accept_ack + +=== 1.0.0 + +* Initial release diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.x/index.html b/docs/en/ranch/2.1/guide/migrating_from_1.x/index.html new file mode 100644 index 00000000..fd3bcab9 --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_1.x/index.html @@ -0,0 +1,274 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Migrating from Ranch 1.x</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Migrating from Ranch 1.x</span></h1> + +<p>The changelog for Ranch releases before 1.6 can be found in this section.</p> +<h2 id="_1_5_0">1.5.0</h2> +<ul><li>Add transport functions getopts/2, getstat/1 and getstat/2 +</li> +<li>Fix ranch:info/0 and ranch:procs/2 in embedded mode +</li> +<li>Prevent ranch_conns_sup from stopping on unexpected messages +</li> +</ul> +<h2 id="_1_4_0">1.4.0</h2> +<ul><li>Add new transport option num_acceptor +</li> +<li>Deprecate ranch:start_listener/6 in favor of start_listener/5 +</li> +<li>Deprecate ranch:child_spec/6 in favor of child_spec/5 +</li> +</ul> +<h2 id="_1_3_0">1.3.0</h2> +<p>The version numbers 1.3.1 and 1.3.2 were later made to fix small mistakes made during the 1.3.0 release process. They do not include code changes.</p> +<ul><li>Tested with OTP R16B+ on Linux, FreeBSD, OSX and Windows +</li> +<li>Add ssl to the list of dependencies +</li> +<li>Add ranch:info/0 and ranch:procs/2 to retrieve Ranch state information +</li> +<li>Allow configuring a listener with only SNI, without a default certificate +</li> +<li>Blacklist transport options instead of whitelist +<ul><li>Unknown options are now allowed, but will result in a Dialyzer warning +</li> +</ul> +</li> +<li>Add many transport options typespecs and documentation +</li> +<li>Don't silently drop the accept rate when running out of fds +</li> +<li>Prevent a race condition when stopping listeners +</li> +<li>Improve reporting for common errors, for example eaddrinuse +</li> +<li>Fix double removal of connections bug +<ul><li>The number of active connections should now be exact +</li> +</ul> +</li> +<li>Fix stuck acceptor bug when controlling_socket returned errors +</li> +<li>Numerous documentation and examples improvements +</li> +</ul> +<h2 id="_1_2_1">1.2.1</h2> +<ul><li>Fix bug preventing node shutdown when SSL is used with OTP 17.1+ +</li> +<li>Tune restart intensity in all supervisors +</li> +</ul> +<h2 id="_1_2_0">1.2.0</h2> +<ul><li>Allow the supervised process and the process owning the socket to be different +</li> +<li>Add many transport options (please refer to the documentation) +</li> +<li>Add function ranch:get_addr/1 to retrieve both IP and port of listener +</li> +<li>Don't pass Ranch-specific options down to transports +<ul><li>Should make Dialyzer happy in user projects +</li> +<li>New types ranch:opt(), ranch_tcp:opt(), ranch_ssl:ssl_opt() and ranch_ssl:opt() +</li> +</ul> +</li> +<li>Fix crash when filtering unknown options out +</li> +<li>Print a warning for each option filtered out +</li> +<li>Handle Transport:controlling_socket/2 errors and close the socket +</li> +<li>Handle Protocol:start_link/4 crashes to avoid killing all active connections +</li> +<li>Use Asciidoc for documentation +</li> +<li>Test Ranch across 14 Erlang versions on CircleCI +</li> +<li>Improve and document test suites with recent ct_helper improvements +</li> +<li>Fix a number of intermittent test issues +</li> +</ul> +<h2 id="_1_1_0">1.1.0</h2> +<ul><li>Add Transport:secure/0 +</li> +<li>Add SSL partial_chain option +</li> +<li>Stop reporting errors on {error, closed} in accept_ack +</li> +</ul> +<h2 id="_1_0_0">1.0.0</h2> +<ul><li>Initial release +</li> +</ul> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_1.5/"> + Migrating from Ranch 1.5 to 1.6 + </a> + + + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/migrating_from_2.0.asciidoc b/docs/en/ranch/2.1/guide/migrating_from_2.0.asciidoc new file mode 100644 index 00000000..2b4b192c --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_2.0.asciidoc @@ -0,0 +1,70 @@ +[appendix] +== Migrating from Ranch 2.0 to Ranch 2.1 + +Ranch 2.1 adds counters and alarms. + +The https://github.com/juhlig/prometheus_ranch[Prometheus collector] +was updated to include accepted/terminated connections +metrics. + +Ranch 2.1 is compatible with Erlang/OTP 22.0 onward. Support +for Erlang/OTP 21 has been removed. + +=== Features added + +* Metrics are now provided by `ranch:info/0,1`. Currently + includes accepted/terminated connection counts per + connection supervisor. + +* Alarms can now be configured. The only alarm currently + available is `num_connections`. When the number of + connections goes over a configurable treshold Ranch + will call the given callback. This can be used to + programmatically shut down idle connections to + make up space for new connections, for example. + +* A `post_listen` callback option has been added. It + receives sockets immediately after the `Transport:listen/1` + call. It can be used for some additional initialization + of the socket, such as setting file permissions on + Unix domain sockets. + +* It is now possible to use TLS-PSK authentication + without having to specify a default certificate + for TLS < 1.3. + +=== Experimental features added + +* The `inet_backend` option is now properly handled + and tested for TCP listeners. This allows using + the experimental `socket` backend. The `socket` + backend is now tested with Ranch. Note that + there are known issues and Windows support is not + currently implemented. + +=== Changed behaviors + +* Ranch will now remove unsupported SSL/TLS options + where applicable. A warning will be logged when + this happens. Options are only removed when they + are not compatible with the selected TLS version + and leaving them would prevent the listener from + starting. ++ + The following options are removed when using TLS + 1.1, 1.2 or 1.3: `beast_mitigation` and `padding_check`. ++ + The following options are removed when using TLS + 1.3 exclusively: `client_renegotiation`, + `next_protocols_advertised`, `psk_identity`, + `reuse_session`, `reuse_sessions`, + `secure_renegotiate` and `user_lookup_fun`. + +=== Added functions + +* The function `ranch_proxy_header:to_connection_info/1` + converts PROXY protocol information to the same + format as `ssl:connection_information/1`. Because + there is little overlap only the `protocol`, + `selected_cipher_suite` and `sni_hostname` will + be available, however. diff --git a/docs/en/ranch/2.1/guide/migrating_from_2.0/index.html b/docs/en/ranch/2.1/guide/migrating_from_2.0/index.html new file mode 100644 index 00000000..2e17a487 --- /dev/null +++ b/docs/en/ranch/2.1/guide/migrating_from_2.0/index.html @@ -0,0 +1,206 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Migrating from Ranch 2.0 to Ranch 2.1</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Migrating from Ranch 2.0 to Ranch 2.1</span></h1> + +<p>Ranch 2.1 adds counters and alarms.</p> +<p>The <a href="https://github.com/juhlig/prometheus_ranch">Prometheus collector</a> was updated to include accepted/terminated connections metrics.</p> +<p>Ranch 2.1 is compatible with Erlang/OTP 22.0 onward. Support for Erlang/OTP 21 has been removed.</p> +<h2 id="_features_added">Features added</h2> +<ul><li>Metrics are now provided by <code>ranch:info/0,1</code>. Currently includes accepted/terminated connection counts per connection supervisor. +</li> +<li>Alarms can now be configured. The only alarm currently available is <code>num_connections</code>. When the number of connections goes over a configurable treshold Ranch will call the given callback. This can be used to programmatically shut down idle connections to make up space for new connections, for example. +</li> +<li>A <code>post_listen</code> callback option has been added. It receives sockets immediately after the <code>Transport:listen/1</code> call. It can be used for some additional initialization of the socket, such as setting file permissions on Unix domain sockets. +</li> +<li>It is now possible to use TLS-PSK authentication without having to specify a default certificate for TLS < 1.3. +</li> +</ul> +<h2 id="_experimental_features_added">Experimental features added</h2> +<ul><li>The <code>inet_backend</code> option is now properly handled and tested for TCP listeners. This allows using the experimental <code>socket</code> backend. The <code>socket</code> backend is now tested with Ranch. Note that there are known issues and Windows support is not currently implemented. +</li> +</ul> +<h2 id="_changed_behaviors">Changed behaviors</h2> +<ul><li>Ranch will now remove unsupported SSL/TLS options where applicable. A warning will be logged when this happens. Options are only removed when they are not compatible with the selected TLS version and leaving them would prevent the listener from starting. +<p>The following options are removed when using TLS 1.1, 1.2 or 1.3: <code>beast_mitigation</code> and <code>padding_check</code>.</p> +<p>The following options are removed when using TLS 1.3 exclusively: <code>client_renegotiation</code>, <code>next_protocols_advertised</code>, <code>psk_identity</code>, <code>reuse_session</code>, <code>reuse_sessions</code>, <code>secure_renegotiate</code> and <code>user_lookup_fun</code>.</p> +</li> +</ul> +<h2 id="_added_functions">Added functions</h2> +<ul><li>The function <code>ranch_proxy_header:to_connection_info/1</code> converts PROXY protocol information to the same format as <code>ssl:connection_information/1</code>. Because there is little overlap only the <code>protocol</code>, <code>selected_cipher_suite</code> and <code>sni_hostname</code> will be available, however. +</li> +</ul> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/internals/"> + Internals + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/migrating_from_1.7/"> + Migrating from Ranch 1.7+ to Ranch 2.0 + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/parsers.asciidoc b/docs/en/ranch/2.1/guide/parsers.asciidoc new file mode 100644 index 00000000..7a9c5a53 --- /dev/null +++ b/docs/en/ranch/2.1/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/docs/en/ranch/2.1/guide/parsers/index.html b/docs/en/ranch/2.1/guide/parsers/index.html new file mode 100644 index 00000000..ffcb0932 --- /dev/null +++ b/docs/en/ranch/2.1/guide/parsers/index.html @@ -0,0 +1,241 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Writing parsers</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Writing parsers</span></h1> + +<p>There are three kinds of protocols:</p> +<ul><li>Text protocols +</li> +<li>Schema-less binary protocols +</li> +<li>Schema-based binary protocols +</li> +</ul> +<p>This chapter introduces the first two kinds. It will not cover more advanced topics such as continuations or parser generators.</p> +<p>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.</p> +<h2 id="_parsing_text">Parsing text</h2> +<p>Text protocols are generally line based. This means that we can't do anything with them until we receive the full line.</p> +<p>A simple way to get a full line is to use <code>binary:split/2,3</code>.</p> +<div class="listingblock"><div class="title">Using binary:split/2 to get a line of input</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#0000FF">case</font></b> <b><font color="#000000">binary:split</font></b>(<font color="#009900">Buffer</font>, <font color="#990000"><<</font><font color="#FF0000">"\n"</font><font color="#990000">>></font>) <b><font color="#0000FF">of</font></b> + [<font color="#990000">_</font>] <font color="#990000">-></font> + <b><font color="#000000">get_more_data</font></b>(<font color="#009900">Buffer</font>); + [<font color="#009900">Line</font>, <font color="#009900">Rest</font>] <font color="#990000">-></font> + <b><font color="#000000">handle_line</font></b>(<font color="#009900">Line</font>, <font color="#009900">Rest</font>) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>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.</p> +<p>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.</p> +<div class="listingblock"><div class="title">Using binary:split/3 to split text</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#0000FF">case</font></b> <b><font color="#000000">binary:split</font></b>(<font color="#009900">Line</font>, <font color="#990000"><<</font><font color="#FF0000">" "</font><font color="#990000">>></font>, [<font color="#FF6600">global</font>]) <b><font color="#0000FF">of</font></b> + [<font color="#990000"><<</font><font color="#FF0000">"HELLO"</font><font color="#990000">>></font>] <font color="#990000">-></font> + <b><font color="#000000">be_polite</font></b>(); + [<font color="#990000"><<</font><font color="#FF0000">"AUTH"</font><font color="#990000">>></font>, <font color="#009900">User</font>, <font color="#009900">Password</font>] <font color="#990000">-></font> + <b><font color="#000000">authenticate_user</font></b>(<font color="#009900">User</font>, <font color="#009900">Password</font>); + [<font color="#990000"><<</font><font color="#FF0000">"QUIT"</font><font color="#990000">>></font>, <font color="#009900">Reason</font>] <font color="#990000">-></font> + <b><font color="#000000">quit</font></b>(<font color="#009900">Reason</font>) + <i><font color="#9A1900">%% ...</font></i> +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>Pretty simple, right? Match on the command name, get the rest of the tokens in variables and call the respective functions.</p> +<p>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.</p> +<h2 id="_parsing_binary">Parsing binary</h2> +<p>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.</p> +<p>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.</p> +<p>The general idea stays the same though.</p> +<div class="listingblock"><div class="title">Using binary pattern matching to split frames</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#990000"><<</font> <font color="#009900">Size</font><font color="#990000">:</font><font color="#993399">32</font>, <font color="#990000">_/</font><font color="#FF6600">bits</font> <font color="#990000">>></font> <font color="#990000">=</font> <font color="#009900">Buffer</font>, +<b><font color="#0000FF">case</font></b> <font color="#009900">Buffer</font> <b><font color="#0000FF">of</font></b> + <font color="#990000"><<</font> <font color="#009900">Frame</font><font color="#990000">:</font><font color="#009900">Size</font><font color="#990000">/</font><b><font color="#000080">binary</font></b>, <font color="#009900">Rest</font><font color="#990000">/</font><font color="#FF6600">bits</font> <font color="#990000">>></font> <font color="#990000">-></font> + <b><font color="#000000">handle_frame</font></b>(<font color="#009900">Frame</font>, <font color="#009900">Rest</font>); + <font color="#990000">_</font> <font color="#990000">-></font> + <b><font color="#000000">get_more_data</font></b>(<font color="#009900">Buffer</font>) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>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.</p> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/embedded/"> + Embedded mode + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/ssl_auth/"> + SSL client authentication + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/protocols.asciidoc b/docs/en/ranch/2.1/guide/protocols.asciidoc new file mode 100644 index 00000000..8f55cea2 --- /dev/null +++ b/docs/en/ranch/2.1/guide/protocols.asciidoc @@ -0,0 +1,113 @@ +== 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/3`. This callback is +responsible for spawning a new process for handling the connection. +It receives three arguments: the name of the listener, the +transport handler being used and the protocol options defined in +the call to `ranch:start_listener/5`. 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:handshake/1,2` 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. + +.Perform the socket handshake + +[source,erlang] +{ok, Socket} = ranch:handshake(Ref). + +If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling `ranch:handshake/1,2`. 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/3]). +-export([init/3]). + +start_link(Ref, Transport, Opts) -> + Pid = spawn_link(?MODULE, init, [Ref, Transport, Opts]), + {ok, Pid}. + +init(Ref, Transport, _Opts = []) -> + {ok, Socket} = ranch:handshake(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_statem and gen_server + +Special processes like the ones that use the `gen_statem` or `gen_server` +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:handshake/1,2` from the `init` callback +as this would cause a deadlock to happen. + +This problem can be addressed in several ways. + +==== gen_statem + +* Use state enter calls and place the `ranch:handshake/1,2` call in the enter + clause of the initial state. Check the `tcp_reverse` example for a complete + example. +* Use a `next_event` action in the return from `init/1` and place the + `ranch:handshake/1,2` call in the clause handling the event in the initial + state. +* Use the `gen_statem:enter_loop/4` function and start your process with + `proc_lib:spawn_link/3` or `proc_lib:start_link/3,4,5`. See below for an + example. + +.Using gen_statem:enter_loop/4 to start a protocol + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_statem). +-behaviour(ranch_protocol). + +-export([start_link/3]). +-export([init/1]). +%% Exports of other gen_statem callbacks here. + +start_link(Ref, Transport, Opts) -> + {ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Transport, Opts}])}. + +init({Ref, Transport, _Opts}) -> + %% Perform any required state initialization here. + {ok, Socket} = ranch:handshake(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + gen_statem:enter_loop(?MODULE, [], state_name, {state_data, Socket, Transport}). + +%% Other gen_statem callbacks here. +---- + +==== gen_server + +* Use `{continue, Continue}` in the return from `init/1` and place the + `ranch:handshake/1,2` call in a corresponding `handle_continue/2` clause. +* Use the `gen_server:enter_loop/3` function and start your process with + `proc_lib:spawn_link/3` or `proc_lib:start_link/3,4,5`. diff --git a/docs/en/ranch/2.1/guide/protocols/index.html b/docs/en/ranch/2.1/guide/protocols/index.html new file mode 100644 index 00000000..d275248c --- /dev/null +++ b/docs/en/ranch/2.1/guide/protocols/index.html @@ -0,0 +1,261 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Protocols</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Protocols</span></h1> + +<p>A protocol handler starts a connection process and defines the protocol logic executed in this process.</p> +<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2> +<p>All protocol handlers must implement the <code>ranch_protocol</code> behavior which defines a single callback, <code>start_link/3</code>. This callback is responsible for spawning a new process for handling the connection. It receives three arguments: the name of the listener, the transport handler being used and the protocol options defined in the call to <code>ranch:start_listener/5</code>. This callback must return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p> +<p>The newly started process can then freely initialize itself. However, it must call <code>ranch:handshake/1,2</code> 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.</p> +<div class="listingblock"><div class="title">Perform the socket handshake</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">Socket</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:handshake</font></b>(<font color="#009900">Ref</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>If your protocol code requires specific socket options, you should set them while initializing your connection process, after calling <code>ranch:handshake/1,2</code>. You can use <code>Transport:setopts/2</code> for that purpose.</p> +<p>Following is the complete protocol code for the example found in <code>examples/tcp_echo/</code>.</p> +<div class="listingblock"><div class="title">Protocol module that echoes everything it receives</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000080">-module</font></b>(<font color="#FF6600">echo_protocol</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">ranch_protocol</font>)<font color="#990000">.</font> + +<b><font color="#000080">-export</font></b>([<b><font color="#000000">start_link</font></b><font color="#990000">/</font><font color="#993399">3</font>])<font color="#990000">.</font> +<b><font color="#000080">-export</font></b>([<b><font color="#000000">init</font></b><font color="#990000">/</font><font color="#993399">3</font>])<font color="#990000">.</font> + +<b><font color="#000000">start_link</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>) <font color="#990000">-></font> + <font color="#009900">Pid</font> <font color="#990000">=</font> <b><font color="#000080">spawn_link</font></b>(<b><font color="#000080">?MODULE</font></b>, <font color="#FF6600">init</font>, [<font color="#009900">Ref</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>]), + {<font color="#FF6600">ok</font>, <font color="#009900">Pid</font>}<font color="#990000">.</font> + +<b><font color="#000000">init</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Transport</font>, <font color="#009900">_Opts</font> <font color="#990000">=</font> []) <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">Socket</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:handshake</font></b>(<font color="#009900">Ref</font>), + <b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>)<font color="#990000">.</font> + +<b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">recv</font></b>(<font color="#009900">Socket</font>, <font color="#993399">0</font>, <font color="#993399">5000</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">-></font> + <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Data</font>), + <b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>); + <font color="#990000">_</font> <font color="#990000">-></font> + <font color="#0000FF">ok</font> <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">close</font></b>(<font color="#009900">Socket</font>) + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_using_gen_statem_and_gen_server">Using gen_statem and gen_server</h2> +<p>Special processes like the ones that use the <code>gen_statem</code> or <code>gen_server</code> behaviours have the particularity of having their <code>start_link</code> call not return until the <code>init</code> function returns. This is problematic, because you won't be able to call <code>ranch:handshake/1,2</code> from the <code>init</code> callback as this would cause a deadlock to happen.</p> +<p>This problem can be addressed in several ways.</p> +<h4 id="_gen_statem">gen_statem</h4> +<ul><li>Use state enter calls and place the <code>ranch:handshake/1,2</code> call in the enter clause of the initial state. Check the <code>tcp_reverse</code> example for a complete example. +</li> +<li>Use a <code>next_event</code> action in the return from <code>init/1</code> and place the <code>ranch:handshake/1,2</code> call in the clause handling the event in the initial state. +</li> +<li>Use the <code>gen_statem:enter_loop/4</code> function and start your process with <code>proc_lib:spawn_link/3</code> or <code>proc_lib:start_link/3,4,5</code>. See below for an example. +</li> +</ul> +<div class="listingblock"><div class="title">Using gen_statem:enter_loop/4 to start a protocol</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000080">-module</font></b>(<font color="#FF6600">my_protocol</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">gen_statem</font>)<font color="#990000">.</font> +<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">ranch_protocol</font>)<font color="#990000">.</font> + +<b><font color="#000080">-export</font></b>([<b><font color="#000000">start_link</font></b><font color="#990000">/</font><font color="#993399">3</font>])<font color="#990000">.</font> +<b><font color="#000080">-export</font></b>([<b><font color="#000000">init</font></b><font color="#990000">/</font><font color="#993399">1</font>])<font color="#990000">.</font> +<i><font color="#9A1900">%% Exports of other gen_statem callbacks here.</font></i> + +<b><font color="#000000">start_link</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>) <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <b><font color="#000000">proc_lib:spawn_link</font></b>(<b><font color="#000080">?MODULE</font></b>, <font color="#FF6600">init</font>, [{<font color="#009900">Ref</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>}])}<font color="#990000">.</font> + +<b><font color="#000000">init</font></b>({<font color="#009900">Ref</font>, <font color="#009900">Transport</font>, <font color="#009900">_Opts</font>}) <font color="#990000">-></font> + <i><font color="#9A1900">%% Perform any required state initialization here.</font></i> + {<font color="#FF6600">ok</font>, <font color="#009900">Socket</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:handshake</font></b>(<font color="#009900">Ref</font>), + <font color="#0000FF">ok</font> <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">setopts</font></b>(<font color="#009900">Socket</font>, [{<font color="#FF6600">active</font>, <font color="#FF6600">once</font>}]), + <b><font color="#000000">gen_statem:enter_loop</font></b>(<b><font color="#000080">?MODULE</font></b>, [], <font color="#FF6600">state_name</font>, {<font color="#FF6600">state_data</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>})<font color="#990000">.</font> + +<i><font color="#9A1900">%% Other gen_statem callbacks here.</font></i></tt></pre> +</div></div> +<h4 id="_gen_server">gen_server</h4> +<ul><li>Use <code>{continue, Continue}</code> in the return from <code>init/1</code> and place the <code>ranch:handshake/1,2</code> call in a corresponding <code>handle_continue/2</code> clause. +</li> +<li>Use the <code>gen_server:enter_loop/3</code> function and start your process with <code>proc_lib:spawn_link/3</code> or <code>proc_lib:start_link/3,4,5</code>. +</li> +</ul> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/transports/"> + Transports + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/embedded/"> + Embedded mode + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/ssl_auth.asciidoc b/docs/en/ranch/2.1/guide/ssl_auth.asciidoc new file mode 100644 index 00000000..f4364d06 --- /dev/null +++ b/docs/en/ranch/2.1/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 certificate. + +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 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, + ranch_ssl, #{socket_opts => [ + {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/docs/en/ranch/2.1/guide/ssl_auth/index.html b/docs/en/ranch/2.1/guide/ssl_auth/index.html new file mode 100644 index 00000000..2ad9a96a --- /dev/null +++ b/docs/en/ranch/2.1/guide/ssl_auth/index.html @@ -0,0 +1,254 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: SSL client authentication</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>SSL client authentication</span></h1> + +<h2 id="_purpose">Purpose</h2> +<p>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.</p> +<p>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 certificate.</p> +<p>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 <code>Transport:name/0</code>.</p> +<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2> +<p>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.</p> +<p>Following are the steps you need to take to create a CAcert.org account, generate a certificate and install it in your favorite browser.</p> +<ul><li>Open <a href="http://cacert.org">http://cacert.org</a> in your favorite browser +</li> +<li>Root Certificate link: install both certificates +</li> +<li>Join (Register an account) +</li> +<li>Verify your account (check your email inbox!) +</li> +<li>Log in +</li> +<li>Client Certificates: New +</li> +<li>Follow instructions to create the certificate +</li> +<li>Install the certificate in your browser +</li> +</ul> +<p>You can optionally save the certificate for later use, for example to extract the <code>IssuerID</code> information as will be detailed later on.</p> +<h2 id="_transport_configuration">Transport configuration</h2> +<p>The SSL transport does not request a client certificate by default. You need to specify the <code>{verify, verify_peer}</code> option when starting the listener to enable this behavior.</p> +<div class="listingblock"><div class="title">Configure a listener for SSL authentication</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#990000">_</font>} <font color="#990000">=</font> <b><font color="#000000">ranch:start_listener</font></b>(<font color="#FF6600">my_ssl</font>, + <font color="#FF6600">ranch_ssl</font>, #{<font color="#0000FF">socket_opts</font> <font color="#990000">=></font> [ + {<font color="#FF6600">port</font>, <font color="#009900">SSLPort</font>}, + {<font color="#FF6600">certfile</font>, <font color="#009900">PathToCertfile</font>}, + {<font color="#FF6600">cacertfile</font>, <font color="#009900">PathToCACertfile</font>}, + {<font color="#FF6600">verify</font>, <font color="#FF6600">verify_peer</font>} + ]}, + <font color="#FF6600">my_protocol</font>, [] +)<font color="#990000">.</font></tt></pre> +</div></div> +<p>In this example we set the required <code>port</code> and <code>certfile</code>, but also the <code>cacertfile</code> containing the CACert.org root certificate, and the option to request the client certificate.</p> +<p>If you enable the <code>{verify, verify_peer}</code> 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.</p> +<h2 id="_authentication">Authentication</h2> +<p>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.</p> +<div class="listingblock"><div class="title">Retrieve the issuer ID from a certificate</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">certfile_to_issuer_id</font></b>(<font color="#009900">Filename</font>) <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">=</font> <b><font color="#000000">file:read_file</font></b>(<font color="#009900">Filename</font>), + [{<font color="#FF6600">'Certificate'</font>, <font color="#009900">Cert</font>, <font color="#FF6600">not_encrypted</font>}] <font color="#990000">=</font> <b><font color="#000000">public_key:pem_decode</font></b>(<font color="#009900">Data</font>), + {<font color="#FF6600">ok</font>, <font color="#009900">IssuerID</font>} <font color="#990000">=</font> <b><font color="#000000">public_key:pkix_issuer_id</font></b>(<font color="#009900">Cert</font>, <b><font color="#000080">self</font></b>), + <font color="#009900">IssuerID</font><font color="#990000">.</font></tt></pre> +</div></div> +<p>The <code>IssuerID</code> 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.</p> +<p>To retrieve the <code>IssuerID</code> 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 <code>ssl:peercert/1</code> function. Once you have the certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to extract the <code>IssuerID</code> value.</p> +<p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client certificate was found. This snippet is intended to be used from your protocol code.</p> +<div class="listingblock"><div class="title">Retrieve the issuer ID from the certificate for the current connection</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><b><font color="#000000">socket_to_issuer_id</font></b>(<font color="#009900">Socket</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">ssl:peercert</font></b>(<font color="#009900">Socket</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">error</font>, <font color="#FF6600">no_peercert</font>} <font color="#990000">-></font> + <font color="#000080">false</font>; + {<font color="#FF6600">ok</font>, <font color="#009900">Cert</font>} <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">IssuerID</font>} <font color="#990000">=</font> <b><font color="#000000">public_key:pkix_issuer_id</font></b>(<font color="#009900">Cert</font>, <b><font color="#000080">self</font></b>), + <font color="#009900">IssuerID</font> + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>You then only need to match the <code>IssuerID</code> value to authenticate the user.</p> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/parsers/"> + Writing parsers + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/connection_draining/"> + Connection draining + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/2.1/guide/transports.asciidoc b/docs/en/ranch/2.1/guide/transports.asciidoc new file mode 100644 index 00000000..73747fd5 --- /dev/null +++ b/docs/en/ranch/2.1/guide/transports.asciidoc @@ -0,0 +1,177 @@ +== 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`. + +Ranch depends on `ssl` by default so any necessary +dependencies will start when Ranch is started. It is +possible to remove the dependency when the SSL transport +will not be used. Refer to your release build tool's +documentation for more information. + +When embedding Ranch listeners that have an SSL transport, +your application must depend on the `ssl` application for +proper behavior. + +=== 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 three kinds of active modes: `{active, once}`, `{active, N}` +and `{active, true}`. The first will send a single message before going +back to passive mode; the second will send `N` messages followed by +a `Passive` message when switching back to passive mode; the third +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. + +Four different messages can be received: + +* Incoming data: `{OK, Socket, Data}` +* Socket closed: `{Closed, Socket}` +* Socket error: `{Error, Socket, Reason}` +* Switch to passive mode: `{Passive, Socket}` + +The value of `OK`, `Closed`, `Error` and `Passive` 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, Passive} = 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, Passive} = 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). + +=== Upgrading a TCP socket to SSL + +A connected TCP socket can be upgraded to a SSL socket via the function +`ranch_ssl:handshake/3`. The socket *must* be in `{active, false}` mode +before telling the client that the server is ready to upgrade in order +to avoid race conditions. + +IMPORTANT: The new socket received from `ranch_ssl:handshake/3` must be +used via the `ranch_ssl` transport. + +.Performing a TLS handshake on a TCP socket +[source,erlang] +{ok, SslSocket} = ranch_ssl:handshake(TcpSocket, SslOpts, 5000). + +=== 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. diff --git a/docs/en/ranch/2.1/guide/transports/index.html b/docs/en/ranch/2.1/guide/transports/index.html new file mode 100644 index 00000000..b6238f4b --- /dev/null +++ b/docs/en/ranch/2.1/guide/transports/index.html @@ -0,0 +1,291 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <title>Nine Nines: Transports</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=7" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Transports</span></h1> + +<p>A transport defines the interface to interact with a socket.</p> +<p>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.</p> +<h2 id="_tcp_transport">TCP transport</h2> +<p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p> +<h2 id="_ssl_transport">SSL transport</h2> +<p>The SSL transport is a thin wrapper around <code>ssl</code>.</p> +<p>Ranch depends on <code>ssl</code> by default so any necessary dependencies will start when Ranch is started. It is possible to remove the dependency when the SSL transport will not be used. Refer to your release build tool's documentation for more information.</p> +<p>When embedding Ranch listeners that have an SSL transport, your application must depend on the <code>ssl</code> application for proper behavior.</p> +<h2 id="_sending_and_receiving_data">Sending and receiving data</h2> +<p>This section assumes that <code>Transport</code> is a valid transport handler (like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected socket obtained through the listener.</p> +<p>You can send data to a socket by calling the <code>Transport:send/2</code> function. The data can be given as <code>iodata()</code>, which is defined as <code>binary() | iolist()</code>. All the following calls will work:</p> +<div class="listingblock"><div class="title">Sending data to the socket</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#990000"><<</font><font color="#FF0000">"Ranch is cool!"</font><font color="#990000">>></font>)<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#FF0000">"Ranch is cool!"</font>)<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, [<font color="#FF0000">"Ranch"</font>, [<font color="#FF0000">"is"</font>, <font color="#FF0000">"cool!"</font>]])<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, [<font color="#FF0000">"Ranch"</font>, [<font color="#990000"><<</font><font color="#FF0000">"is"</font><font color="#990000">>></font>, <font color="#FF0000">"cool!"</font>]])<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can receive data either in passive or in active mode. Passive mode means that you will perform a blocking <code>Transport:recv/3</code> call, while active mode means that you will receive the data as a message.</p> +<p>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.</p> +<p>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 <code>{error, timeout}</code>.</p> +<p>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.</p> +<div class="listingblock"><div class="title">Receiving data from the socket in passive mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">recv</font></b>(<font color="#009900">Socket</font>, <font color="#993399">0</font>, <font color="#993399">5000</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>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.</p> +<p>There are three kinds of active modes: <code>{active, once}</code>, <code>{active, N}</code> and <code>{active, true}</code>. The first will send a single message before going back to passive mode; the second will send <code>N</code> messages followed by a <code>Passive</code> message when switching back to passive mode; the third will send messages indefinitely. We recommend not using the <code>{active, true}</code> 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.</p> +<p>Four different messages can be received:</p> +<ul><li>Incoming data: <code>{OK, Socket, Data}</code> +</li> +<li>Socket closed: <code>{Closed, Socket}</code> +</li> +<li>Socket error: <code>{Error, Socket, Reason}</code> +</li> +<li>Switch to passive mode: <code>{Passive, Socket}</code> +</li> +</ul> +<p>The value of <code>OK</code>, <code>Closed</code>, <code>Error</code> and <code>Passive</code> can be different depending on the transport being used. To be able to properly match on them you must first call the <code>Transport:messages/0</code> function.</p> +<div class="listingblock"><div class="title">Retrieving the transport's active message identifiers</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#009900">OK</font>, <font color="#009900">Closed</font>, <font color="#009900">Error</font>, <font color="#009900">Passive</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">messages</font></b>()<font color="#990000">.</font></tt></pre> +</div></div> +<p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> function, and do so every time you want to receive data.</p> +<div class="listingblock"><div class="title">Receiving messages from the socket in active mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#009900">OK</font>, <font color="#009900">Closed</font>, <font color="#009900">Error</font>, <font color="#009900">Passive</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">messages</font></b>(), +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">setopts</font></b>(<font color="#009900">Socket</font>, [{<font color="#FF6600">active</font>, <font color="#FF6600">once</font>}]), +<b><font color="#0000FF">receive</font></b> + {<font color="#009900">OK</font>, <font color="#009900">Socket</font>, <font color="#009900">Data</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"data received: ~p~n"</font>, [<font color="#009900">Data</font>]); + {<font color="#009900">Closed</font>, <font color="#009900">Socket</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"socket got closed!~n"</font>); + {<font color="#009900">Error</font>, <font color="#009900">Socket</font>, <font color="#009900">Reason</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"error happened: ~p~n"</font>, [<font color="#009900">Reason</font>]) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>You can easily integrate active sockets with existing Erlang code as all you really need is just a few more clauses when receiving messages.</p> +<h2 id="_sending_files">Sending files</h2> +<p>As in the previous section it is assumed <code>Transport</code> is a valid transport handler and <code>Socket</code> is a connected socket obtained through the listener.</p> +<p>To send a whole file, with name <code>Filename</code>, over a socket:</p> +<div class="listingblock"><div class="title">Sending a file by filename</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Filename</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of bytes and chunks of size <code>ChunkSize</code>:</p> +<div class="listingblock"><div class="title">Sending part of a file by filename in chunks</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><font color="#009900">Opts</font> <font color="#990000">=</font> [{<font color="#FF6600">chunk_size</font>, <font color="#009900">ChunkSize</font>}], +{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Filename</font>, <font color="#009900">Offset</font>, <font color="#009900">Bytes</font>, <font color="#009900">Opts</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>To improve efficiency when sending multiple parts of the same file it is also possible to use a file descriptor opened in raw mode:</p> +<div class="listingblock"><div class="title">Sending a file opened in raw mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">RawFile</font>} <font color="#990000">=</font> <b><font color="#000000">file:open</font></b>(<font color="#009900">Filename</font>, [<font color="#FF6600">raw</font>, <font color="#FF6600">read</font>, <b><font color="#000080">binary</font></b>]), +{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">RawFile</font>, <font color="#009900">Offset</font>, <font color="#009900">Bytes</font>, <font color="#009900">Opts</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_upgrading_a_tcp_socket_to_ssl">Upgrading a TCP socket to SSL</h2> +<p>A connected TCP socket can be upgraded to a SSL socket via the function <code>ranch_ssl:handshake/3</code>. The socket <strong>must</strong> be in <code>{active, false}</code> mode before telling the client that the server is ready to upgrade in order to avoid race conditions.</p> +<p>IMPORTANT: The new socket received from <code>ranch_ssl:handshake/3</code> must be used via the <code>ranch_ssl</code> transport.</p> +<div class="listingblock"><div class="title">Performing a TLS handshake on a TCP socket</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.9 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">SslSocket</font>} <font color="#990000">=</font> <b><font color="#000000">ranch_ssl:handshake</font></b>(<font color="#009900">TcpSocket</font>, <font color="#009900">SslOpts</font>, <font color="#993399">5000</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<h2 id="_writing_a_transport_handler">Writing a transport handler</h2> +<p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. It defines a certain number of callbacks that must be written in order to allow transparent usage of the transport handler.</p> +<p>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 <code>setopts/2</code> function <strong>must</strong> implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p> +<p>If the transport handler doesn't have a native implementation of <code>sendfile/5</code> a fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument is the transport's module. See <code>ranch_ssl</code> for an example.</p> + + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/2.1/guide/listeners/"> + Listeners + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/2.1/guide/protocols/"> + Protocols + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 2.1 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/2.1/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/2.1/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/ranch/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/ranch/1.8/guide">1.8</a></li> + + <li><a href="/docs/en/ranch/1.7/guide">1.7</a></li> + + <li><a href="/docs/en/ranch/1.6/guide">1.6</a></li> + +</ul> + +<h3 id="_like_my_work__donate">Like my work? Donate!</h3> +<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p> + + + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + |