diff options
| author | Loïc Hoguin <[email protected]> | 2016-03-28 15:36:42 +0200 |
|---|---|---|
| committer | Loïc Hoguin <[email protected]> | 2016-03-28 15:36:42 +0200 |
| commit | fe3492a98de29942477b061cd02c92246f4bf85a (patch) | |
| tree | 2255b796a657e6e4dfb72beec1141258d17f1220 /docs/en/ranch | |
| download | ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.tar.gz ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.tar.bz2 ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.zip | |
Initial commit, new website system
Diffstat (limited to 'docs/en/ranch')
26 files changed, 5867 insertions, 0 deletions
diff --git a/docs/en/ranch/1.2/guide/embedded.asciidoc b/docs/en/ranch/1.2/guide/embedded.asciidoc new file mode 100644 index 00000000..593a8079 --- /dev/null +++ b/docs/en/ranch/1.2/guide/embedded.asciidoc @@ -0,0 +1,48 @@ +== Embedded mode + +Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa. + +=== Embedding + +To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the `init/1` function +of one of your application supervisors. + +Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add `ranch_sup` to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener. + +Ranch has a convenience function for getting the listeners child specs +called `ranch:child_spec/6`, that works like `ranch:start_listener/6`, +except that it doesn't start anything, it only returns child specs. + +As for `ranch_sup`, the child spec is simple enough to not require a +convenience function. + +The following example adds both `ranch_sup` and one listener to another +application's supervision tree. + +.Embed Ranch directly in your supervision tree + +[source,erlang] +---- +init([]) -> + RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []}, + permanent, 5000, supervisor, [ranch_sup]}, + ListenerSpec = ranch:child_spec(echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] + ), + {ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}. +---- + +Remember, you can add as many listener child specs as needed, but only +one `ranch_sup` spec! + +It is recommended that your architecture makes sure that all listeners +are restarted if `ranch_sup` fails. See the Ranch internals chapter for +more details on how Ranch does it. diff --git a/docs/en/ranch/1.2/guide/embedded/index.html b/docs/en/ranch/1.2/guide/embedded/index.html new file mode 100644 index 00000000..e8cd3eca --- /dev/null +++ b/docs/en/ranch/1.2/guide/embedded/index.html @@ -0,0 +1,182 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Embedded mode</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="paragraph"><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></div>
+<div class="sect1">
+<h2 id="_embedding">Embedding</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding.
+First, you need to add <code>ranch_sup</code> to your supervision tree, only once,
+regardless of the number of listeners you will use. Then you need to
+add the child specs for each listener.</p></div>
+<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs
+called <code>ranch:child_spec/6</code>, that works like <code>ranch:start_listener/6</code>,
+except that it doesn’t start anything, it only returns child specs.</p></div>
+<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a
+convenience function.</p></div>
+<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another
+application’s supervision tree.</p></div>
+<div class="listingblock">
+<div class="title">Embed Ranch directly in your supervision tree</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>([]) <span style="color: #990000">-></span>
+ <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []},
+ <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]},
+ <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+ ),
+ {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only
+one <code>ranch_sup</code> spec!</p></div>
+<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners
+are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for
+more details on how Ranch does it.</p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/index.html b/docs/en/ranch/1.2/guide/index.html new file mode 100644 index 00000000..cb3d49c1 --- /dev/null +++ b/docs/en/ranch/1.2/guide/index.html @@ -0,0 +1,182 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Ranch User Guide</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="ulist"><ul>
+<li>
+<p>
+<a href="introduction/">Introduction</a>
+</p>
+</li>
+<li>
+<p>
+<a href="listeners/">Listeners</a>
+</p>
+</li>
+<li>
+<p>
+<a href="transports/">Transports</a>
+</p>
+</li>
+<li>
+<p>
+<a href="protocols/">Protocols</a>
+</p>
+</li>
+<li>
+<p>
+<a href="embedded/">Embedded mode</a>
+</p>
+</li>
+<li>
+<p>
+<a href="parsers/">Writing parsers</a>
+</p>
+</li>
+<li>
+<p>
+<a href="ssl_auth/">SSL client authentication</a>
+</p>
+</li>
+<li>
+<p>
+<a href="internals/">Internals</a>
+</p>
+</li>
+</ul></div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/internals.asciidoc b/docs/en/ranch/1.2/guide/internals.asciidoc new file mode 100644 index 00000000..fa63f1d3 --- /dev/null +++ b/docs/en/ranch/1.2/guide/internals.asciidoc @@ -0,0 +1,94 @@ +== Internals + +This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application. + +Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system. + +=== Architecture + +Ranch is an OTP application. + +Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the `ranch_server` process and all the listeners that +will be started. + +The `ranch_server` gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called `ranch_server`. The table is owned by the top supervisor +to improve fault tolerance. This way if the `ranch_server` gen_server +fails, it doesn't lose any information and the restarted process can +continue as if nothing happened. + +Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual `sys` and `supervisor` calls will work on +it as expected. + +Listeners are grouped into the `ranch_listener_sup` supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +`ranch_server` gen_server with varying amount of information. + +All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process. + +=== Number of acceptors + +The second argument to `ranch:start_listener/6` is the number of +processes that will be accepting connections. Care should be taken +when choosing this number. + +First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down. + +Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn't +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however. + +Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it's big enough to always have acceptors ready +and it's low enough that it doesn't have a negative impact on the +system's performances. + +=== Platform-specific TCP features + +Some socket options are platform-specific and not supported by `inet`. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the `raw` option, for which we will see an example. + +One of these features is `TCP_DEFER_ACCEPT` on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process. + +This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections. + +To enable this mechanism, the following option can be used. + +.Using raw transport options + +[source,erlang] +{raw, 6, 9, << 30:32/native >>} + +It means go on layer 6, turn on option 9 with the given integer parameter. diff --git a/docs/en/ranch/1.2/guide/internals/index.html b/docs/en/ranch/1.2/guide/internals/index.html new file mode 100644 index 00000000..bd7610c7 --- /dev/null +++ b/docs/en/ranch/1.2/guide/internals/index.html @@ -0,0 +1,227 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Internals</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="sect1">
+<h2 id="_architecture">Architecture</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch is an OTP application.</p></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_number_of_acceptors">Number of acceptors</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The second argument to <code>ranch:start_listener/6</code> is the number of
+processes that will be accepting connections. Care should be taken
+when choosing this number.</p></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div>
+<div class="listingblock">
+<div class="title">Using raw transport options</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div>
+<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/introduction.asciidoc b/docs/en/ranch/1.2/guide/introduction.asciidoc new file mode 100644 index 00000000..3199fb2f --- /dev/null +++ b/docs/en/ranch/1.2/guide/introduction.asciidoc @@ -0,0 +1,25 @@ +== Introduction + +Ranch is a socket acceptor pool for TCP protocols. + +Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own. + +=== Prerequisites + +It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols. + +=== Supported platforms + +Ranch is tested and supported on Linux. + +Ranch is developed for Erlang R15B01+. + +Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected. + +=== Versioning + +Ranch uses http://semver.org/[Semantic Versioning 2.0.0] diff --git a/docs/en/ranch/1.2/guide/introduction/index.html b/docs/en/ranch/1.2/guide/introduction/index.html new file mode 100644 index 00000000..2a6d275c --- /dev/null +++ b/docs/en/ranch/1.2/guide/introduction/index.html @@ -0,0 +1,166 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Introduction</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div>
+<div class="paragraph"><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></div>
+<div class="sect1">
+<h2 id="_prerequisites">Prerequisites</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience
+with socket programming and TCP protocols.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_supported_platforms">Supported platforms</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch is tested and supported on Linux.</p></div>
+<div class="paragraph"><p>Ranch is developed for Erlang R15B01+.</p></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_versioning">Versioning</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/listeners.asciidoc b/docs/en/ranch/1.2/guide/listeners.asciidoc new file mode 100644 index 00000000..ef2d49c7 --- /dev/null +++ b/docs/en/ranch/1.2/guide/listeners.asciidoc @@ -0,0 +1,251 @@ +== Listeners + +A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the user of transport handlers. + +The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application. + +=== Starting a listener + +Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections. + +A listener can be started and stopped at will. + +When starting a listener, a number of different settings are required: + +* A name to identify it locally and be able to interact with it. +* The number of acceptors in the pool. +* A transport handler and its associated options. +* A protocol handler and its associated options. + +Ranch includes both TCP and SSL transport handlers, respectively +`ranch_tcp` and `ranch_ssl`. + +A listener can be started by calling the `ranch:start_listener/6` +function. Before doing so however, you must ensure that the `ranch` +application is started. + +.Starting the Ranch application + +[source,erlang] +ok = application:start(ranch). + +You are then ready to start a listener. Let's call it `tcp_echo`. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the `echo_protocol` handler. + +.Starting a listener for TCP connections on port 5555 + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] +). + +You can try this out by compiling and running the `tcp_echo` example in the +examples directory. To do so, open a shell in the 'examples/tcp_echo/' +directory and run the following command: + +.Building and starting a Ranch example + +[source,bash] +$ make run + +You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you're done testing, you can use +the `Ctrl+]` key to escape to the telnet command line and type +`quit` to exit. + +.Connecting to the example listener with telnet + +[source,bash] +---- +$ telnet localhost 5555 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +Hello! +Hello! +It works! +It works! +^] + +telnet> quit +Connection closed. +---- + +=== Stopping a listener + +All you need to stop a Ranch listener is to call the +`ranch:stop_listener/1` function with the listener's name +as argument. In the previous section we started the listener +named `tcp_echo`. We can now stop it. + +.Stopping a listener + +[source,erlang] +ranch:stop_listener(tcp_echo). + +=== Default transport options + +By default the socket will be set to return `binary` data, with the +options `{active, false}`, `{packet, raw}`, `{reuseaddr, true}` set. +These values can't be overriden when starting the listener, but +they can be overriden using `Transport:setopts/2` in the protocol. + +It will also set `{backlog, 1024}` and `{nodelay, true}`, which +can be overriden at listener startup. + +=== Listening on a random port + +You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port. + +You can retrieve this port number by calling `ranch:get_port/1`. The +argument is the name of the listener you gave in `ranch:start_listener/6`. + +.Starting a listener for TCP connections on a random port + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 0}], + echo_protocol, [] +). +Port = ranch:get_port(tcp_echo). + +=== Listening on privileged ports + +Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an `{error, eacces}` error when trying +to open a listening socket on such a port. + +The methods for listening on privileged ports vary between systems, +please refer to your system's documentation for more information. + +We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide. + +=== Accepting connections on an existing socket + +If you want to accept connections on an existing socket, you can use the +`socket` transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(`gen_tcp:connect`, `ssl:connect`). The accept function will then be +called on the passed in socket. You should connect the socket in +`{active, false}` mode, as well. + +Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process. + +=== Limiting the number of concurrent connections + +The `max_connections` transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally. + +.Customizing the maximum number of concurrent connections + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}, {max_connections, 100}], + echo_protocol, [] +). + +You can disable this limit by setting its value to the atom `infinity`. + +.Disabling the limit for the number of connections + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, 100, + ranch_tcp, [{port, 5555}, {max_connections, infinity}], + echo_protocol, [] +). + +You may not always want connections to be counted when checking for +`max_connections`. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don't consume +much resources and can safely be removed from the count. + +To remove the connection from the count, you must call the +`ranch:remove_connection/1` from within the connection process, +with the name of the listener as the only argument. + +.Removing a connection from the count of connections + +[source,erlang] +ranch:remove_connection(Ref). + +As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol's `start_link/4` callback. + +You can modify the `max_connections` value on a running listener by +using the `ranch:set_max_connections/2` function, with the name of the +listener as first argument and the new value as the second. + +.Upgrading the maximum number of connections + +[source,erlang] +ranch:set_max_connections(tcp_echo, MaxConns). + +The change will occur immediately. + +=== Using a supervisor for connection processes + +Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a `worker`. +When the `connection_type` configuration value is set to `supervisor`, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree. + +Connection processes of type `supervisor` can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket). + +Instead of returning `{ok, ConnPid}`, simply return +`{ok, SupPid, ConnPid}`. + +It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped. + +=== Upgrading + +Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections. + +To upgrade the protocol options, call `ranch:set_protocol_options/2` +with the name of the listener as first argument and the new options +as the second. + +.Upgrading the protocol options + +[source,erlang] +ranch:set_protocol_options(tcp_echo, NewOpts). + +All future connections will use the new options. + +You can also retrieve the current options similarly by +calling `ranch:get_protocol_options/1`. + +.Retrieving the current protocol options + +[source,erlang] +Opts = ranch:get_protocol_options(tcp_echo). diff --git a/docs/en/ranch/1.2/guide/listeners/index.html b/docs/en/ranch/1.2/guide/listeners/index.html new file mode 100644 index 00000000..638b15af --- /dev/null +++ b/docs/en/ranch/1.2/guide/listeners/index.html @@ -0,0 +1,421 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Listeners</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="paragraph"><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 user of transport handlers.</p></div>
+<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection
+processes, allowing developers to focus on building their application.</p></div>
+<div class="sect1">
+<h2 id="_starting_a_listener">Starting a listener</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer
+to request that Ranch listens for connections.</p></div>
+<div class="paragraph"><p>A listener can be started and stopped at will.</p></div>
+<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+A name to identify it locally and be able to interact with it.
+</p>
+</li>
+<li>
+<p>
+The number of acceptors in the pool.
+</p>
+</li>
+<li>
+<p>
+A transport handler and its associated options.
+</p>
+</li>
+<li>
+<p>
+A protocol handler and its associated options.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively
+<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div>
+<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/6</code>
+function. Before doing so however, you must ensure that the <code>ranch</code>
+application is started.</p></div>
+<div class="listingblock">
+<div class="title">Starting the Ranch application</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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>
+<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.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Building and starting a Ranch example</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make run</tt></pre></div></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Connecting to the example listener with telnet</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ telnet localhost <span style="color: #993399">5555</span>
+Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span>
+Connected to localhost<span style="color: #990000">.</span>
+Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span>
+Hello<span style="color: #990000">!</span>
+Hello<span style="color: #990000">!</span>
+It works<span style="color: #990000">!</span>
+It works<span style="color: #990000">!</span>
+<span style="color: #990000">^]</span>
+
+telnet<span style="color: #990000">></span> quit
+Connection closed<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_stopping_a_listener">Stopping a listener</h2>
+<div class="sectionbody">
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Stopping a listener</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_default_transport_options">Default transport options</h2>
+<div class="sectionbody">
+<div class="paragraph"><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 overriden when starting the listener, but
+they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div>
+<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which
+can be overriden at listener startup.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_listening_on_a_random_port">Listening on a random port</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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/6</code>.</p></div>
+<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.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span>
+<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><p>The methods for listening on privileged ports vary between systems,
+please refer to your system’s documentation for more information.</p></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the
+<code>socket</code> transport option, which should just be the relevant data returned
+from the connect function for the transport or the underlying socket library
+(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be
+called on the passed in socket. You should connect the socket in
+<code>{active, false}</code> mode, as well.</p></div>
+<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an
+SSL listen socket prior to R16. Ranch will catch the error thrown, but the
+owner of the SSL socket will remain as whatever process created the socket.
+However, this will not affect accept behaviour unless the owner process dies,
+in which case the socket is closed. Therefore, to use this feature with SSL
+with an erlang release prior to R16, ensure that the SSL socket is opened in a
+persistant process.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number
+of concurrent connections. It defaults to 1024. Its purpose is to
+prevent your system from being overloaded and ensuring all the
+connections are handled optimally.</p></div>
+<div class="listingblock">
+<div class="title">Customizing the maximum number of concurrent connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div>
+<div class="listingblock">
+<div class="title">Disabling the limit for the number of connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Removing a connection from the count of connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the
+first argument of the protocol’s <code>start_link/4</code> callback.</p></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Upgrading the maximum number of connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The change will occur immediately.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return
+<code>{ok, SupPid, ConnPid}</code>.</p></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_upgrading">Upgrading</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect
+immediately and for all subsequent connections.</p></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Upgrading the protocol options</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>All future connections will use the new options.</p></div>
+<div class="paragraph"><p>You can also retrieve the current options similarly by
+calling <code>ranch:get_protocol_options/1</code>.</p></div>
+<div class="listingblock">
+<div class="title">Retrieving the current protocol options</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/parsers.asciidoc b/docs/en/ranch/1.2/guide/parsers.asciidoc new file mode 100644 index 00000000..9eacbfa9 --- /dev/null +++ b/docs/en/ranch/1.2/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/1.2/guide/parsers/index.html b/docs/en/ranch/1.2/guide/parsers/index.html new file mode 100644 index 00000000..364cd757 --- /dev/null +++ b/docs/en/ranch/1.2/guide/parsers/index.html @@ -0,0 +1,243 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Writing parsers</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="paragraph"><p>There are three kinds of protocols:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Text protocols
+</p>
+</li>
+<li>
+<p>
+Schema-less binary protocols
+</p>
+</li>
+<li>
+<p>
+Schema-based binary protocols
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover
+more advanced topics such as continuations or parser generators.</p></div>
+<div class="paragraph"><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></div>
+<div class="sect1">
+<h2 id="_parsing_text">Parsing text</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t
+do anything with them until we receive the full line.</p></div>
+<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div>
+<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.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
+ [<span style="color: #990000">_</span>] <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>);
+ [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>)
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Using binary:split/3 to split text</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
+ [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>();
+ [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>);
+ [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>)
+ <span style="font-style: italic"><span style="color: #9A1900">%% ...</span></span>
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Pretty simple, right? Match on the command name, get the rest
+of the tokens in variables and call the respective functions.</p></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_parsing_binary">Parsing binary</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><p>The general idea stays the same though.</p></div>
+<div class="listingblock">
+<div class="title">Using binary pattern matching to split frames</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>,
+<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
+ <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>);
+ <span style="color: #990000">_</span> <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>)
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/protocols.asciidoc b/docs/en/ranch/1.2/guide/protocols.asciidoc new file mode 100644 index 00000000..80603432 --- /dev/null +++ b/docs/en/ranch/1.2/guide/protocols.asciidoc @@ -0,0 +1,125 @@ +== Protocols + +A protocol handler starts a connection process and defines the +protocol logic executed in this process. + +=== Writing a protocol handler + +All protocol handlers must implement the `ranch_protocol` behavior +which defines a single callback, `start_link/4`. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to `ranch:start_listener/6`. This callback must +return `{ok, Pid}`, with `Pid` the pid of the new process. + +The newly started process can then freely initialize itself. However, +it must call `ranch:accept_ack/1` before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener's name as argument. + +.Acknowledge accepting the socket + +[source,erlang] +ok = ranch:accept_ack(Ref). + +If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling `ranch:accept_ack/1`. You can use `Transport:setopts/2` +for that purpose. + +Following is the complete protocol code for the example found +in `examples/tcp_echo/`. + +.Protocol module that echoes everything it receives + +[source,erlang] +---- +-module(echo_protocol). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/4]). + +start_link(Ref, Socket, Transport, Opts) -> + Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]), + {ok, Pid}. + +init(Ref, Socket, Transport, _Opts = []) -> + ok = ranch:accept_ack(Ref), + loop(Socket, Transport). + +loop(Socket, Transport) -> + case Transport:recv(Socket, 0, 5000) of + {ok, Data} -> + Transport:send(Socket, Data), + loop(Socket, Transport); + _ -> + ok = Transport:close(Socket) + end. +---- + +=== Using gen_server + +Special processes like the ones that use the `gen_server` or `gen_fsm` +behaviours have the particularity of having their `start_link` call not +return until the `init` function returns. This is problematic, because +you won't be able to call `ranch:accept_ack/1` from the `init` callback +as this would cause a deadlock to happen. + +There are two ways of solving this problem. + +The first, and probably the most elegant one, is to make use of the +`gen_server:enter_loop/3` function. It allows you to start your process +normally (although it must be started with `proc_lib` like all special +processes), then perform any needed operations before falling back into +the normal `gen_server` execution loop. + +.Use a gen_server for protocol handling + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_server). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/4]). +%% Exports of other gen_server callbacks here. + +start_link(Ref, Socket, Transport, Opts) -> + proc_lib:start_link(?MODULE, init, [Ref, Socket, Transport, Opts]). + +init(Ref, Socket, Transport, _Opts = []) -> + ok = proc_lib:init_ack({ok, self()}), + %% Perform any required state initialization here. + ok = ranch:accept_ack(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + gen_server:enter_loop(?MODULE, [], {state, Socket, Transport}). + +%% Other gen_server callbacks here. +---- + +The second method involves triggering a timeout just after `gen_server:init` +ends. If you return a timeout value of `0` then the `gen_server` will call +`handle_info(timeout, _, _)` right away. + +.Use a gen_server for protocol handling, method 2 + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_server). +-behaviour(ranch_protocol). + +%% Exports go here. + +init([Ref, Socket, Transport]) -> + {ok, {state, Ref, Socket, Transport}, 0}. + +handle_info(timeout, State={state, Ref, Socket, Transport}) -> + ok = ranch:accept_ack(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + {noreply, State}; +%% ... +---- diff --git a/docs/en/ranch/1.2/guide/protocols/index.html b/docs/en/ranch/1.2/guide/protocols/index.html new file mode 100644 index 00000000..cd44a06b --- /dev/null +++ b/docs/en/ranch/1.2/guide/protocols/index.html @@ -0,0 +1,263 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Protocols</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="paragraph"><p>A protocol handler starts a connection process and defines the
+protocol logic executed in this process.</p></div>
+<div class="sect1">
+<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior
+which defines a single callback, <code>start_link/4</code>. This callback is
+responsible for spawning a new process for handling the connection.
+It receives four arguments: the name of the listener, the socket, the
+transport handler being used and the protocol options defined in
+the call to <code>ranch:start_listener/6</code>. This callback must
+return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div>
+<div class="paragraph"><p>The newly started process can then freely initialize itself. However,
+it must call <code>ranch:accept_ack/1</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>
+<div class="listingblock">
+<div class="title">Acknowledge accepting the socket</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>If your protocol code requires specific socket options, you should
+set them while initializing your connection process, after
+calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code>
+for that purpose.</p></div>
+<div class="paragraph"><p>Following is the complete protocol code for the example found
+in <code>examples/tcp_echo/</code>.</p></div>
+<div class="listingblock">
+<div class="title">Protocol module that echoes everything it receives</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span>
+<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
+
+<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
+<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
+
+<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
+ <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]),
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span>
+
+<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
+ <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
+ <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span>
+
+<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
+ <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>),
+ <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>);
+ <span style="color: #990000">_</span> <span style="color: #990000">-></span>
+ <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</span>)
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_using_gen_server">Using gen_server</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</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:accept_ack/1</code> from the <code>init</code> callback
+as this would cause a deadlock to happen.</p></div>
+<div class="paragraph"><p>There are two ways of solving this problem.</p></div>
+<div class="paragraph"><p>The first, and probably the most elegant one, is to make use of the
+<code>gen_server:enter_loop/3</code> function. It allows you to start your process
+normally (although it must be started with <code>proc_lib</code> like all special
+processes), then perform any needed operations before falling back into
+the normal <code>gen_server</code> execution loop.</p></div>
+<div class="listingblock">
+<div class="title">Use a gen_server for protocol handling</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
+<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
+<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
+
+<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
+<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
+<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span>
+
+<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">proc_lib:start_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>])<span style="color: #990000">.</span>
+
+<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
+ <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">proc_lib:init_ack</span></span>({<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>()}),
+ <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span>
+ <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
+ <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
+ <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span>
+
+<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div>
+<div class="paragraph"><p>The second method involves triggering a timeout just after <code>gen_server:init</code>
+ends. If you return a timeout value of <code>0</code> then the <code>gen_server</code> will call
+<code>handle_info(timeout, _, _)</code> right away.</p></div>
+<div class="listingblock">
+<div class="title">Use a gen_server for protocol handling, method 2</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
+<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
+<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
+
+<span style="font-style: italic"><span style="color: #9A1900">%% Exports go here.</span></span>
+
+<span style="font-weight: bold"><span style="color: #000000">init</span></span>([<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>]) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">ok</span>, {<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}, <span style="color: #993399">0</span>}<span style="color: #990000">.</span>
+
+<span style="font-weight: bold"><span style="color: #000000">handle_info</span></span>(<span style="color: #FF6600">timeout</span>, <span style="color: #009900">State</span><span style="color: #990000">=</span>{<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}) <span style="color: #990000">-></span>
+ <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
+ <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
+ {<span style="color: #FF6600">noreply</span>, <span style="color: #009900">State</span>};
+<span style="font-style: italic"><span style="color: #9A1900">%% ...</span></span></tt></pre></div></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/ssl_auth.asciidoc b/docs/en/ranch/1.2/guide/ssl_auth.asciidoc new file mode 100644 index 00000000..de0bbaf0 --- /dev/null +++ b/docs/en/ranch/1.2/guide/ssl_auth.asciidoc @@ -0,0 +1,120 @@ +== SSL client authentication + +=== Purpose + +SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security. + +The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate. + +As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of `Transport:name/0`. + +=== Obtaining client certificates + +You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free. + +Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser. + +* Open http://cacert.org in your favorite browser +* Root Certificate link: install both certificates +* Join (Register an account) +* Verify your account (check your email inbox!) +* Log in +* Client Certificates: New +* Follow instructions to create the certificate +* Install the certificate in your browser + +You can optionally save the certificate for later use, for example +to extract the `IssuerID` information as will be detailed later on. + +=== Transport configuration + +The SSL transport does not request a client certificate by default. +You need to specify the `{verify, verify_peer}` option when starting +the listener to enable this behavior. + +.Configure a listener for SSL authentication + +[source,erlang] +{ok, _} = ranch:start_listener(my_ssl, 100, + ranch_ssl, [ + {port, SSLPort}, + {certfile, PathToCertfile}, + {cacertfile, PathToCACertfile}, + {verify, verify_peer} + ], + my_protocol, [] +). + +In this example we set the required `port` and `certfile`, but also +the `cacertfile` containing the CACert.org root certificate, and +the option to request the client certificate. + +If you enable the `{verify, verify_peer}` option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients. + +=== Authentication + +To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly. + +.Retrieve the issuer ID from a certificate + +[source,erlang] +---- +certfile_to_issuer_id(Filename) -> + {ok, Data} = file:read_file(Filename), + [{'Certificate', Cert, not_encrypted}] = public_key:pem_decode(Data), + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID. +---- + +The `IssuerID` variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved. + +To retrieve the `IssuerID` from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the `ssl:peercert/1` function. Once you have the +certificate, you can again use the `public_key:pkix_issuer_id/2` to +extract the `IssuerID` value. + +The following function returns the `IssuerID` or `false` if no client +certificate was found. This snippet is intended to be used from your +protocol code. + +.Retrieve the issuer ID from the certificate for the current connection + +[source,erlang] +---- +socket_to_issuer_id(Socket) -> + case ssl:peercert(Socket) of + {error, no_peercert} -> + false; + {ok, Cert} -> + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID + end. +---- + +You then only need to match the `IssuerID` value to authenticate the +user. diff --git a/docs/en/ranch/1.2/guide/ssl_auth/index.html b/docs/en/ranch/1.2/guide/ssl_auth/index.html new file mode 100644 index 00000000..a1018d85 --- /dev/null +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -0,0 +1,292 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: SSL client authentication</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="sect1">
+<h2 id="_purpose">Purpose</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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 certicate.</p></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Open <a href="http://cacert.org">http://cacert.org</a> in your favorite browser
+</p>
+</li>
+<li>
+<p>
+Root Certificate link: install both certificates
+</p>
+</li>
+<li>
+<p>
+Join (Register an account)
+</p>
+</li>
+<li>
+<p>
+Verify your account (check your email inbox!)
+</p>
+</li>
+<li>
+<p>
+Log in
+</p>
+</li>
+<li>
+<p>
+Client Certificates: New
+</p>
+</li>
+<li>
+<p>
+Follow instructions to create the certificate
+</p>
+</li>
+<li>
+<p>
+Install the certificate in your browser
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_transport_configuration">Transport configuration</h2>
+<div class="sectionbody">
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Configure a listener for SSL authentication</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, <span style="color: #993399">100</span>,
+ <span style="color: #FF6600">ranch_ssl</span>, [
+ {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>},
+ {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>},
+ {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>},
+ {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>}
+ ],
+ <span style="color: #FF6600">my_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_authentication">Authentication</h2>
+<div class="sectionbody">
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Retrieve the issuer ID from a certificate</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>),
+ [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>),
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
+ <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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>
+<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.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</span>) <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
+ {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span>
+ <span style="color: #000080">false</span>;
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span>
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
+ <span style="color: #009900">IssuerID</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You then only need to match the <code>IssuerID</code> value to authenticate the
+user.</p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/guide/transports.asciidoc b/docs/en/ranch/1.2/guide/transports.asciidoc new file mode 100644 index 00000000..91953762 --- /dev/null +++ b/docs/en/ranch/1.2/guide/transports.asciidoc @@ -0,0 +1,169 @@ +== Transports + +A transport defines the interface to interact with a socket. + +Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive. + +=== TCP transport + +The TCP transport is a thin wrapper around `gen_tcp`. + +=== SSL transport + +The SSL transport is a thin wrapper around `ssl`. It requires +the `crypto`, `asn1`, `public_key` and `ssl` applications +to be started. When starting an SSL listener, Ranch will attempt +to automatically start them. It will not try to stop them when +the listener is removed, however. + +.Starting the SSL application + +[source,erlang] +ssl:start(). + +In a proper OTP setting, you will need to make your application +depend on the `crypto`, `public_key` and `ssl` applications. +They will be started automatically when starting your release. + +The SSL transport `accept/2` function performs both transport +and SSL accepts. Errors occurring during the SSL accept phase +are returned as `{error, {ssl_accept, atom()}}` to differentiate +on which socket the problem occurred. + +=== Sending and receiving data + +This section assumes that `Transport` is a valid transport handler +(like `ranch_tcp` or `ranch_ssl`) and `Socket` is a connected +socket obtained through the listener. + +You can send data to a socket by calling the `Transport:send/2` +function. The data can be given as `iodata()`, which is defined as +`binary() | iolist()`. All the following calls will work: + +.Sending data to the socket + +[source,erlang] +---- +Transport:send(Socket, <<"Ranch is cool!">>). +Transport:send(Socket, "Ranch is cool!"). +Transport:send(Socket, ["Ranch", ["is", "cool!"]]). +Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]). +---- + +You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking `Transport:recv/3` call, while +active mode means that you will receive the data as a message. + +By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols. + +Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with `{error, timeout}`. + +The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size. + +.Receiving data from the socket in passive mode + +[source,erlang] +{ok, Data} = Transport:recv(Socket, 0, 5000). + +Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it. + +There are two kinds of active modes: `{active, once}` and +`{active, true}`. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the `{active, true}` mode as it could quickly +flood your process mailbox. It's better to keep the data in the socket +and read it only when required. + +Three different messages can be received: + +* `{OK, Socket, Data}` +* `{Closed, Socket}` +* `{Error, Socket, Reason}` + +The value of `OK`, `Closed` and `Error` can be different +depending on the transport being used. To be able to properly match +on them you must first call the `Transport:messages/0` function. + +.Retrieving the transport's active message identifiers + +[source,erlang] +{OK, Closed, Error} = Transport:messages(). + +To start receiving messages you will need to call the `Transport:setopts/2` +function, and do so every time you want to receive data. + +.Receiving messages from the socket in active mode + +[source,erlang] +---- +{OK, Closed, Error} = Transport:messages(), +Transport:setopts(Socket, [{active, once}]), +receive + {OK, Socket, Data} -> + io:format("data received: ~p~n", [Data]); + {Closed, Socket} -> + io:format("socket got closed!~n"); + {Error, Socket, Reason} -> + io:format("error happened: ~p~n", [Reason]) +end. +---- + +You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages. + +=== Sending files + +As in the previous section it is assumed `Transport` is a valid transport +handler and `Socket` is a connected socket obtained through the listener. + +To send a whole file, with name `Filename`, over a socket: + +.Sending a file by filename + +[source,erlang] +{ok, SentBytes} = Transport:sendfile(Socket, Filename). + +Or part of a file, with `Offset` greater than or equal to 0, `Bytes` number of +bytes and chunks of size `ChunkSize`: + +.Sending part of a file by filename in chunks + +[source,erlang] +Opts = [{chunk_size, ChunkSize}], +{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts). + +To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode: + +.Sending a file opened in raw mode + +[source,erlang] +{ok, RawFile} = file:open(Filename, [raw, read, binary]), +{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts). + +=== Writing a transport handler + +A transport handler is a module implementing the `ranch_transport` behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler. + +The behavior doesn't define the socket options available when opening a +socket. These do not need to be common to all transports as it's easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The `setopts/2` function *must* +implement the `{active, once}` and the `{active, true}` options. + +If the transport handler doesn't have a native implementation of `sendfile/5` a +fallback is available, `ranch_transport:sendfile/6`. The extra first argument +is the transport's module. See `ranch_ssl` for an example. diff --git a/docs/en/ranch/1.2/guide/transports/index.html b/docs/en/ranch/1.2/guide/transports/index.html new file mode 100644 index 00000000..a3ce9983 --- /dev/null +++ b/docs/en/ranch/1.2/guide/transports/index.html @@ -0,0 +1,323 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Transports</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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> + +<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div>
+<div class="paragraph"><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></div>
+<div class="sect1">
+<h2 id="_tcp_transport">TCP transport</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_ssl_transport">SSL transport</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>. It requires
+the <code>crypto</code>, <code>asn1</code>, <code>public_key</code> and <code>ssl</code> applications
+to be started. When starting an SSL listener, Ranch will attempt
+to automatically start them. It will not try to stop them when
+the listener is removed, however.</p></div>
+<div class="listingblock">
+<div class="title">Starting the SSL application</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ssl:start</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>In a proper OTP setting, you will need to make your application
+depend on the <code>crypto</code>, <code>public_key</code> and <code>ssl</code> applications.
+They will be started automatically when starting your release.</p></div>
+<div class="paragraph"><p>The SSL transport <code>accept/2</code> function performs both transport
+and SSL accepts. Errors occurring during the SSL accept phase
+are returned as <code>{error, {ssl_accept, atom()}}</code> to differentiate
+on which socket the problem occurred.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_sending_and_receiving_data">Sending and receiving data</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Sending data to the socket</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span>
+<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span>
+<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span>
+<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Receiving data from the socket in passive mode</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and
+<code>{active, true}</code>. The first will send a single message before going
+back to passive mode; the second 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></div>
+<div class="paragraph"><p>Three different messages can be received:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<code>{OK, Socket, Data}</code>
+</p>
+</li>
+<li>
+<p>
+<code>{Closed, Socket}</code>
+</p>
+</li>
+<li>
+<p>
+<code>{Error, Socket, Reason}</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</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>
+<div class="listingblock">
+<div class="title">Retrieving the transport’s active message identifiers</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #009900">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Receiving messages from the socket in active mode</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #009900">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(),
+<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
+<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span>
+ {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]);
+ {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>);
+ {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
+ <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</span>, [<span style="color: #009900">Reason</span>])
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_sending_files">Sending files</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div>
+<div class="listingblock">
+<div class="title">Sending a file by filename</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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>
+<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.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}],
+{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><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>
+<div class="listingblock">
+<div class="title">Sending a file opened in raw mode</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]),
+{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_writing_a_transport_handler">Writing a transport handler</h2>
+<div class="sectionbody">
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+<div class="paragraph"><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></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/index.html b/docs/en/ranch/1.2/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/ranch/1.2/index.html @@ -0,0 +1 @@ +<!DOCTYPE html><html><head><link rel="canonical" href="http://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0;url=http://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/ranch/1.2/manual/index.html b/docs/en/ranch/1.2/manual/index.html new file mode 100644 index 00000000..339f6643 --- /dev/null +++ b/docs/en/ranch/1.2/manual/index.html @@ -0,0 +1,172 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: Ranch Function Reference</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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 Function Reference</span></h1> + +<div class="ulist"><ul>
+<li>
+<p>
+<a href="ranch_app">ranch(7)</a>
+</p>
+</li>
+<li>
+<p>
+<a href="ranch">ranch(3)</a>
+</p>
+</li>
+<li>
+<p>
+<a href="ranch_protocol">ranch_protocol(3)</a>
+</p>
+</li>
+<li>
+<p>
+<a href="ranch_ssl">ranch_ssl(3)</a>
+</p>
+</li>
+<li>
+<p>
+<a href="ranch_tcp">ranch_tcp(3)</a>
+</p>
+</li>
+<li>
+<p>
+<a href="ranch_transport">ranch_transport(3)</a>
+</p>
+</li>
+</ul></div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/manual/ranch/index.html b/docs/en/ranch/1.2/manual/ranch/index.html new file mode 100644 index 00000000..bdec4cca --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch/index.html @@ -0,0 +1,557 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: ranch(3)</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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(3)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>ranch - socket acceptor pool</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">Description</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and
+manipulating Ranch listeners.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_types">Types</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3>
+<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div>
+<div class="paragraph"><p>This is a soft limit. The actual number of connections
+might be slightly above the limit due to concurrency
+when accepting new connections. Some connections may
+also be removed from this count explicitly by the user
+code.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_opt">opt()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
+ | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>}
+ | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()}
+ | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>}
+ | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
+<div class="paragraph"><p>Ranch-specific transport options.</p></div>
+<div class="paragraph"><p>These options are not passed on to the transports.
+They are used by Ranch while setting up the listeners.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_ref_any">ref() = any()</h3>
+<div class="paragraph"><p>Unique name used to refer to a listener.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_option_descriptions">Option descriptions</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>None of the options are required.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+ack_timeout (5000)
+</dt>
+<dd>
+<p>
+ Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish.
+</p>
+</dd>
+<dt class="hdlist1">
+connection_type (worker)
+</dt>
+<dd>
+<p>
+ Type of process that will handle the connection.
+</p>
+</dd>
+<dt class="hdlist1">
+max_connections (1024)
+</dt>
+<dd>
+<p>
+ Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely.
+</p>
+</dd>
+<dt class="hdlist1">
+shutdown (5000)
+</dt>
+<dd>
+<p>
+ Maximum allowed time for children to stop on listener shutdown.
+</p>
+</dd>
+<dt class="hdlist1">
+socket
+</dt>
+<dd>
+<p>
+ Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>.
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_exports">Exports</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div>
+<div class="paragraph"><p>This function MUST be used by a connection process to inform
+Ranch that it initialized properly and let it perform any
+additional operations before the socket can be safely used.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_child_spec_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+NbAcceptors = non_neg_integer()
+</dt>
+<dd>
+<p>
+Number of acceptor processes.
+</p>
+</dd>
+<dt class="hdlist1">
+Transport = module()
+</dt>
+<dd>
+<p>
+Transport module.
+</p>
+</dd>
+<dt class="hdlist1">
+TransOpts = any()
+</dt>
+<dd>
+<p>
+Transport options.
+</p>
+</dd>
+<dt class="hdlist1">
+Protocol = module()
+</dt>
+<dd>
+<p>
+Protocol module.
+</p>
+</dd>
+<dt class="hdlist1">
+ProtoOpts = any()
+</dt>
+<dd>
+<p>
+Protocol options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return child specifications for a new listener.</p></div>
+<div class="paragraph"><p>This function can be used to embed a listener directly
+in an application instead of letting Ranch handle it.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+IP = inet:ip_address()
+</dt>
+<dd>
+<p>
+IP of the interface used by this listener.
+</p>
+</dd>
+<dt class="hdlist1">
+Port = inet:port_number()
+</dt>
+<dd>
+<p>
+Port number used by this listener.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+MaxConns = max_conns()
+</dt>
+<dd>
+<p>
+Current maximum number of connections.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+Port = inet:port_number()
+</dt>
+<dd>
+<p>
+Port number used by this listener.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the port for the given listener.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+ProtoOpts = any()
+</dt>
+<dd>
+<p>
+Current protocol options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div>
+<div class="paragraph"><p>You can use this function for long-running connection processes
+which spend most of their time idling rather than consuming
+resources. This allows Ranch to accept a lot more connections
+without sacrificing the latency of the system.</p></div>
+<div class="paragraph"><p>This function may only be called from a connection process.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+MaxConns = max_conns()
+</dt>
+<dd>
+<p>
+New maximum number of connections.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div>
+<div class="paragraph"><p>The change will be applied immediately. If the new value is
+smaller than the previous one, Ranch will not kill the extra
+connections, but will wait for them to terminate properly.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+ProtoOpts = any()
+</dt>
+<dd>
+<p>
+New protocol options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Set the protocol options for the given listener.</p></div>
+<div class="paragraph"><p>The change will be applied immediately for all new connections.
+Old connections will not receive the new options.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_start_listener_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+NbAcceptors = non_neg_integer()
+</dt>
+<dd>
+<p>
+Number of acceptor processes.
+</p>
+</dd>
+<dt class="hdlist1">
+Transport = module()
+</dt>
+<dd>
+<p>
+Transport module.
+</p>
+</dd>
+<dt class="hdlist1">
+TransOpts = any()
+</dt>
+<dd>
+<p>
+Transport options.
+</p>
+</dd>
+<dt class="hdlist1">
+Protocol = module()
+</dt>
+<dd>
+<p>
+Protocol module.
+</p>
+</dd>
+<dt class="hdlist1">
+ProtoOpts = any()
+</dt>
+<dd>
+<p>
+Protocol options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Start listening for connections using the given transport
+and protocol. Returns the pid for this listener’s supervisor.</p></div>
+<div class="paragraph"><p>There are additional transport options that apply
+regardless of transport. They allow configuring how the
+connections are supervised, rate limited and more. Please
+consult the previous section for more details.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Stop the given listener.</p></div>
+<div class="paragraph"><p>The listener is stopped gracefully, first by closing the
+listening port, then by stopping the connection processes.
+These processes are stopped according to the <code>shutdown</code>
+transport option, which may be set to brutally kill all
+connection processes or give them some time to stop properly.</p></div>
+<div class="paragraph"><p>This function does not return until the listener is
+completely stopped.</p></div>
+</div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/manual/ranch_app/index.html b/docs/en/ranch/1.2/manual/ranch_app/index.html new file mode 100644 index 00000000..ac3ffd08 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_app/index.html @@ -0,0 +1,177 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: ranch(7)</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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(7)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_dependencies">Dependencies</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>ranch</code> application has no particular dependency required
+to start.</p></div>
+<div class="paragraph"><p>It has optional dependencies that are only required when
+listening for SSL connections. The dependencies are <code>crypto</code>,
+<code>asn1</code>, <code>public_key</code> and <code>ssl</code>. They are started automatically
+if they weren’t before.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_environment">Environment</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>ranch</code> application defines one application environment
+configuration parameter.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+profile (false)
+</dt>
+<dd>
+<p>
+ When enabled, Ranch will start <code>eprof</code> profiling automatically.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop
+profiling and output the results to the files <em>procs.profile</em>
+and <em>total.profile</em>. Do not use in production.</p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/manual/ranch_protocol/index.html b/docs/en/ranch/1.2/manual/ranch_protocol/index.html new file mode 100644 index 00000000..aa0001c6 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_protocol/index.html @@ -0,0 +1,217 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: ranch_protocol(3)</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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_protocol(3)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">Description</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used
+by Ranch protocols.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_types">Types</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>None.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_callbacks">Callbacks</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Ref = ranch:ref()
+</dt>
+<dd>
+<p>
+Listener name.
+</p>
+</dd>
+<dt class="hdlist1">
+Socket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+Transport = module()
+</dt>
+<dd>
+<p>
+Transport module for this socket.
+</p>
+</dd>
+<dt class="hdlist1">
+ProtoOpts = any()
+</dt>
+<dd>
+<p>
+Protocol options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Start a new connection process for the given socket.</p></div>
+<div class="paragraph"><p>The only purpose of this callback is to start a process that
+will handle the socket. It must spawn the process, link and
+then return the new pid. This function will always be called
+from inside a supervisor.</p></div>
+<div class="paragraph"><p>This callback can also return two pids. The first pid is the
+pid of the process that will be supervised. The second pid is
+the pid of the process that will receive ownership of the
+socket. This second process must be a child of the first. This
+form is only available when <code>connection_type</code> is set to
+<code>supervisor</code>.</p></div>
+<div class="paragraph"><p>If any other value is returned, the supervisor will close the
+socket and assume no process has been started.</p></div>
+<div class="paragraph"><p>Do not perform any operations in this callback, as this would
+block the supervisor responsible for starting connection
+processes and degrade performance severely.</p></div>
+</div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html new file mode 100644 index 00000000..2c0ef14f --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -0,0 +1,483 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: ranch_ssl(3)</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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_ssl(3)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">Description</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_types">Types</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_ssl_opt">ssl_opt()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
+ | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
+ | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]}
+ | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
+ | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
+ | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
+ | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}}
+ | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>}
+ | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>}
+ | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
+ | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
+ | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>}
+ | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}}
+ | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
+ | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
+ | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)}
+ | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
+ | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
+ | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
+ | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
+ | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]}
+ | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
+ | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()}
+ | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
+ | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>SSL-specific listen options.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3>
+<div class="paragraph"><p>Listen options.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_opts_opt">opts() = [opt()]</h3>
+<div class="paragraph"><p>List of listen options.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_option_descriptions">Option descriptions</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code>
+or the <code>certfile</code> option. None of the other options are required.</p></div>
+<div class="paragraph"><p>The default value is given next to the option name.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+alpn_preferred_protocols
+</dt>
+<dd>
+<p>
+ Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.
+</p>
+</dd>
+<dt class="hdlist1">
+cacertfile
+</dt>
+<dd>
+<p>
+ Path to PEM encoded trusted certificates file used to verify peer certificates.
+</p>
+</dd>
+<dt class="hdlist1">
+cacerts
+</dt>
+<dd>
+<p>
+ List of DER encoded trusted certificates.
+</p>
+</dd>
+<dt class="hdlist1">
+cert
+</dt>
+<dd>
+<p>
+ DER encoded user certificate.
+</p>
+</dd>
+<dt class="hdlist1">
+certfile
+</dt>
+<dd>
+<p>
+ Path to the PEM encoded user certificate file. May also contain the private key.
+</p>
+</dd>
+<dt class="hdlist1">
+ciphers
+</dt>
+<dd>
+<p>
+ List of ciphers that clients are allowed to use.
+</p>
+</dd>
+<dt class="hdlist1">
+client_renegotiation (true)
+</dt>
+<dd>
+<p>
+ Whether to allow client-initiated renegotiation.
+</p>
+</dd>
+<dt class="hdlist1">
+crl_cache ({ssl_crl_cache, {internal, []}})
+</dt>
+<dd>
+<p>
+ Customize the module used to cache Certificate Revocation Lists.
+</p>
+</dd>
+<dt class="hdlist1">
+crl_check (false)
+</dt>
+<dd>
+<p>
+ Whether to perform CRL check on all certificates in the chain during validation.
+</p>
+</dd>
+<dt class="hdlist1">
+depth (1)
+</dt>
+<dd>
+<p>
+ Maximum of intermediate certificates allowed in the certification path.
+</p>
+</dd>
+<dt class="hdlist1">
+dh
+</dt>
+<dd>
+<p>
+ DER encoded Diffie-Hellman parameters.
+</p>
+</dd>
+<dt class="hdlist1">
+dhfile
+</dt>
+<dd>
+<p>
+ Path to the PEM encoded Diffie-Hellman parameters file.
+</p>
+</dd>
+<dt class="hdlist1">
+fail_if_no_peer_cert (false)
+</dt>
+<dd>
+<p>
+ Whether to refuse the connection if the client sends an empty certificate.
+</p>
+</dd>
+<dt class="hdlist1">
+hibernate_after (undefined)
+</dt>
+<dd>
+<p>
+ Time in ms after which SSL socket processes go into hibernation to reduce memory usage.
+</p>
+</dd>
+<dt class="hdlist1">
+honor_cipher_order (false)
+</dt>
+<dd>
+<p>
+ If true, use the server’s preference for cipher selection. If false, use the client’s preference.
+</p>
+</dd>
+<dt class="hdlist1">
+key
+</dt>
+<dd>
+<p>
+ DER encoded user private key.
+</p>
+</dd>
+<dt class="hdlist1">
+keyfile
+</dt>
+<dd>
+<p>
+ Path to the PEM encoded private key file, if different than the certfile.
+</p>
+</dd>
+<dt class="hdlist1">
+log_alert (true)
+</dt>
+<dd>
+<p>
+ If false, error reports will not be displayed.
+</p>
+</dd>
+<dt class="hdlist1">
+next_protocols_advertised
+</dt>
+<dd>
+<p>
+ List of protocols to send to the client if it supports the Next Protocol extension.
+</p>
+</dd>
+<dt class="hdlist1">
+nodelay (true)
+</dt>
+<dd>
+<p>
+ Whether to enable TCP_NODELAY.
+</p>
+</dd>
+<dt class="hdlist1">
+partial_chain
+</dt>
+<dd>
+<p>
+ Claim an intermediate CA in the chain as trusted.
+</p>
+</dd>
+<dt class="hdlist1">
+password
+</dt>
+<dd>
+<p>
+ Password to the private key file, if password protected.
+</p>
+</dd>
+<dt class="hdlist1">
+psk_identity
+</dt>
+<dd>
+<p>
+ Provide the given PSK identity hint to the client during the handshake.
+</p>
+</dd>
+<dt class="hdlist1">
+reuse_session
+</dt>
+<dd>
+<p>
+ Custom policy to decide whether a session should be reused.
+</p>
+</dd>
+<dt class="hdlist1">
+reuse_sessions (false)
+</dt>
+<dd>
+<p>
+ Whether to allow session reuse.
+</p>
+</dd>
+<dt class="hdlist1">
+secure_renegotiate (false)
+</dt>
+<dd>
+<p>
+ Whether to reject renegotiation attempts that do not conform to RFC5746.
+</p>
+</dd>
+<dt class="hdlist1">
+sni_fun
+</dt>
+<dd>
+<p>
+ Function called when the client requests a host using Server Name Indication. Returns options to apply.
+</p>
+</dd>
+<dt class="hdlist1">
+sni_hosts
+</dt>
+<dd>
+<p>
+ Options to apply for the host that matches what the client requested with Server Name Indication.
+</p>
+</dd>
+<dt class="hdlist1">
+user_lookup_fun
+</dt>
+<dd>
+<p>
+ Function called to determine the shared secret when using PSK, or provide parameters when using SRP.
+</p>
+</dd>
+<dt class="hdlist1">
+verify (verify_none)
+</dt>
+<dd>
+<p>
+ Use <code>verify_peer</code> to request a certificate from the client.
+</p>
+</dd>
+<dt class="hdlist1">
+verify_fun
+</dt>
+<dd>
+<p>
+ Custom policy to decide whether a client certificate is valid.
+</p>
+</dd>
+<dt class="hdlist1">
+versions
+</dt>
+<dd>
+<p>
+ TLS protocol versions that will be supported.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Note that the client will not send a certificate unless the
+value for the <code>verify</code> option is set to <code>verify_peer</code>. This
+means that the <code>fail_if_no_peer_cert</code> only apply when combined
+with the <code>verify</code> option. The <code>verify_fun</code> option allows
+greater control over the client certificate validation.</p></div>
+<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_exports">Exports</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>None.</p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/manual/ranch_tcp/index.html b/docs/en/ranch/1.2/manual/ranch_tcp/index.html new file mode 100644 index 00000000..845e3022 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_tcp/index.html @@ -0,0 +1,408 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: ranch_tcp(3)</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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_tcp(3)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">Description</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div>
+<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is
+recommended to disable async threads when using the
+<code>sendfile</code> function of this transport, as it can make
+the threads stuck indefinitely.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_types">Types</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_opt">opt()</h3>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | <span style="color: #FF6600">inet</span>
+ | <span style="color: #FF6600">inet6</span>
+ | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()}
+ | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}}
+ | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
+ | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}
+ | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
+ | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
+ | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
+ | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
+ | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div>
+<div class="paragraph"><p>Listen options.</p></div>
+<div class="paragraph"><p>This does not represent the entirety of the options that can
+be set on the socket, but only the options that may be
+set independently of protocol implementation.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_opts_opt">opts() = [opt()]</h3>
+<div class="paragraph"><p>List of listen options.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_option_descriptions">Option descriptions</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>None of the options are required.</p></div>
+<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more
+thorough description of these options. This manual only aims
+to provide a short description along with what the defaults
+are. Defaults may be different in Ranch compared to <code>gen_tcp</code>.
+Defaults are given next to the option name.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+backlog (1024)
+</dt>
+<dd>
+<p>
+ Max length of the queue of pending connections.
+</p>
+</dd>
+<dt class="hdlist1">
+buffer
+</dt>
+<dd>
+<p>
+ Size of the buffer used by the Erlang driver. Default is system-dependent.
+</p>
+</dd>
+<dt class="hdlist1">
+delay_send (false)
+</dt>
+<dd>
+<p>
+ Always queue packets before sending, to send fewer, larger packets over the network.
+</p>
+</dd>
+<dt class="hdlist1">
+dontroute (false)
+</dt>
+<dd>
+<p>
+ Don’t send via a gateway, only send to directly connected hosts.
+</p>
+</dd>
+<dt class="hdlist1">
+exit_on_close (true)
+</dt>
+<dd>
+<p>
+ Disable to allow sending data after a close has been detected.
+</p>
+</dd>
+<dt class="hdlist1">
+fd
+</dt>
+<dd>
+<p>
+ File descriptor of the socket, if it was opened externally.
+</p>
+</dd>
+<dt class="hdlist1">
+high_msgq_watermark (8192)
+</dt>
+<dd>
+<p>
+ Limit in the amount of data in the socket message queue before the socket queue becomes busy.
+</p>
+</dd>
+<dt class="hdlist1">
+high_watermark (8192)
+</dt>
+<dd>
+<p>
+ Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy.
+</p>
+</dd>
+<dt class="hdlist1">
+inet
+</dt>
+<dd>
+<p>
+ Set up the socket for IPv4.
+</p>
+</dd>
+<dt class="hdlist1">
+inet6
+</dt>
+<dd>
+<p>
+ Set up the socket for IPv6.
+</p>
+</dd>
+<dt class="hdlist1">
+ip
+</dt>
+<dd>
+<p>
+ Interface to listen on. Listen on all interfaces by default.
+</p>
+</dd>
+<dt class="hdlist1">
+keepalive (false)
+</dt>
+<dd>
+<p>
+ Enable sending of keep-alive messages.
+</p>
+</dd>
+<dt class="hdlist1">
+linger ({false, 0})
+</dt>
+<dd>
+<p>
+ Whether to wait and how long to flush data sent before closing the socket.
+</p>
+</dd>
+<dt class="hdlist1">
+low_msgq_watermark (4096)
+</dt>
+<dd>
+<p>
+ Amount of data in the socket message queue before the socket queue leaves busy state.
+</p>
+</dd>
+<dt class="hdlist1">
+low_watermark (4096)
+</dt>
+<dd>
+<p>
+ Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state.
+</p>
+</dd>
+<dt class="hdlist1">
+nodelay (true)
+</dt>
+<dd>
+<p>
+ Whether to enable TCP_NODELAY.
+</p>
+</dd>
+<dt class="hdlist1">
+port (0)
+</dt>
+<dd>
+<p>
+ TCP port number to listen on. 0 means a random port will be used.
+</p>
+</dd>
+<dt class="hdlist1">
+priority (0)
+</dt>
+<dd>
+<p>
+ Priority value for all packets to be sent by this socket.
+</p>
+</dd>
+<dt class="hdlist1">
+recbuf
+</dt>
+<dd>
+<p>
+ Minimum size of the socket’s receive buffer. Default is system-dependent.
+</p>
+</dd>
+<dt class="hdlist1">
+send_timeout (30000)
+</dt>
+<dd>
+<p>
+ How long the send call may wait for confirmation before returning.
+</p>
+</dd>
+<dt class="hdlist1">
+send_timeout_close (true)
+</dt>
+<dd>
+<p>
+ Whether to close the socket when the confirmation wasn’t received.
+</p>
+</dd>
+<dt class="hdlist1">
+sndbuf
+</dt>
+<dd>
+<p>
+ Minimum size of the socket’s send buffer. Default is system-dependent.
+</p>
+</dd>
+<dt class="hdlist1">
+tos
+</dt>
+<dd>
+<p>
+ Value for the IP_TOS IP level option. Use with caution.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific
+options by specifying the protocol level, the option number and
+the actual option value specified as a binary. This option is not
+portable. Use with caution.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_exports">Exports</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>None.</p></div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.2/manual/ranch_transport/index.html b/docs/en/ranch/1.2/manual/ranch_transport/index.html new file mode 100644 index 00000000..40b22b39 --- /dev/null +++ b/docs/en/ranch/1.2/manual/ranch_transport/index.html @@ -0,0 +1,628 @@ +<!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"> + + <meta name="generator" content="Hugo 0.15" /> + + <title>Nine Nines: ranch_transport(3)</title> + + <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + + <link href="/css/bootstrap.min.css" rel="stylesheet"> + <link href="/css/99s.css" 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="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></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_transport(3)</span></h1> + +<div class="sect1">
+<h2 id="_name">Name</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">Description</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used
+by Ranch transports.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_types">Types</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3>
+<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div>
+<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_callbacks">Callbacks</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+LSocket = CSocket = any()
+</dt>
+<dd>
+<p>
+Listening socket.
+</p>
+</dd>
+<dt class="hdlist1">
+Timeout = timeout()
+</dt>
+<dd>
+<p>
+Accept timeout.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div>
+<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket
+after accepting the connection. This is most useful when the
+transport is not raw TCP, like with SSL for example.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+Timeout = timeout()
+</dt>
+<dd>
+<p>
+Ack timeout.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div>
+<div class="paragraph"><p>This function will be called by connection processes
+before performing any socket operation. It allows
+transports that require extra initialization to perform
+their task and make the socket ready to use.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Socket = any()
+</dt>
+<dd>
+<p>
+Socket opened with listen/1 or accept/2.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Close the given socket.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Socket = any()
+</dt>
+<dd>
+<p>
+Socket opened with listen/1 or accept/2.
+</p>
+</dd>
+<dt class="hdlist1">
+Pid = pid()
+</dt>
+<dd>
+<p>
+Pid of the new owner of the socket.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Change the controlling process for the given socket.</p></div>
+<div class="paragraph"><p>The controlling process is the process that is allowed to
+perform operations on the socket, and that will receive
+messages from the socket when active mode is used. When
+the controlling process dies, the socket is closed.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+TransOpts = any()
+</dt>
+<dd>
+<p>
+Transport options.
+</p>
+</dd>
+<dt class="hdlist1">
+LSocket = any()
+</dt>
+<dd>
+<p>
+Listening socket.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Listen for connections on the given port.</p></div>
+<div class="paragraph"><p>The port is given as part of the transport options under
+the key <code>port</code>. Any other option is transport dependent.</p></div>
+<div class="paragraph"><p>The socket returned by this call can then be used to
+accept connections. It is not possible to send or receive
+data from the listening socket.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+OK = Closed = Error = atom()
+</dt>
+<dd>
+<p>
+Tuple names.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_name_8594_name">name() → Name</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Name = atom()
+</dt>
+<dd>
+<p>
+Transport module name.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the name of the transport.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+IP = inet:ip_address()
+</dt>
+<dd>
+<p>
+IP of the remote endpoint.
+</p>
+</dd>
+<dt class="hdlist1">
+Port = inet:port_number()
+</dt>
+<dd>
+<p>
+Port of the remote endpoint.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+Length = non_neg_integer()
+</dt>
+<dd>
+<p>
+Requested length.
+</p>
+</dd>
+<dt class="hdlist1">
+Timeout = timeout()
+</dt>
+<dd>
+<p>
+Receive timeout.
+</p>
+</dd>
+<dt class="hdlist1">
+Packet = iodata() | any()
+</dt>
+<dd>
+<p>
+Data received.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div>
+<div class="paragraph"><p>Trying to receive data from a socket that is in active mode
+will return an error.</p></div>
+<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div>
+<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>,
+this is highly discouraged as this could cause your process
+to get stuck waiting for data that will never come. This may
+happen when a socket becomes half-open due to a crash of the
+remote endpoint. Wi-Fi going down is another common culprit
+of this issue.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+Packet = iodata()
+</dt>
+<dd>
+<p>
+Data to be sent.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Send data to the given socket.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3>
+<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3>
+<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+File = file:filename_all() | file:fd()
+</dt>
+<dd>
+<p>
+Filename or file descriptor for the file to be sent.
+</p>
+</dd>
+<dt class="hdlist1">
+Offset = non_neg_integer()
+</dt>
+<dd>
+<p>
+Begin sending at this position in the file.
+</p>
+</dd>
+<dt class="hdlist1">
+Bytes = non_neg_integer()
+</dt>
+<dd>
+<p>
+Send this many bytes.
+</p>
+</dd>
+<dt class="hdlist1">
+SentBytes = non_neg_integer()
+</dt>
+<dd>
+<p>
+This many bytes were sent.
+</p>
+</dd>
+<dt class="hdlist1">
+SfOpts = sendfile_opts()
+</dt>
+<dd>
+<p>
+Sendfile options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
+<div class="paragraph"><p>The file may be sent full or in parts, and may be specified
+by its filename or by an already open file descriptor.</p></div>
+<div class="paragraph"><p>Transports that manipulate TCP directly may use the
+<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile
+syscall where applicable (on Linux, for example). Other
+transports can use the <code>sendfile/6</code> function exported from
+this module.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+SockOpts = any()
+</dt>
+<dd>
+<p>
+Socket options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Change options for the given socket.</p></div>
+<div class="paragraph"><p>This is mainly useful for switching to active or passive mode
+or to set protocol-specific options.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+How = read | write | read_write
+</dt>
+<dd>
+<p>
+Which side(s) of the socket to close.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Socket = any()
+</dt>
+<dd>
+<p>
+Socket opened with listen/1 or accept/2.
+</p>
+</dd>
+<dt class="hdlist1">
+IP = inet:ip_address()
+</dt>
+<dd>
+<p>
+IP of the local endpoint.
+</p>
+</dd>
+<dt class="hdlist1">
+Port = inet:port_number()
+</dt>
+<dd>
+<p>
+Port of the local endpoint.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_exports">Exports</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Transport = module()
+</dt>
+<dd>
+<p>
+Transport module for this socket.
+</p>
+</dd>
+<dt class="hdlist1">
+CSocket = any()
+</dt>
+<dd>
+<p>
+Socket for this connection.
+</p>
+</dd>
+<dt class="hdlist1">
+File = file:filename_all() | file:fd()
+</dt>
+<dd>
+<p>
+Filename or file descriptor for the file to be sent.
+</p>
+</dd>
+<dt class="hdlist1">
+Offset = non_neg_integer()
+</dt>
+<dd>
+<p>
+Begin sending at this position in the file.
+</p>
+</dd>
+<dt class="hdlist1">
+Bytes = non_neg_integer()
+</dt>
+<dd>
+<p>
+Send this many bytes.
+</p>
+</dd>
+<dt class="hdlist1">
+SentBytes = non_neg_integer()
+</dt>
+<dd>
+<p>
+This many bytes were sent.
+</p>
+</dd>
+<dt class="hdlist1">
+SfOpts = sendfile_opts()
+</dt>
+<dd>
+<p>
+Sendfile options.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
+<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code>
+and may be used when transports are not manipulating TCP
+directly.</p></div>
+</div>
+</div>
+</div>
+ + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.2 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.2/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.2/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</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-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script> + <script src="/js/bootstrap-carousel.js"></script> + <script src="/js/bootstrap-dropdown.js"></script> + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/index.html b/docs/en/ranch/index.html new file mode 100644 index 00000000..c1eedb2f --- /dev/null +++ b/docs/en/ranch/index.html @@ -0,0 +1 @@ +<!DOCTYPE html><html><head><link rel="canonical" href="http://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0;url=http://ninenines.eu/docs/" /></head></html>
\ No newline at end of file |